VLink  2.3.0
A high-performance communication middleware
vlink::LoggerBackend Class Referencefinal

MessageLoop-based asynchronous rotating-file backend. More...

#include <logger_backend.h>

Inheritance diagram for vlink::LoggerBackend:
Collaboration diagram for vlink::LoggerBackend:

Classes

struct  Config
 Construction-time queue, file and formatting settings. More...
 

Public Types

using ErrorHandler = Function< void(std::string_view)>
 Callback invoked once when the backend enters a permanent error state. More...
 
using ConsoleWriter = Function< void(Logger::Level, std::string_view)>
 Callback used to emit preformatted backtrace records to a console sink. More...
 
 Internal queue implementation type. More...
 Back-pressure strategy applied when the bounded queue is at capacity. More...
 Built-in priority levels for kPriorityType loops; higher values dispatch first. More...

Public Member Functions

 LoggerBackend (Config &&config, ErrorHandler &&error_handler, ConsoleWriter &&console_writer=nullptr)
 Constructs and starts the asynchronous backend. More...
 
 ~LoggerBackend () override
 Drains records still pending at shutdown, flushes the file and stops the worker. More...
 
bool log (Logger::Level level, std::string_view message) noexcept
 Enqueues one record. More...
 
void flush () noexcept
 Drains non-evicted records preceding the barrier and flushes the active file. More...
 
void enable_backtrace (size_t size) noexcept
 Starts retaining the most recent records in a bounded ring. More...
 
void disable_backtrace () noexcept
 Stops backtrace capture and discards retained records. More...
 
void dump_backtrace (const ConsoleWriter &console_writer) noexcept
 Writes retained records to the file and optional console callback. More...
 
bool has_error () const noexcept
 Reports whether the running backend entered a permanent error state. More...
 
size_t get_max_task_count () const override
 Returns the configured MessageLoop dispatcher queue capacity. More...
 

Additional Inherited Members

Detailed Description

MessageLoop-based asynchronous rotating-file backend.

Each accepted record owns its message until a single worker thread formats and writes it. Queue overflow either blocks producers or discards an older record from the dispatcher queue according to Config::block_when_full; Error and Fatal records always block and remain protected. Low-frequency control operations use protected queue barriers, so flush and backtrace changes cannot be evicted by data-plane overflow.

Note
A backend must exclusively own its rotating-file set. Separate processes or backend instances should use separate paths. Flush transfers buffered bytes to the operating system but does not provide power-loss durability equivalent to fsync.
Stop and join all callers before destruction. Inherited MessageLoop lifecycle controls may be used to stop the worker for diagnostics, but a stopped backend must not be restarted; direct shutdown may discard records that have not reached the worker batch.

Member Typedef Documentation

◆ ConsoleWriter

Callback used to emit preformatted backtrace records to a console sink.

Receives the record level and one formatted line without its trailing newline. When stored by the constructor it receives Warn and higher records while backtrace capture is enabled; dump_backtrace may provide a callback for retained records. The line view is valid only during the callback, including nested writes. Logging and backtrace reconfiguration are allowed; recursive dumps and automatic console callbacks are suppressed. The callback must not destroy the backend or wait for its worker. Exceptions put the backend into its permanent error state.

◆ ErrorHandler

using vlink::LoggerBackend::ErrorHandler = Function<void(std::string_view)>

Callback invoked once when the backend enters a permanent error state.

Receives the diagnostic message on the thread that detects the error. The message view is valid only during the callback. The callback must not destroy this backend or wait for its worker or invoke this backend; exceptions are isolated at the notification boundary.

Constructor & Destructor Documentation

◆ LoggerBackend()

vlink::LoggerBackend::LoggerBackend ( Config &&  config,
ErrorHandler &&  error_handler,
ConsoleWriter &&  console_writer = nullptr 
)
explicit

Constructs and starts the asynchronous backend.

Parameters
configQueue, file and formatting settings.
error_handlerOptional permanent-error notification.
console_writerOptional backtrace console receiver.
Note
Backend initialisation failures enter the permanent error state and notify error_handler instead of throwing. Use has_error to inspect that state.

◆ ~LoggerBackend()

vlink::LoggerBackend::~LoggerBackend ( )
override

Drains records still pending at shutdown, flushes the file and stops the worker.

Member Function Documentation

◆ disable_backtrace()

void vlink::LoggerBackend::disable_backtrace ( )
noexcept

Stops backtrace capture and discards retained records.

◆ dump_backtrace()

void vlink::LoggerBackend::dump_backtrace ( const ConsoleWriter &  console_writer)
noexcept

Writes retained records to the file and optional console callback.

Parameters
console_writerOptional receiver for each preformatted line without its trailing newline.
Note
Callbacks may reconfigure the live ring; the dump consumes a snapshot. Recursive dumps and console callbacks are suppressed. Permanent file errors still permit console replay.

◆ enable_backtrace()

void vlink::LoggerBackend::enable_backtrace ( size_t  size)
noexcept

Starts retaining the most recent records in a bounded ring.

Parameters
sizeMaximum retained record count.

◆ flush()

void vlink::LoggerBackend::flush ( )
noexcept

Drains non-evicted records preceding the barrier and flushes the active file.

◆ get_max_task_count()

size_t vlink::LoggerBackend::get_max_task_count ( ) const
overridevirtual

Returns the configured MessageLoop dispatcher queue capacity.

Returns
Number of MessageLoop dispatcher queue slots, excluding the current worker batch.

Reimplemented from vlink::MessageLoop.

◆ has_error()

bool vlink::LoggerBackend::has_error ( ) const
noexcept

Reports whether the running backend entered a permanent error state.

Returns
true after the first permanent backend error.

◆ log()

bool vlink::LoggerBackend::log ( Logger::Level  level,
std::string_view  message 
)
noexcept

Enqueues one record.

Parameters
levelRecord severity.
messageMessage bytes copied into backend-owned storage.
Returns
true when accepted for processing; false for kOff, after shutdown or permanent error, on allocation/enqueue failure, or when a non-blocking full queue contains no droppable record. Acceptance does not guarantee a later file write.

The documentation for this class was generated from the following file: