Class for logging into files. More...

#include <FileSink.hpp>

Inheritance diagram for sl::log::FileSink< TRecord >:

Classes
struct	CleanupRule
	Type for configuring FileSink cleanup rules. More...

struct	RotationRule
	Type for configuring FileSink rotation rules. More...

Public Types
using	Record_t = std::remove_cvref_t< TRecord >
	Used Record type. More...

using	FlushPolicy_t = std::unique_ptr< detail::AbstractFlushPolicyWrapper< Record_t > >

using	Projections_t = RecordGetters< Record_t >

using	Formatter_t = std::function< std::string(const Record_t &)>

using	Filter_t = std::function< bool(const Record_t &)>

Public Member Functions
	FileSink (std::string fileNamePattern, std::filesystem::path directory=std::filesystem::current_path())
	Constructor. More...

	~FileSink () noexcept
	Destructor. More...

	FileSink (const FileSink &)=delete
	Deleted copy constructor. More...

FileSink &	operator= (const FileSink &)=delete
	Deleted copy assign operator. More...

	FileSink (FileSink &&)=delete
	Deleted move constructor. More...

FileSink &	operator= (FileSink &&)=delete
	Deleted move assign operator. More...

void	setRotationRule (RotationRule rule) noexcept
	Applies a new RotationRule configuration. More...

RotationRule	rotationRule () const noexcept
	Returns a copy of the current RotationRule configuration. More...

void	rotate ()
	Rotates the current file. More...

void	setCleanupRule (CleanupRule rule) noexcept
	Applies a new CleanupRule configuration. More...

CleanupRule	cleanupRule () const noexcept
	Returns a copy of the current CleanupRule configuration. More...

template<FileStateHandler THandler>
void	setOpeningHandler (THandler &&handler) noexcept
	Applies a new handler for opening files. More...

void	removeOpeningHandler () noexcept
	Removes the active opening handler. More...

template<FileStateHandler THandler>
void	setClosingHandler (THandler &&handler) noexcept
	Applies a new handler for closing files. More...

void	removeClosingHandler () noexcept
	Removes the active closing handler. More...

void	setDirectory (std::filesystem::path directory)
	Sets the directory in which the log files will be created. More...

std::filesystem::path	directory () const noexcept
	Getter of the directory member. More...

void	setFileNamePattern (std::string fileNamePattern)
	Sets the file name pattern for generated log files. More...

std::string	fileNamePattern () const noexcept
	Getter of the used file name pattern string. More...

template<FlushPolicyFor< Record_t > TPolicy>
void	setFlushPolicy (TPolicy &&policy)
	Sets the active Flush-Policy. More...

void	removeFlushPolicy ()
	Replaces the current Flush-Policy with the default one. More...

void	flush ()
	Flushes all pending output of the internal stream. More...

void	log (const Record_t &record) final override
	Handles the given Record object. More...

void	setEnabled (bool enable=true) noexcept final override
	Enables or disables the Sink object. More...

bool	isEnabled () const noexcept final override
	Checks if the Sink object is enabled. More...

template<RecordFormatterFor< Record_t > TFormatter>
void	setFormatter (TFormatter &&formatter)
	Sets the active formatter. More...

void	removeFormatter ()
	Replaces the active formatter with the default one. More...

template<RecordFilterFor< Record_t > TFilter>
void	setFilter (TFilter &&filter)
	Sets the active filter. More...

void	removeFilter ()
	Replaces the active filter with the default one. More...

Protected Member Functions
template<class TData >
void	writeToStream (TData &&data)
	Writes directly to the internal stream. More...

virtual void	afterMessageWrite (const Record_t &record, std::string_view message)
	Virtual method which will be called after the actual message is written to the stream. More...

Static Protected Member Functions
static constexpr FlushPolicy_t	defaultFlushPolicy () noexcept

static constexpr Formatter_t	defaultFormatter () noexcept

static constexpr Filter_t	defaultFilter () noexcept

Detailed Description

template<Record TRecord>
class sl::log::FileSink< TRecord >

Class for logging into files.

Template Parameters

TRecord Used Record type.

Instances of this class are linked to a specific file and writes every Record into it. Users can setup rotation and cleanup rules.

File name pattern

Users can provide a pattern string, which will be used for newly generated file names. Those file names will be generated when a new file shall be opened. There are mainly two parts of those strings:

Constant parts are all substrings which do not contain any known tokens and will simply be used as is in file names.
Dynamic parts are substrings which contain know tokens, which will be replaced with actual data when a new file name will be generated. Look at the token section of this page for further details.

Tokens

Each token begins with %

