This class is in charge of logging to any basic file type and handling the rotation of files up to a maximum number of files set. This class inherits from the FileTarget class and, therefore, the TargetBase class for common logging functions and logging settings. More...

Inheritance diagram for serenity::experimental::targets::RotatingTarget:

Public Member Functions
	RotatingTarget ()
	Default constructor that will set the logger name to "Rotating_Logger". All sets all other values to their defaults. More...

	RotatingTarget (std::string_view name, std::string_view filePath, bool replaceIfExists=false)
	Constructor that sets the logger name, the file name, file path, and log directory off the `filePath` variable, and will truncate the file if it already exists depending on the value of `replaceIfExists`. More...

	RotatingTarget (std::string_view name, std::string_view formatPattern, std::string_view filePath, bool replaceIfExists=false)
	Constructor that sets the logger name, the format pattern to use, the file name, file path, and log directory off the `filePath` variable, and will truncate the file if it already exists depending on the value of `replaceIfExists`. More...

	RotatingTarget (const RotatingTarget &)=delete

RotatingTarget &	operator= (const RotatingTarget &)=delete

	~RotatingTarget ()
	Cleans up any background resources used and closes the file context currently held. More...

void	ShouldRotateFile (bool shouldRotate=true)
	This function takes in a boolean value that determines whether or not the file context currently held should rotate when file size limit option has been reached.

void	SetRotateSettings (RotateSettings settings)
	Sets the overall rotation settings for the logger in regards to the filecontext. More...

void	RenameFileForRotation ()
	Sets up the base file given in constructor, or the base file after being renamed, for rotation. More...

void	RotateFileOnSize ()
	This function controls how the file is rotated. If the logger should rotate, the file will be closed and the next file in iteration up to the max file limit will be opened for writing. More...

bool	RenameFile (std::string_view newFileName) override
	Renames the current file to the name passed in via `newFileName`. More...

void	PrintMessage (std::string_view formatted) override
	Writes the message to the currently held file context unless writing to the buffer was enabled - in which case, this will write to the buffer instead. More...

const std::string	FilePath ()
	Returns the file path of the file context currently being held.

const std::string	FileName ()
	Returns the file name of the file context currently being held.

void	EraseContents ()
	Closes the file context currently being held and re-opens the same file context, truncating the file size to 0.

bool	OpenFile (bool truncate=false)
	Opens the file held by the file handle. More...

bool	CloseFile ()
	Joins any currently running flush background thread (if enabled) and if the file handle's file context is currently open, will flush contents to disk and close the file. More...

void	Flush ()
	If contents were written to buffer, this will now write contents of buffer to file and flush contents to disk, otherwise, just flushes contents to disk.

void	SetFlushPolicy (serenity::experimental::Flush_Policy pPolicy)
	Sets the current policy in use to defer to the policy passed in from "pPolicy". More...

serenity::experimental::Flush_Policy &	Policy ()
	Returns the current policy in use.

const std::string	LoggerName ()
	Returns the logger's name.

void	SetPattern (std::string_view pattern)
	Calls the handle to the Message_Formatter's SetPattern( ) function. More...

void	ResetPatternToDefault ()
	Resets the current format pattern in use to the default format pattern.

void	SetLogLevel (LoggerLevel level)
	Sets the log level that messages should be logged at. More...

void	WriteToBaseBuffer (bool fmtToBuf=true)
	Enables/Disables writing to a buffer. More...

bool	isWriteToBuf ()
	Returns true if buffer writes are enabled and false if they are disabled.

std::string *	Buffer ()
	Returns a pointer to the buffer container.

const LoggerLevel	Level ()
	Returns the current log level setting (the threshold of whether to log a message or not).

void	SetLoggerName (std::string_view name)
	Sets the name of the logger. More...

template<typename... Args>
void	Trace (std::string_view msg, Args &&...args)
	Logs a message giving the message a LoggerLevel::trace setting. More...

template<typename... Args>
void	Info (std::string_view msg, Args &&...args)
	Logs a message giving the message a LoggerLevel::info setting. More...

template<typename... Args>
void	Debug (std::string_view msg, Args &&...args)
	Logs a message giving the message a LoggerLevel::debug setting. More...

template<typename... Args>
void	Warn (std::string_view msg, Args &&...args)
	Logs a message giving the message a LoggerLevel::warning setting. More...

template<typename... Args>
void	Error (std::string_view msg, Args &&...args)
	Logs a message giving the message a LoggerLevel::error setting. More...

