CppTrail::BasicAsyncLoggerImpl< char_t > Class Template Reference

An asynchronous logger template utilizing background worker threads and object recycling. This class decouples the logging call from the actual I/O operation. It maintains an internal queue of log entries and a pool of worker threads to process them. To minimize heap pressure, it uses a backup pool (object pool) to recycle linked-list nodes. More...

#include <async_logger.h>

Inheritance diagram for CppTrail::BasicAsyncLoggerImpl< char_t >:

Collaboration diagram for CppTrail::BasicAsyncLoggerImpl< char_t >:

Public Types
using	char_type = typename BasicLoggerImpl< char_t >::char_type
	Alias for the underlying character type.
using	string_type = typename BasicLoggerImpl< char_t >::string_type
	Alias for the basic_string type associated with this logger's encoding.
using	message_type = typename BasicLoggerImpl< char_t >::message_type
	Alias for the BasicMessage type associated to the logger.
Public Types inherited from CppTrail::BasicLoggerImpl< char_t >
using	char_type = char_t
	Alias for the underlying character type used by this logger.
using	string_type = std::basic_string< char_type >
	Alias for the basic_string type associated with this logger's encoding.
using	message_type = BasicMessage< char_type >
	Alias for the BasicMessage type associated to the logger.
using	string_view_type = std::basic_string_view< char_type >
	Alias for the basic_string_view type associated with this logger's encoding.

Public Member Functions
void	log (message_type oMessage) final
	Enqueues a log message for asynchronous processing.
void	start () final
	Starts the background worker pool and the underlying service.
void	stop () final
	Synchronously shuts down the worker pool and the service.
void	signalStop () final
	Initiates a shutdown sequence on a separate background "killer" thread.
void	join () final
	Blocks until all background activity (workers and killer threads) has ceased.
Status	status () final
	Retrieves the aggregated operational status of the asynchronous logger.
Public Member Functions inherited from CppTrail::BasicLoggerImpl< char_t >
virtual	~BasicLoggerImpl ()=default
	Virtual destructor to ensure proper cleanup of derived logger resources.

Protected Member Functions
	BasicAsyncLoggerImpl ()
	Default constructor.
	BasicAsyncLoggerImpl (std::size_t nMaxEntryCount, bool bThrowOnOverflow, std::size_t nWorkerCount)
	Specialized constructor for controlled resource management.
	~BasicAsyncLoggerImpl () override=default
	Destructor.
virtual void	work (message_type oMessage)=0
	Abstract method for the actual I/O work.
Service Lifecycle Interface
Hooks for derived classes to manage the underlying sink (e.g., opening sockets).
virtual Status	serviceStatus ()=0
	Reports the current operational status of the underlying sink.
virtual void	serviceStart ()=0
	Performs the initialization sequence for the sink.
virtual void	serviceStop ()=0
	Performs the shutdown sequence for the sink.

Detailed Description

template<typename char_t>
class CppTrail::BasicAsyncLoggerImpl< char_t >

An asynchronous logger template utilizing background worker threads and object recycling. This class decouples the logging call from the actual I/O operation. It maintains an internal queue of log entries and a pool of worker threads to process them. To minimize heap pressure, it uses a backup pool (object pool) to recycle linked-list nodes.

Template Parameters

char_t

The character type (e.g., char, char8_t) used for log content.

Warning

Ensure that your destructor calls stop() and join()

Constructor & Destructor Documentation

BasicAsyncLoggerImpl() [1/2]

template<typename char_t >

CppTrail::BasicAsyncLoggerImpl< char_t >::BasicAsyncLoggerImpl ( )

inlineprotected

Default constructor.

Initializes a single worker thread and sets an effectively infinite queue limit.

BasicAsyncLoggerImpl() [2/2]

template<typename char_t >

CppTrail::BasicAsyncLoggerImpl< char_t >::BasicAsyncLoggerImpl ( std::size_t  nMaxEntryCount, bool  bThrowOnOverflow, std::size_t  nWorkerCount  )

protected

Specialized constructor for controlled resource management.

Parameters

nMaxEntryCount	The maximum number of log entries allowed in the queue.
bThrowOnOverflow	If true, log() throws LoggerOverflowError when full; otherwise, it drops the log.
nWorkerCount	The number of background threads to spawn for processing.

~BasicAsyncLoggerImpl()

template<typename char_t >

CppTrail::BasicAsyncLoggerImpl< char_t >::~BasicAsyncLoggerImpl ( )

overrideprotecteddefault

Destructor.

Warning

Ensure that your destructor calls stop() and join()

Member Function Documentation

join()

template<typename char_t >

void CppTrail::BasicAsyncLoggerImpl< char_t >::join ( )

finalvirtual

Blocks until all background activity (workers and killer threads) has ceased.

This is the final synchronization point. It ensures that no background threads are still accessing the logger's memory.

Note

This is called automatically by the BasicLogger handle's destructor to ensure RAII safety and prevent "zombie" threads.