Token	Effect
%Y	year in 4 digits
%m	month in 2 digits (including leading zeros)
%d	day of month in 2 digits (including leading zeros)
%j	day of year
%H	hour in 24h format (2 digits with leading zeros)
%M	minute (2 digits with leading zeros)
%S	second (2 digits with leading zeros)
%N	incrementing number starting at 1
%xN	incrementing number with x digits and leading zeros. Replace x with an actual number (might be multiple digits). Starts at 1.

Rotation

Rotation rules are used as an indicator when to switch to a new file. Currently are two basic rules implemented:

file size
duration

Each rule will be checked before a new Record will be written to file. If a new file shall be opened, a new file name will be generated via provided file name pattern. If this file already exists, it will be overriden (or an exception raises if it is already in use).

Cleanup

While rotation is used for indicating when to switch files, CleanupRule s are used for determining when to delete old files. Cleanup process will watch at the currently provided directory and will only observe files with equally file extensions as provided in the file name pattern. If no extension (e.g. .abcd) is used, all files without an extension will be observed.

File state handler

These handler are used to generate messages on state changes for the internal managed file. Users can provide invokable objects, which will be called and shall return a std::string, which will then written synchronized to the std::fstream. The synchronization is the reason, why the user is not allowed to write to the stream themselves.
Handlers shall have the following signature:

std::string()

Examples: CustomRecordType/main.cpp, CustomizeBaseRecord/main.cpp, and FileLogging/main.cpp.

Member Typedef Documentation

◆ Filter_t

template<Record TRecord>

using sl::log::BasicSink< TRecord >::Filter_t = std::function<bool(const Record_t&)>

inherited

◆ FlushPolicy_t

template<Record TRecord>

using sl::log::OStreamSink< TRecord >::FlushPolicy_t = std::unique_ptr<detail::AbstractFlushPolicyWrapper<Record_t> >

inherited

◆ Formatter_t

template<Record TRecord>

using sl::log::BasicSink< TRecord >::Formatter_t = std::function<std::string(const Record_t&)>

inherited

◆ Projections_t

template<Record TRecord>

using sl::log::BasicSink< TRecord >::Projections_t = RecordGetters<Record_t>

inherited

◆ Record_t

template<Record TRecord>

using sl::log::ISink< TRecord >::Record_t = std::remove_cvref_t<TRecord>

Used Record type.

Constructor & Destructor Documentation

◆ FileSink() [1/3]

template<Record TRecord>

sl::log::FileSink< TRecord >::FileSink	(	std::string	fileNamePattern,
		std::filesystem::path	directory = `std::filesystem::current_path()`
	)

inlineexplicit

Constructor.

Parameters

fileNamePattern	Pattern string from which new file names will be generated.
directory	The directory where all files of this sink will be generated.

Constructs a new FileSink instance, which uses the provided file name pattern for newly opened files at the specified directory.

Remarks: It is not intended, that the pattern string contains any directory information. Use the directory property instead.

Exceptions

SinkException if pattern string is empty or contains directory information

◆ ~FileSink()

template<Record TRecord>

sl::log::FileSink< TRecord >::~FileSink ( )

inlinenoexcept

Destructor.

Finalizes and closes the current opened file (if any).

◆ FileSink() [2/3]

template<Record TRecord>

sl::log::FileSink< TRecord >::FileSink ( const FileSink< TRecord > & )

delete

Deleted copy constructor.

◆ FileSink() [3/3]

template<Record TRecord>

sl::log::FileSink< TRecord >::FileSink ( FileSink< TRecord > && )

delete

Deleted move constructor.

Member Function Documentation

◆ afterMessageWrite()

template<Record TRecord>

virtual void sl::log::OStreamSink< TRecord >::afterMessageWrite	(	const Record_t &	record,
		std::string_view	message
	)

inlineprotectedvirtualinherited

Virtual method which will be called after the actual message is written to the stream.

Parameters

record	The current handled Record object
message	The final message

Remarks: The stream associated mutex is locked before this function gets invoked.

Version: since alpha-0.6

◆ cleanupRule()

template<Record TRecord>

CleanupRule sl::log::FileSink< TRecord >::cleanupRule ( ) const

inlinenoexcept

Returns a copy of the current CleanupRule configuration.

◆ defaultFilter()

template<Record TRecord>

static constexpr Filter_t sl::log::BasicSink< TRecord >::defaultFilter ( )

inlinestaticconstexprprotectednoexceptinherited

◆ defaultFlushPolicy()

template<Record TRecord>

static constexpr FlushPolicy_t sl::log::OStreamSink< TRecord >::defaultFlushPolicy ( )