template<typename... Args>
void	Fatal (std::string_view msg, Args &&...args)
	Logs a message giving the message a LoggerLevel::fatal setting. More...

Protected Member Functions
void	PolicyFlushOn () override
	Executes the currently set flush policy. More...

msg_details::Message_Formatter *	MsgFmt ()
	Returns a pointer to the handle for the Message_Formatter class instance.

msg_details::Message_Info *	MsgInfo ()
	Returns a pointer to the handle for the Message_Info class instance.

Protected Attributes
std::ofstream	fileHandle
	Protected file handle that holds the file context. More...

FileSettings	fileOptions
	The structure this class and the derived class ( RotatingTarget ) use to keep track of basic file settings. More...

BackgroundThread	flushWorker
	The structure this class and the derived class ( RotatingTarget ) use to flush contents to disk on an interval basis. More...

Detailed Description

For all Rotating Target Constructors:

if either the directories or the file don't exist yet, the *constructor will create the neccessary directories
as well as the file needed to write to.
For the constructors that don't take a file path variable, the logs will be written to a "Logs" directory in the
location that the app is being run from.

Constructor & Destructor Documentation

◆ RotatingTarget() [1/3]

serenity::experimental::targets::RotatingTarget::RotatingTarget ( )

The default constructor will also create a file named "Rotating_Log.txt" upon creation. This base name and extension will be cached internally and the file will be renamed as Rotating_Log_01.txt and follow rotation settings thereafter in the "Logs" directory of where the app is running from

◆ RotatingTarget() [2/3]

serenity::experimental::targets::RotatingTarget::RotatingTarget	(	std::string_view	name,
		std::string_view	filePath,
		bool	replaceIfExists = `false`
	)

explicit

This constructor will cache the file name, the file path, the file extension, and the log directory off of the filePath variable. The file will then be renamed for rotation - if the file already exists, it will delete the oldest file with the base file name and rename the file using that file's index number.

Parameters

name	the name that the logger itself will use and be identified by
filePath	the full path to the file to write to
replaceIfExists	this value will determine if the file is truncated upon being opened the first time

◆ RotatingTarget() [3/3]

serenity::experimental::targets::RotatingTarget::RotatingTarget	(	std::string_view	name,
		std::string_view	formatPattern,
		std::string_view	filePath,
		bool	replaceIfExists = `false`
	)

explicit

This constructor will cache the file name, the file path, the file extension, and the log directory off of the filePath variable. The file will then be renamed for rotation - if the file already exists, it will delete the oldest file with the base file name and rename the file using that file's index number.

Parameters

name	the name that the logger itself will use and be identified by
formatPattern	the format pattern that determines how the prepended text will be displayed before the log message
filePath	the full path to the file to write to
replaceIfExists	this value will determine if the file is truncated upon being opened the first time

◆ ~RotatingTarget()

serenity::experimental::targets::RotatingTarget::~RotatingTarget ( )

When the deconstructor is called, will clean up background flush thread if enabled, flush the contents of the file handle to the file (if messages were written to buffer, will now write contents of buffer to file), and then close the file context

Member Function Documentation

◆ CloseFile()

bool serenity::targets::FileTarget::CloseFile ( )

inherited

Returns: If successful, returns true. If unsuccessful, will return false with error message

◆ Debug()

template<typename... Args>

serenity::targets::TargetBase::Debug	(	std::string_view	msg,
		Args &&...	args
	)

inherited

Checks if the message should be logged via the log level threshold setting. If it isn't, immediately returns. If the message should be logged, this function will then perform a quick check on whether or not writes to the buffer were enabled and will write to the buffer if they were. If writes to the buffers weren't enabled, then PrintMessage( ) will be called and the derived target handles how this is implemented. After writing the message, follows the derived target's PolicyFlushOn( ) implementation

Template Parameters

msg	The message being passed in. Follows C++20's format library and libfmt's substitution model using "{}" to replace any arguments from the `args` parameter.
args	Variadic placeholder for any number of and any type of arguments to use in substituion.

◆ Error()

template<typename... Args>

serenity::targets::TargetBase::Error	(	std::string_view	msg,
		Args &&...	args
	)

inherited

Checks if the message should be logged via the log level threshold setting. If it isn't, immediately returns. If the message should be logged, this function will then perform a quick check on whether or not writes to the buffer were enabled and will write to the buffer if they were. If writes to the buffers weren't enabled, then PrintMessage( ) will be called and the derived target handles how this is implemented. After writing the message, follows the derived target's PolicyFlushOn( ) implementation

Template Parameters

