From 6b846a9805509f13090ec1698773f8ea2eb689f2 Mon Sep 17 00:00:00 2001 From: Odysseas Georgoudis Date: Sun, 22 Sep 2024 15:10:49 +0100 Subject: [PATCH] update documentation --- docs/backend_options.rst | 14 +++++++ docs/frontend_options.rst | 61 ++++++++++++++++++++++++++++ docs/index.rst | 16 ++++---- include/quill/core/FrontendOptions.h | 2 +- 4 files changed, 85 insertions(+), 8 deletions(-) create mode 100644 docs/backend_options.rst create mode 100644 docs/frontend_options.rst diff --git a/docs/backend_options.rst b/docs/backend_options.rst new file mode 100644 index 00000000..2aa1cd35 --- /dev/null +++ b/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); \ No newline at end of file diff --git a/docs/frontend_options.rst b/docs/frontend_options.rst new file mode 100644 index 00000000..edce4b6a --- /dev/null +++ b/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 + + // 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; + + // The Logger type must also be defined + using CustomLogger = quill::LoggerImpl; + + int main() + { + // Start the backend thread + quill::BackendOptions backend_options; + quill::Backend::start(backend_options); // or quill::Backend::start_with_signal_handler(); + + // All frontend operations and Logger must utilize the CustomFrontend instead of quill::Frontend + auto console_sink = CustomFrontend::create_or_get_sink("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); + } \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 3e338135..bf701e0a 100644 --- a/docs/index.rst +++ b/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 diff --git a/include/quill/core/FrontendOptions.h b/include/quill/core/FrontendOptions.h index af295af5..81afe505 100644 --- a/include/quill/core/FrontendOptions.h +++ b/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. *