inlinestaticconstexprprotectednoexceptinherited

◆ defaultFormatter()

template<Record TRecord>

static constexpr Formatter_t sl::log::BasicSink< TRecord >::defaultFormatter ( )

inlinestaticconstexprprotectednoexceptinherited

◆ directory()

template<Record TRecord>

std::filesystem::path sl::log::FileSink< TRecord >::directory ( ) const

inlinenoexcept

Getter of the directory member.

Returns: A copy of the path object

◆ fileNamePattern()

template<Record TRecord>

std::string sl::log::FileSink< TRecord >::fileNamePattern ( ) const

inlinenoexcept

Getter of the used file name pattern string.

Returns: Returns a copy of the active pattern string

◆ flush()

template<Record TRecord>

void sl::log::OStreamSink< TRecord >::flush ( )

inlineinherited

Flushes all pending output of the internal stream.

Remarks: Internally locks the associated stream mutex.

◆ isEnabled()

template<Record TRecord>

bool sl::log::BasicSink< TRecord >::isEnabled ( ) const

inlinefinaloverridevirtualnoexceptinherited

Checks if the Sink object is enabled.

Returns: Returns true if object is enabled.

Implements sl::log::ISink< TRecord >.

◆ log()

template<Record TRecord>

void sl::log::BasicSink< TRecord >::log ( const Record_t & record )

inlinefinaloverridevirtualinherited

Handles the given Record object.

Before the Record gets passed to the actual destination, it will be checked if the Sink object is enabled and if the Record should be filtered. If these checks are passed, the abstract writeMessage function will be invoked with the finally formatted message string.

Parameters

record Record object

Implements sl::log::ISink< TRecord >.

◆ operator=() [1/2]

template<Record TRecord>

FileSink& sl::log::FileSink< TRecord >::operator= ( const FileSink< TRecord > & )

delete

Deleted copy assign operator.

◆ operator=() [2/2]

template<Record TRecord>

FileSink& sl::log::FileSink< TRecord >::operator= ( FileSink< TRecord > && )

delete

Deleted move assign operator.

◆ removeClosingHandler()

template<Record TRecord>

void sl::log::FileSink< TRecord >::removeClosingHandler ( )

inlinenoexcept

Removes the active closing handler.

◆ removeFilter()

template<Record TRecord>

void sl::log::BasicSink< TRecord >::removeFilter ( )

inlineinherited

Replaces the active filter with the default one.

◆ removeFlushPolicy()

template<Record TRecord>

void sl::log::OStreamSink< TRecord >::removeFlushPolicy ( )

inlineinherited

Replaces the current Flush-Policy with the default one.

The default Flush-Policy flushes after each handled Record.

◆ removeFormatter()

template<Record TRecord>

void sl::log::BasicSink< TRecord >::removeFormatter ( )

inlineinherited

Replaces the active formatter with the default one.

◆ removeOpeningHandler()

template<Record TRecord>

void sl::log::FileSink< TRecord >::removeOpeningHandler ( )

inlinenoexcept

Removes the active opening handler.

◆ rotate()

template<Record TRecord>

void sl::log::FileSink< TRecord >::rotate ( )

inline

Rotates the current file.

This function has no effect, if the file stream is not already open.

◆ rotationRule()

template<Record TRecord>

RotationRule sl::log::FileSink< TRecord >::rotationRule ( ) const

inlinenoexcept

Returns a copy of the current RotationRule configuration.

◆ setCleanupRule()

template<Record TRecord>

void sl::log::FileSink< TRecord >::setCleanupRule ( CleanupRule rule )

inlinenoexcept

Applies a new CleanupRule configuration.

Parameters

rule	The new CleanupRule configuration.

◆ setClosingHandler()

template<Record TRecord>

template<FileStateHandler THandler>

void sl::log::FileSink< TRecord >::setClosingHandler ( THandler && handler )

inlinenoexcept

Applies a new handler for closing files.

For further details look at file state handler.

Template Parameters

THandler Type of handler (automatically deduced)

Parameters

handler invokable handler object

◆ setDirectory()

template<Record TRecord>

void sl::log::FileSink< TRecord >::setDirectory ( std::filesystem::path directory )

inline

Sets the directory in which the log files will be created.

Parameters

directory Path object

If the given directory does not exist, it will be created.

◆ setEnabled()

template<Record TRecord>

void sl::log::BasicSink< TRecord >::setEnabled ( bool enable = true )

inlinefinaloverridevirtualnoexceptinherited

Enables or disables the Sink object.

Disabled Sinks will not handle any incoming Record s

Parameters

enable True will enable the Sink object.