msg	The message being passed in. Follows C++20's format library and libfmt's substitution model using "{}" to replace any arguments from the `args` parameter.
args	Variadic placeholder for any number of and any type of arguments to use in substituion.

◆ Fatal()

template<typename... Args>

serenity::targets::TargetBase::Fatal	(	std::string_view	msg,
		Args &&...	args
	)

inherited

Checks if the message should be logged via the log level threshold setting. If it isn't, immediately returns. If the message should be logged, this function will then perform a quick check on whether or not writes to the buffer were enabled and will write to the buffer if they were. If writes to the buffers weren't enabled, then PrintMessage( ) will be called and the derived target handles how this is implemented. After writing the message, follows the derived target's PolicyFlushOn( ) implementation

Template Parameters

msg	The message being passed in. Follows C++20's format library and libfmt's substitution model using "{}" to replace any arguments from the `args` parameter.
args	Variadic placeholder for any number of and any type of arguments to use in substituion.

◆ Info()

template<typename... Args>

serenity::targets::TargetBase::Info	(	std::string_view	msg,
		Args &&...	args
	)

inherited

Checks if the message should be logged via the log level threshold setting. If it isn't, immediately returns. If the message should be logged, this function will then perform a quick check on whether or not writes to the buffer were enabled and will write to the buffer if they were. If writes to the buffers weren't enabled, then PrintMessage( ) will be called and the derived target handles how this is implemented. After writing the message, follows the derived target's PolicyFlushOn( ) implementation

Template Parameters

msg	The message being passed in. Follows C++20's format library and libfmt's substitution model using "{}" to replace any arguments from the `args` parameter.
args	Variadic placeholder for any number of and any type of arguments to use in substituion.

◆ OpenFile()

bool serenity::targets::FileTarget::OpenFile ( bool truncate = false )

inherited

Opens the file context currently being held and sets the file buffer size using "DEFAULT_BUFFER_SIZE" macro. If the file doessn't already exist, this function will create the file first.

Returns: If successful, returns true. If unsuccessful, will return false with error message

◆ PolicyFlushOn()

void serenity::targets::FileTarget::PolicyFlushOn ( )

overrideprotectedvirtualinherited

Compares current flush setting and executes that policy if active. Current policies are: always flush, never flush, LogLevel-based flushing and time-based flushing. Time based flushing uses a background thread worker which will intermittenly lock the file when elapsed time is reached from "flushEvery" setting, flush the contents to disk, and then unlock the file for further writes

Reimplemented from serenity::targets::TargetBase.

◆ PrintMessage()

void serenity::experimental::targets::RotatingTarget::PrintMessage ( std::string_view formatted )

overridevirtual

Checks if background flush thread is active, if it is - will lock access to the file for writing. If rotate setting is enabled, will check that the file size doesn't exceed file size limit and writes the message to the file. If the file size would exceed the limit, closes the current file and rotates to next file before writing the message. This function will then follow any settings active in the flush policy

Parameters

formatted The actual message in its entirety to send to the output destination.

Reimplemented from serenity::targets::FileTarget.

◆ RenameFile()

bool serenity::experimental::targets::RotatingTarget::RenameFile ( std::string_view newFileName )

overridevirtual

Will close the current file being written to and replace the old file name with the new file name given. Previous files are unaffected. However, if cycling through rotation, future files will have this new name as their base as well.

Reimplemented from serenity::targets::FileTarget.

◆ RenameFileForRotation()

void serenity::experimental::targets::RotatingTarget::RenameFileForRotation ( )

This function will cache the file's name, extension, and path, as well as the log directory for the file before renaming the current file to the first iteration of the log file to rotate through. (Example: Rotate_Log.txt becomes Rotate_Log_01.txt). If this rotation-ready file already exists, will open the file by overwriting its contents and truncating its size to 0.

◆ RotateFileOnSize()

void serenity::experimental::targets::RotatingTarget::RotateFileOnSize ( )

If the logger should rotate, will close the current file, increment the file count up to max number of files set, and try to open the next file in iteration. If file already exists, will remove the oldest file with the given file name base before opening the next file in iteration. If the setting rotateFile is set to false, this function will return and do nothing else.

◆ SetFlushPolicy()

void serenity::targets::TargetBase::SetFlushPolicy ( serenity::experimental::Flush_Policy pPolicy )

inherited

Parameters

pPolicy refers to any settings that are added or changed by the user, including whether to flush always, never, or periodically.

On top of having options to never flush, always flush, and periodically flush, the Flush_Policy class includes the settings for whether flushing should occur based on a time-interval or log level if the periodical flushing option is enabled.

