×
Doc Home Page

Namespaces targets se_colors msg_details helpers globals SERENITY_LUTS custom_flags CustomFlagError

Classes Flush_Policy Message_Formatter Message_Info ZoneThread Message_Time ConsoleTarget FileTarget RotatingTarget RotateSettings TargetBase FileHelper FileCache BaseTargetHelper Format_Source_Loc Format_Thread_ID format_error

Structs CustomFormatter<LoggerLevel> CustomFormatter<std::tm> PeriodicSettings RotateLimits RotatingDaylightCache BackgroundThread MsgWithLoc custom_error_handler
Home Building Examples Source Go To Top
Home Building Examples Source


BackgroundThread
- Found In File: FileHelper.h





This struct simply helps the file based targets check for the ability to write to or flush to a file before attempting to lock a mutex for those operations. The goal of this struct is to minimize thread contention for the file based targets when multi-threading support is enabled.

Click here for a file snippet:

This struct is found under the namespace serenity::target::helpers in file FileHelper.h 


   struct BackgroundThread
   {
   	   std::jthread flushThread;
   	   std::stop_token interruptThread {};
   	   std::atomic<bool> cleanUpThreads {false };
   	   std::atomic<bool> flushThreadEnabled {false };
   	   std::atomic<bool> flushComplete {true };
   	   std::atomic<bool> threadWriting {false };
   	   std::atomic<bool> pauseThread {false };
   };

Member Variables
std::jthread flushThread
This thread object is used by Serenity for background flushing independent of the logging thread(s).
std::stop_token interruptThread
This stop token object is used, as the name implies, to interrupt the background flushing thread as well as effectively terminates the flushing thread gracefully.
std::atomic<bool> cleanUpThreads
This atomic variable is used to initiate, check, and notify the background flushing thread when the main thread requests this thread to be destroyed.
std::atomic<bool> flushThreadEnabled
This atomic variable is used in checks from the file logging thread(s) when writing to the file buffer.
std::atomic<bool> flushComplete
This atomic variable is used to notify the file logging thread(s) when a flush operation has been completed.
std::atomic<bool> threadWriting
This atomic variable is used to notify the background flushing thread when a logging operation has been completed.
std::atomic<bool> pauseThread
This atomic variable is used to notify the background flushing thread to temporarily halt any flushing operations without destroying the thread itself.
More Information About BackgroundThread


std::jthread flushThread
This thread object handles background flushing of contents to the file and is the same thread that the other variables in this struct are primarily referencing in Serenity for communication between the logging thread(s) and the actual flushing of those logs to the file(s).


std::stop_token interruptThread
This stop token object is used, as the name implies, to interrupt the background flushing thread as well as effectively terminates the flushing thread gracefully. This is used specifically in the clean-up process on logger target destruction if the flushing thread was created.


std::atomic<bool> cleanUpThreads
This atomic variable is used to initiate, check, and notify the background flushing thread when the main thread requests this thread to be destroyed; this is used in tandem with the stop_token `interruptThread` during logger destruction.


std::atomic<bool> flushThreadEnabled
This atomic variable is set to `true` when the background flushing thread is instantiated and is used in checks from the file logging thread(s) when writing to the file buffer.


std::atomic<bool> flushComplete
This atomic variable is used to notify the file logging thread(s) when a flush operation has been completed and when it is safe to claim a light-weight ownership over the resource for continued logging before locking the mutex to aid in avoiding thread contention.


std::atomic<bool> threadWriting
This atomic variable is used to notify the background flushing thread when a logging operation has been completed and when it is safe to claim a light-weight ownership over the resource for continued flushing before locking the mutex to aid in avoiding thread contention.


std::atomic<bool> pauseThread
This atomic variable is used to notify the background flushing thread to temporarily halt any flushing operations without destroying the thread itself. This is used more so with the RotatingTarget based logger(s) when a file is currently in the process of being rotated based on setting thresholds that have been met or in the case that the flush policies for certain logger(s) has changed or if the period for flushing hasn't elapsed.

For Example:
  1. Flush policy was changed from FlushSetting::always to FlushSetting::never
    • In this case, the thread will be put to sleep indefinitely or until the logger is destroyed by setting this atomic to `true` and bypassing flush operations.
  2. Flush policy is set to FlushSetting::periodically with PeriodicSettings::logLevelBased and a log level of Fatal
    • In this case, this thread will effectively be put to sleep until a Fatal log message has been written. This scenario sets this atomic to `true` and then immediately wakes up and flushes the file buffer to disk by setting this atomic to `false` once the condition (a fatal message) has been met. Then, once all contents have been flushed, this atomic will be reset back to `true`; pausing the background thread from executing again.