Implements sl::log::ISink< TRecord >.

◆ setFileNamePattern()

template<Record TRecord>

void sl::log::FileSink< TRecord >::setFileNamePattern ( std::string fileNamePattern )

inline

Sets the file name pattern for generated log files.

Parameters

fileNamePattern Pattern string

For further details look here.

Remarks: It is not intended, that the pattern string contains any directory information. Use the directory property instead.

Exceptions

SinkException if pattern string is empty or contains directory information

◆ setFilter()

template<Record TRecord>

template<RecordFilterFor< Record_t > TFilter>

void sl::log::BasicSink< TRecord >::setFilter ( TFilter && filter )

inlineinherited

Sets the active filter.

It's the filters job to decide, which Record will be printed (filter returns true) and which will be skipped (filter returns false). Therefore a filter must be an invokable of the following signature:

bool(const Record&)

sl::log::Record

concept Record

Concept which all the necessary concepts for Record types.

Definition: Record.hpp:204

Remarks: The filters return type doesn't have to be bool, but the returned object must at least be implicitly convertible to bool.

Template Parameters

TFilter Type of the passed filter (automatically deduced)

Parameters

filter An invokable filter object

Examples: FileLogging/main.cpp.

◆ setFlushPolicy()

template<Record TRecord>

template<FlushPolicyFor< Record_t > TPolicy>

void sl::log::OStreamSink< TRecord >::setFlushPolicy ( TPolicy && policy )

inlineinherited

Sets the active Flush-Policy.

Template Parameters

TPolicy Type of the passed Flush-Policy (automatically deduced)

Parameters

policy The new Flush-Policy object

◆ setFormatter()

template<Record TRecord>

template<RecordFormatterFor< Record_t > TFormatter>

void sl::log::BasicSink< TRecord >::setFormatter ( TFormatter && formatter )

inlineinherited

Sets the active formatter.

It's the formatters job to extract the necessary information from Records and built the final message string.

A custom formatter should use the following signature:

std::string(const Record&)

Template Parameters

TFormatter Type of the passed formatter (automatically deduced)

Parameters

formatter An invokable formatter object

◆ setOpeningHandler()

template<Record TRecord>

template<FileStateHandler THandler>

void sl::log::FileSink< TRecord >::setOpeningHandler ( THandler && handler )

inlinenoexcept

Applies a new handler for opening files.

For further details look at file state handler.

Template Parameters

THandler Type of handler (automatically deduced)

Parameters

handler invokable handler object

◆ setRotationRule()

template<Record TRecord>

void sl::log::FileSink< TRecord >::setRotationRule ( RotationRule rule )

inlinenoexcept

Applies a new RotationRule configuration.

Parameters

rule	The new RotationRule configuration.

◆ writeToStream()

template<Record TRecord>

template<class TData >

void sl::log::OStreamSink< TRecord >::writeToStream ( TData && data )

inlineprotectedinherited

Writes directly to the internal stream.

Template Parameters

TData Type of data (automatically deduced)

Parameters

data	Data which will be written to the stream.

This functions writes directly to the stream object. No filter or formatter will be involved and stream will be flush afterwards. This might be useful for writing custom header or footer data to the stream.

Remarks: If not already locked, this function will lock the stream associated mutex.

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

FileSink.hpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Detailed Description

template<Record TRecord> class sl::log::FileSink< TRecord >

File name pattern

Tokens

Rotation

Cleanup

File state handler

Member Typedef Documentation

◆ Filter_t

◆ FlushPolicy_t

◆ Formatter_t

◆ Projections_t

◆ Record_t

Constructor & Destructor Documentation

◆ FileSink() [1/3]

◆ ~FileSink()

◆ FileSink() [2/3]

◆ FileSink() [3/3]

Member Function Documentation

◆ afterMessageWrite()

◆ cleanupRule()

◆ defaultFilter()

◆ defaultFlushPolicy()

◆ defaultFormatter()

◆ directory()

◆ fileNamePattern()

◆ flush()

◆ isEnabled()

◆ log()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ removeClosingHandler()

◆ removeFilter()

◆ removeFlushPolicy()

◆ removeFormatter()

◆ removeOpeningHandler()

◆ rotate()

◆ rotationRule()

◆ setCleanupRule()

◆ setClosingHandler()

◆ setDirectory()

◆ setEnabled()

◆ setFileNamePattern()

◆ setFilter()

◆ setFlushPolicy()

◆ setFormatter()

◆ setOpeningHandler()

◆ setRotationRule()

◆ writeToStream()

template<Record TRecord>
class sl::log::FileSink< TRecord >