◆ SetLoggerName()

void serenity::targets::TargetBase::SetLoggerName ( std::string_view name )

inherited

Parameters

name	the name that the logger itself will use and be identified by

◆ SetLogLevel()

void serenity::targets::TargetBase::SetLogLevel ( LoggerLevel level )

inherited

For example, if "SetLogLevel(LoggerLevel::Error);" is used, then no messages below LoggerLevel::Error will be logged, however once a Fatal or Error message is made, then they would be logged to the output destination

Parameters

level - the logger level threshold that will determine if a message should be logged or not

◆ SetPattern()

void serenity::targets::TargetBase::SetPattern ( std::string_view pattern )

inherited

Sets the format pattern variable and parses the format string for internal storage and usage of this pattern by initializing and moving the initialized formatter struct in charge of the respective flag to a Formatters container

Parameters

pattern - the format pattern to store. This pattern is what determines how the prepended text will be displayed before the log message

◆ SetRotateSettings()

void serenity::experimental::targets::RotatingTarget::SetRotateSettings ( RotateSettings settings )

Current options revolve aroundfile size settings only and can be found in the RotateSettings class.

Parameters

settings controls the following: file size limit, number of files to rotate through, and whether or not the logger should rotate through files up to the max number of files set

◆ Trace()

template<typename... Args>

serenity::targets::TargetBase::Trace	(	std::string_view	msg,
		Args &&...	args
	)

inherited

Checks if the message should be logged via the log level threshold setting. If it isn't, immediately returns. If the message should be logged, this function will then perform a quick check on whether or not writes to the buffer were enabled and will write to the buffer if they were. If writes to the buffers weren't enabled, then PrintMessage( ) will be called and the derived target handles how this is implemented. After writing the message, follows the derived target's PolicyFlushOn( ) implementation

Template Parameters

msg	The message being passed in. Follows C++20's format library and libfmt's substitution model using "{}" to replace any arguments from the `args` parameter.
args	Variadic placeholder for any number of and any type of arguments to use in substituion.

◆ Warn()

template<typename... Args>

serenity::targets::TargetBase::Warn	(	std::string_view	msg,
		Args &&...	args
	)

inherited

Checks if the message should be logged via the log level threshold setting. If it isn't, immediately returns. If the message should be logged, this function will then perform a quick check on whether or not writes to the buffer were enabled and will write to the buffer if they were. If writes to the buffers weren't enabled, then PrintMessage( ) will be called and the derived target handles how this is implemented. After writing the message, follows the derived target's PolicyFlushOn( ) implementation

Template Parameters

msg	The message being passed in. Follows C++20's format library and libfmt's substitution model using "{}" to replace any arguments from the `args` parameter.
args	Variadic placeholder for any number of and any type of arguments to use in substituion.

◆ WriteToBaseBuffer()

void serenity::targets::TargetBase::WriteToBaseBuffer ( bool fmtToBuf = true )

inherited

When writing to the buffer, messages will be appended with the platform-specific end of line before being added to the buffer. When Flush( ) is called, if writing to the buffer was enabled, the buffer contents will now be written to the file and then flushed to disk. Disabled by default.

Parameters

fmtToBuf the value that controls whether or not buffer writes are enabled/disabled

Member Data Documentation

◆ fileHandle

serenity::targets::FileTarget::fileHandle

protectedinherited

This variable is protected to avoid duplication if using RotatingTarget class due to it inheriting from this class.

◆ fileOptions

serenity::targets::FileTarget::fileOptions

protectedinherited

See also: FileSettings

◆ flushWorker

serenity::targets::FileTarget::flushWorker

protectedinherited

See also: BackgroundThread

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

RotatingTarget.h
Documentation.h
RotatingTarget.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ RotatingTarget() [1/3]

◆ RotatingTarget() [2/3]

◆ RotatingTarget() [3/3]

◆ ~RotatingTarget()

Member Function Documentation

◆ CloseFile()

◆ Debug()

◆ Error()

◆ Fatal()

◆ Info()

◆ OpenFile()

◆ PolicyFlushOn()

◆ PrintMessage()

◆ RenameFile()

◆ RenameFileForRotation()

◆ RotateFileOnSize()

◆ SetFlushPolicy()

◆ SetLoggerName()

◆ SetLogLevel()

◆ SetPattern()

◆ SetRotateSettings()

◆ Trace()

◆ Warn()

◆ WriteToBaseBuffer()

Member Data Documentation

◆ fileHandle

◆ fileOptions

◆ flushWorker