update documentation

docs/backend_options.rst

@@ -0,0 +1,14 @@
+.. title:: Backend Options
+
+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.
+
+For example, to pin the backend worker thread to a specific CPU, you can use the following code:
+
+.. code:: cpp
+
+    quill::BackendOptions backend_options;
+    backend_options.cpu_affinity = 5;
+    quill::Backend::start(backend_options);

docs/frontend_options.rst

@@ -0,0 +1,61 @@
+.. title:: Frontend Options
+
+Frontend Options
+================
+
+The frontend options provide a flexible way to configure hot path settings. These options are compile time options and allow for the customisation of queue types, as well as the use of huge pages on Linux systems.
+
+Each frontend thread operates with its own queue, which can be configured with one of the following options:
+
+- **UnboundedBlocking**: Starts with a small initial capacity. The queue reallocates up to 2GB and then blocks further log messages.
+- **UnboundedDropping**: Starts with a small initial capacity. The queue reallocates up to 2GB and then discards log messages.
+- **UnboundedUnlimited**: Starts with a small initial capacity and reallocates without limit. This queue never blocks or drops log messages.
+- **BoundedBlocking**: Has a fixed capacity and never reallocates. It blocks log messages when the limit is reached.
+- **BoundedDropping**: Has a fixed capacity and never reallocates. It discards log messages when the limit is reached.
+
+Even though each thread has its own queue, a single queue type must be defined for the entire application. By default the `UnboundedBlocking` queue type is used.
+
+To modify the queue type, you should define your own :cpp:struct:`FrontendOptions` and use it to create a custom :cpp:class:`FrontendImpl` and :cpp:class:`LoggerImpl`.
+
+It is important to consistently use your custom types throughout the application, instead of the default ones.
+
+For example, to use a `BoundedDropping` queue with a fixed capacity of `131'072`, you can follow the steps below:
+
+.. code:: cpp
+
+    #include "quill/Backend.h"
+    #include "quill/Frontend.h"
+    #include "quill/sinks/ConsoleSink.h"
+    #include "quill/LogMacros.h"
+    #include "quill/Logger.h"
+    #include <utility>
+
+    // define your own FrontendOptions, see "core/FrontendOptions.h" for details
+    struct CustomFrontendOptions
+    {
+      static constexpr quill::QueueType queue_type = quill::QueueType::BoundedDropping;
+      static constexpr uint32_t initial_queue_capacity = 131'072;
+      static constexpr uint32_t blocking_queue_retry_interval_ns = 800;
+      static constexpr bool huge_pages_enabled = false;
+    };
+
+    // To utilize our custom FrontendOptions, we define a Frontend class using CustomFrontendOptions
+    using CustomFrontend = quill::FrontendImpl<CustomFrontendOptions>;
+
+    // The Logger type must also be defined
+    using CustomLogger = quill::LoggerImpl<CustomFrontendOptions>;
+
+    int main()
+    {
+      // Start the backend thread
+      quill::BackendOptions backend_options;
+      quill::Backend::start(backend_options); // or quill::Backend::start_with_signal_handler<CustomFrontendOptions>();
+
+      // All frontend operations and Logger must utilize the CustomFrontend instead of quill::Frontend
+      auto console_sink = CustomFrontend::create_or_get_sink<quill::ConsoleSink>("sink_id_1");
+      CustomLogger* logger = CustomFrontend::create_or_get_logger("root", std::move(console_sink));
+
+      // log something
+      LOG_INFO(logger, "This is a log info example {}", 123);
+      LOG_WARNING(logger, "This is a log warning example {}", 123);
+    }

docs/index.rst

@@ -24,19 +24,21 @@ Quill is a high-performance asynchronous C++ logging library. It excels in perfo
    :maxdepth: 2
    :caption: Tutorial
 
+   backend_options
+   backtrace_logging
    basic_example
-   logging_macros
-   sinks
-   sink_types
+   csv_writing
    filters
    formatters
+   frontend_options
+   json_logging
+   log_tagging
    loggers
+   logging_macros
+   sinks
+   sink_types
    timestamp_types
-   backtrace_logging
    wide_strings
-   csv_writing
-   json_logging
-   log_tagging
 
 .. toctree::
    :maxdepth: 2

include/quill/core/FrontendOptions.h

@@ -19,7 +19,7 @@ struct FrontendOptions
    * Each frontend thread has its own queue, which can be configured with various options:
    * - UnboundedBlocking: Starts with initial_queue_capacity and reallocates up to 2GB, then blocks.
    * - UnboundedDropping: Starts with initial_queue_capacity and reallocates up to 2GB, then drops log messages.
-   * - UnboundedUnlimited: Starts with initial_queue_capacity and reallocates up to 2GB; subsequent queues are reallocated as needed. Never blocks or drops.
+   * - UnboundedUnlimited: Starts with initial_queue_capacity and reallocates without limit, subsequent queues are reallocated as needed. Never blocks or drops.
    * - BoundedBlocking: Starts with initial_queue_capacity and never reallocates; blocks when the limit is reached.
    * - BoundedDropping: Starts with initial_queue_capacity and never reallocates; drops log messages when the limit is reached.
    *