Implements CppTrail::BasicLoggerImpl< char_t >.

log()

template<typename char_t >

void CppTrail::BasicAsyncLoggerImpl< char_t >::log ( message_type  oMessage )

finalvirtual

Enqueues a log message for asynchronous processing.

This is the primary entry point for logging. It is designed to be high-performance and non-blocking under normal conditions. The message is moved into an internal thread-safe queue to be processed by the worker pool.

Parameters

oMessage

The message to be logged. This object is moved; the caller should not rely on its state after this call.

Exceptions

LoggerOverflowError

If the internal queue reaches m_nMaxEntryCount and the logger is configured to throw on overflow.

Note

If the logger is in Status::STOPPED or Status::BROKEN, the message will be silently discarded to prevent memory leaks during shutdown.

If overflow occurs and bThrowOnOverflow is false, the message is dropped to prioritize application stability over log completeness.

Implements CppTrail::BasicLoggerImpl< char_t >.

serviceStart()

template<typename char_t >

virtual void CppTrail::BasicAsyncLoggerImpl< char_t >::serviceStart ( )

protectedpure virtual

Performs the initialization sequence for the sink.

This is called internally during the start() sequence. It is the appropriate place to allocate memory, open files, or establish network connections before the worker thread begins processing the log queue.

Exceptions

std::runtime_error

or similar if the resource cannot be acquired.

serviceStatus()

template<typename char_t >

virtual Status CppTrail::BasicAsyncLoggerImpl< char_t >::serviceStatus ( )

protectedpure virtual

Reports the current operational status of the underlying sink.

Returns

The current Status of the service.

Note

If the sink is considered "always-on" (like std::cout), this should return Status::TRASCENDENT.

serviceStop()

template<typename char_t >

virtual void CppTrail::BasicAsyncLoggerImpl< char_t >::serviceStop ( )

protectedpure virtual

Performs the shutdown sequence for the sink.

This is called internally during the stop() sequence, after the worker thread has finished draining the log queue. It ensures that resources are released gracefully (e.g., sending a TCP FIN or closing a database transaction).

signalStop()

template<typename char_t >

void CppTrail::BasicAsyncLoggerImpl< char_t >::signalStop ( )

finalvirtual

Initiates a shutdown sequence on a separate background "killer" thread.

This provides a non-blocking alternative to stop(). It spawns a temporary thread that executes the full stop() sequence in the background, allowing the calling thread to continue immediately.

Note

Use join() later to ensure this background shutdown has completed.

Implements CppTrail::BasicLoggerImpl< char_t >.

start()

template<typename char_t >

void CppTrail::BasicAsyncLoggerImpl< char_t >::start ( )

finalvirtual

Starts the background worker pool and the underlying service.

This is a blocking call that ensures the lifecycle is initialized in the correct order:

1. It waits for any existing "killer" threads to finish.
2. It calls serviceStart() to allow derived classes to acquire resources (files, sockets, etc.).
3. It spawns the specified number of background worker threads.

   Note

   This method is thread-safe and prevents multiple simultaneous start sequences.

Implements CppTrail::BasicLoggerImpl< char_t >.

status()

template<typename char_t >

Status CppTrail::BasicAsyncLoggerImpl< char_t >::status ( )

finalvirtual

Retrieves the aggregated operational status of the asynchronous logger.

This method performs a thread-safe evaluation of the logger's health by cross-referencing the underlying service (sink) status with the worker engine's state. The logic follows a "Contract of Expectation":

• If the service is RUNNING/TRASCENDENT, the workers must be ON.
• If the service is STOPPED, the workers must be OFF.
• Any mismatch (e.g., workers running but service stopped) results in Status::BROKEN.

  Returns

  Status The current composite state:

• RUNNING/TRASCENDENT: Fully operational and accepting logs.
• STOPPED: Gracefully shut down; no background activity.
• BROKEN: An inconsistency or critical failure has occurred in the pipeline.

  Note

  This call acquires the worker mutex to ensure a consistent snapshot of the engine state.

Implements CppTrail::BasicLoggerImpl< char_t >.

stop()

template<typename char_t >

void CppTrail::BasicAsyncLoggerImpl< char_t >::stop ( )

finalvirtual

Synchronously shuts down the worker pool and the service.

This method performs a graceful "Drain and Stop" sequence:

1. It signals the worker engine to stop accepting new logs.
2. It blocks the calling thread until all workers have finished processing the current queue.
3. It calls serviceStop() to release resources in the derived implementation.

   Warning

   This is a blocking call. If the queue is large, it may take time to return.

Implements CppTrail::BasicLoggerImpl< char_t >.

work()

template<typename char_t >

virtual void CppTrail::BasicAsyncLoggerImpl< char_t >::work ( message_type  oMessage )

protectedpure virtual

Abstract method for the actual I/O work.

Called by worker threads outside of the queue lock.

Parameters

oMessage

The message to be recorded.

---

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

• /home/runner/work/cpptrail/cpptrail/include/cpptrail/async_logger.h