Merge remote-tracking branch 'upstream/master'

Author: usefulcat

.github/workflows/intelllvm.yml

@@ -0,0 +1,78 @@
+name: intelllvm
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+on:
+  push:
+    branches:
+      - master
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'scripts/**'
+  pull_request:
+    branches:
+      - master
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'scripts/**'
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        build_type: [ Debug, Release ]
+        std: [ 17 ]
+        with_tests: [ ON ]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Intel oneAPI DPC++ Compiler 2025.2.1
+        run: |
+          wget -qO- https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB | sudo tee /etc/apt/trusted.gpg.d/GPG-PUB-KEY-INTEL-SW-PRODUCTS.asc
+          echo "deb https://apt.repos.intel.com/oneapi all main" | sudo tee /etc/apt/sources.list.d/oneAPI.list
+          sudo apt-get update
+          sudo apt-get install -y intel-oneapi-compiler-dpcpp-cpp cmake make
+
+      - name: Setup Intel oneAPI environment
+        shell: bash
+        run: |
+          source /opt/intel/oneapi/setvars.sh
+          # Export Intel environment to GITHUB_ENV
+          echo "CXX=icpx" >> $GITHUB_ENV
+          echo "CC=icx" >> $GITHUB_ENV
+          echo "PATH=$PATH" >> $GITHUB_ENV
+          echo "LD_LIBRARY_PATH=$LD_LIBRARY_PATH" >> $GITHUB_ENV
+          echo "LIBRARY_PATH=$LIBRARY_PATH" >> $GITHUB_ENV
+          echo "CPATH=$CPATH" >> $GITHUB_ENV
+          echo "ONEAPI_ROOT=$ONEAPI_ROOT" >> $GITHUB_ENV
+      
+      - name: Verify compiler
+        run: |
+          echo "CXX=$CXX"
+          $CXX --version
+
+      - name: Prepare build directory
+        run: mkdir -p ${{ runner.workspace }}/build
+
+      - name: Configure
+        shell: bash
+        env:
+          CXX: icpx
+        run: |
+          cd ${{ runner.workspace }}/build
+          cmake -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} -DCMAKE_CXX_STANDARD=${{ matrix.std }} -DQUILL_BUILD_TESTS=${{ matrix.with_tests }} -DQUILL_BUILD_EXAMPLES=ON -DQUILL_VERBOSE_MAKEFILE=ON $GITHUB_WORKSPACE
+
+      - name: Build
+        run: |
+          cd ${{ runner.workspace }}/build
+          cmake --build . --config ${{ matrix.build_type }} --parallel $(nproc)
+
+      - name: Test
+        env:
+          CTEST_OUTPUT_ON_FAILURE: True
+        run: |
+          cd ${{ runner.workspace }}/build
+          ctest --build-config ${{ matrix.build_type }} --parallel $(nproc) --output-on-failure

CHANGELOG.md

@@ -1,4 +1,4 @@
-- TBD
+- [v10.1.0](#v1010)
 - [v10.0.1](#v1001)
 - [v10.0.0](#v1000)
 - [v9.0.3](#v903)
@@ -91,16 +91,22 @@
 - [v1.1.0](#v110)
 - [v1.0.0](#v100)
 
-## TBD
+## v10.1.0
 
-- Added unique prefixes to internal macro variables to prevent conflicts with user variable names in the same
-  scope. ([#799](https://github.com/odygrd/quill/issues/799)
-- Added overflow check when doubling resync interval in `RdtscClock::resync()` to prevent potential UBSan
-  warnings ([#809](https://github.com/odygrd/quill/issues/809)
-- Improved `Utility::to_hex` function
-- Fixed an issue where `BackendWorker::_exit` was always executed during destruction, even when the backend thread had already stopped
+- Fixed potential conflicts by adding unique prefixes to internal macro variables to prevent conflicts with user
+  variable names in the same
+  scope. ([#799](https://github.com/odygrd/quill/issues/799))
+- Fixed potential `UBSan` warnings by adding overflow check when doubling resync interval in
+  `RdtscClock::resync()` ([#809](https://github.com/odygrd/quill/issues/809))
+- Minor improvements in `Utility::to_hex` function and `StringFromTime`
+- Fixed an issue where `BackendWorker::_exit` was always executed during destruction, even when the backend thread had
+  already stopped ([#815](https://github.com/odygrd/quill/issues/815))
 - Fixed `RotatingFileSink` to correctly handle `FilenameAppendOption::StartDate` configuration ([#822](https://github.com/odygrd/quill/issues/822))
- 
+- Fixed unnecessary allocation caused by empty `std::vector` while `BackendWorker` is idle on
+  Windows ([#827](https://github.com/odygrd/quill/issues/827))
+- Fixed `FileSink::open_mode` string comparison for file mode flags
+- Adjusted default `BackendOptions` values for broader system compatibility and typical usage patterns
+  
 ## v10.0.1
 
 - Fixed PatternFormatter test to work with any repository name instead of hardcoded `quill` ([#795](https://github.com/odygrd/quill/issues/795))

MODULE.bazel

@@ -1,6 +1,6 @@
 module(
     name = "quill",
-    version = "10.0.1",
+    version = "10.1.0",
     compatibility_level = 1,
 )
 

README.md

@@ -25,6 +25,9 @@
     <a href="https://github.com/odygrd/quill/actions?query=workflow%3Awindows">
       <img src="https://img.shields.io/github/actions/workflow/status/odygrd/quill/windows.yml?branch=master&label=Windows&logoColor=blue&style=flat-square&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iODgiIHdpZHRoPSI4OCIgeG1sbnM6dj0iaHR0cHM6Ly92ZWN0YS5pby9uYW5vIj48cGF0aCBkPSJNMCAxMi40MDJsMzUuNjg3LTQuODYuMDE2IDM0LjQyMy0zNS42Ny4yMDN6bTM1LjY3IDMzLjUyOWwuMDI4IDM0LjQ1M0wuMDI4IDc1LjQ4LjAyNiA0NS43em00LjMyNi0zOS4wMjVMODcuMzE0IDB2NDEuNTI3bC00Ny4zMTguMzc2em00Ny4zMjkgMzkuMzQ5bC0uMDExIDQxLjM0LTQ3LjMxOC02LjY3OC0uMDY2LTM0LjczOXoiIGZpbGw9IiMwMGFkZWYiLz48L3N2Zz4=" alt="windows-ci" />
     </a>
+    <a href="https://github.com/odygrd/quill/actions?query=workflow%3Aintelllvm">
+      <img src="https://img.shields.io/github/actions/workflow/status/odygrd/quill/intelllvm.yml?branch=master&label=Intel%20LLVM&style=flat-square&logo=intel" alt="intel-llvm-ci" />
+    </a>
   </div>
 
   <div>

benchmarks/backend_throughput/quill_backend_throughput.cpp

@@ -19,7 +19,8 @@ int main()
   quill::BackendOptions backend_options;
   backend_options.cpu_affinity = 5;
   backend_options.sleep_duration = std::chrono::nanoseconds{0};
-
+  backend_options.log_timestamp_ordering_grace_period = std::chrono::microseconds{1};
+  
   // Start the logging backend thread and give it some tiem to init
   quill::Backend::start(backend_options);
 
@@ -64,4 +65,4 @@ int main()
                  total_iterations / delta_d / 1e6,
                  std::chrono::duration_cast<std::chrono::milliseconds>(delta).count(), total_iterations)
             << std::endl;
-}
+}

benchmarks/backend_throughput/quill_backend_throughput_no_buffering.cpp

@@ -20,7 +20,8 @@ int main()
   backend_options.cpu_affinity = 5;
   backend_options.transit_events_hard_limit = 1;
   backend_options.transit_events_soft_limit = 1;
-
+  backend_options.log_timestamp_ordering_grace_period = std::chrono::microseconds{1};
+  
   // Start the logging backend thread and give it some tiem to init
   quill::Backend::start(backend_options);
 
@@ -67,4 +68,4 @@ int main()
                  total_iterations / delta_d / 1e6,
                  std::chrono::duration_cast<std::chrono::milliseconds>(delta).count(), total_iterations)
             << std::endl;
-}
+}

docs/backend_options.rst

@@ -3,10 +3,43 @@
 Backend Options
 ===============
 
-The backend options allow you to customize the behavior of the backend thread and are applied at runtime. To utilize these options, you need to create an object and pass it when starting the backend thread. Most options come with default values, but they can be tailored to meet the specific needs of your application. Refer to :cpp:struct:`BackendOptions` for detailed information.
+The backend options allow you to customize the behavior of the backend thread and are applied at runtime. To utilize these options, you need to create an object and pass it when starting the backend thread. Most options come with carefully tuned default values for general use, but they can be adjusted to meet the specific performance and latency requirements of your application. Refer to :cpp:struct:`BackendOptions` for detailed information.
+
+Example Usage
+-------------
 
 For example, to pin the backend worker thread to a specific CPU, you can use the following code:
 
 .. literalinclude:: examples/quill_docs_example_backend_options.cpp
    :language: cpp
    :linenos:
+
+Character Sanitization
+-----------------------
+
+By default, Quill filters log messages to ensure they contain only printable characters before writing them to sinks. This safety feature converts non-printable characters (including non-ASCII characters like Chinese, Japanese, or other Unicode text) to their hexadecimal representation (e.g., ``\xE4\xB8\xAD`` for Chinese characters).
+
+The default printable character range is limited to ASCII characters from space (``' '``) to tilde (``'~'``), plus newline (``'\n'``).
+
+**Disabling Character Sanitization for UTF-8 Logging**
+
+If you need to log UTF-8 or other non-ASCII text (such as Chinese, etc.), you can disable character sanitization:
+
+.. code-block:: cpp
+
+   quill::BackendOptions backend_options;
+   backend_options.check_printable_char = {};  // Disable sanitization
+   quill::Backend::start(backend_options);
+
+**Custom Character Filtering**
+
+You can also define custom printable character rules:
+
+.. code-block:: cpp
+
+   quill::BackendOptions backend_options;
+   backend_options.check_printable_char = [](char c) {
+       // Allow ASCII printable + newline + common UTF-8 byte ranges
+       return (c >= ' ' && c <= '~') || (c == '\n') || (static_cast<unsigned char>(c) >= 128);
+   };
+   quill::Backend::start(backend_options);

docs/cheat_sheet.rst

@@ -190,7 +190,7 @@ Outputs:
 
 Logging Strings Without Additional Copy
 ---------------------------------------
-By default, the logger takes a deep copy of any string. To log an immutable string with a valid lifetime without copying, use ``quill::utility::StringRef``.
+By default, the logger takes a deep copy of any string for thread safety. To log an immutable string with a valid lifetime without copying (e.g., string literals, static strings), use ``quill::utility::StringRef``.
 
 .. code:: cpp
 
@@ -302,7 +302,7 @@ To log user-defined types, you need to define how they should be serialized or c
        - If the type is **not trivially copyable**, it should have both a **copy constructor** and a **move constructor**.
 
     2. **Use DirectFormatCodec**
-       Suitable for objects that are not safe to copy across threads or for cases where formatting occurs in the slow path. This method converts the object to a string immediately in the hot path using `fmt::format`.
+       Suitable for objects that are not safe to copy across threads (e.g., contain raw pointers, references, or non-copyable resources). This method converts the object to a string immediately in the hot path using `fmt::format`, which increases hot-path latency.
 
     3. **Implement a Custom Codec**
        For maximum flexibility, you can define a custom codec to specify exactly how the object should be serialized and deserialized.
@@ -480,7 +480,7 @@ Writing Custom Codec
 Serialising Non Trivially Copyable User Defined Types With Public Members
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Note that it is possible to pass STL types to ``compute_total_encoded_size``, ``encode_members``, and ``decode_members`` as long as the relevant header file from ``quill/std/`` for that type is included.
+Note that STL types can be used in custom codecs by passing them to ``compute_total_encoded_size``, ``encode_members``, and ``decode_members``, provided you include the relevant header from ``quill/std/`` for each STL type used.
 
 .. code:: cpp
 

docs/conf.py

@@ -36,7 +36,7 @@ def configureDoxyfile(input_dir, output_dir):
 project = 'Quill'
 copyright = '2024, Odysseas Georgoudis'
 author = 'Odysseas Georgoudis'
-release = 'v10.0.1'
+release = 'v10.1.0'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/filters.rst

@@ -9,7 +9,7 @@ Each :cpp:class:`Sink` can be associated with one or multiple :cpp:class:`Filter
 
 By default, a logger sends all log messages to its ``Sinks``. Filters provide a way to intercept and selectively process log records before they are outputted.
 
-A filter is implemented as a callable object that evaluates each log statement and returns a boolean value. This boolean value determines whether the log statement should be forwarded to the ``Sink`` or filtered out.
+A filter is implemented as a callable object that evaluates each log statement on the backend thread and returns a boolean value. When the filter returns ``true``, the log statement is forwarded to the ``Sink``; when ``false``, the log statement is discarded.
 
 Filtering Logs with the Built-In Filter
 ---------------------------------------