ball::AsyncFileObserver Class Reference

#include <ball_asyncfileobserver.h>

Inheritance diagram for ball::AsyncFileObserver:

Public Types
typedef FileObserver::OnFileRotationCallback	OnFileRotationCallback

Public Member Functions
	BSLMF_NESTED_TRAIT_DECLARATION (AsyncFileObserver, bslma::UsesBslmaAllocator)
	AsyncFileObserver (bslma::Allocator *basicAllocator=0)
	AsyncFileObserver (Severity::Level stdoutThreshold, bslma::Allocator *basicAllocator=0)
	AsyncFileObserver (Severity::Level stdoutThreshold, bool publishInLocalTime, bslma::Allocator *basicAllocator=0)
	AsyncFileObserver (Severity::Level stdoutThreshold, bool publishInLocalTime, int maxRecordQueueSize, bslma::Allocator *basicAllocator=0)
	AsyncFileObserver (Severity::Level stdoutThreshold, bool publishInLocalTime, int maxRecordQueueSize, Severity::Level dropRecordsOnFullQueueThreshold, bslma::Allocator *basicAllocator=0)
	~AsyncFileObserver () BSLS_KEYWORD_OVERRIDE
void	disableFileLogging ()
void	disablePublishInLocalTime ()
void	disableSizeRotation ()
void	disableStdoutLoggingPrefix ()
void	disableTimeIntervalRotation ()
int	enableFileLogging (const char *logFilenamePattern)
void	enableStdoutLoggingPrefix ()
void	enablePublishInLocalTime ()
void	forceRotation ()
void	publish (const bsl::shared_ptr< const Record > &record, const Context &context) BSLS_KEYWORD_OVERRIDE
void	releaseRecords () BSLS_KEYWORD_OVERRIDE
void	rotateOnSize (int size)
void	rotateOnTimeInterval (const bdlt::DatetimeInterval &interval)
void	rotateOnTimeInterval (const bdlt::DatetimeInterval &interval, const bdlt::Datetime &startTime)
void	setLogFormat (const char *logFileFormat, const char *stdoutFormat)
void	setOnFileRotationCallback (const OnFileRotationCallback &onRotationCallback)
void	setStdoutThreshold (Severity::Level stdoutThreshold)
int	shutdownPublicationThread ()
int	startPublicationThread ()
int	stopPublicationThread ()
void	suppressUniqueFileNameOnRotation (bool suppress)
void	getLogFormat (const char **logFileFormat, const char **stdoutFormat) const
bool	isFileLoggingEnabled () const
bool	isFileLoggingEnabled (bsl::string *result) const
bool	isFileLoggingEnabled (std::string *result) const
bool	isPublicationThreadRunning () const
bool	isPublishInLocalTimeEnabled () const
bool	isStdoutLoggingPrefixEnabled () const
bool	isSuppressUniqueFileNameOnRotation () const
bool	isUserFieldsLoggingEnabled () const
bdlt::DatetimeInterval	localTimeOffset () const
bsl::size_t	recordQueueLength () const
bdlt::DatetimeInterval	rotationLifetime () const
int	rotationSize () const
Severity::Level	stdoutThreshold () const
virtual void	publish (const Record &record, const Context &context)
virtual void	publish (const bsl::shared_ptr< const Record > &record, const Context &context)
Public Member Functions inherited from ball::Observer
virtual	~Observer ()
	Destroy this observer.

Detailed Description

This class implements the Observer protocol. The publish method of this class outputs log records asynchronously to stdout and optionally to a user-specified file. This class is thread-safe; different threads can operate on an object concurrently. This class is exception-neutral with no guarantee of rollback. In no event is memory leaked.

See ball_asyncfileobserver

Member Typedef Documentation

OnFileRotationCallback

typedef FileObserver::OnFileRotationCallback ball::AsyncFileObserver::OnFileRotationCallback

OnFileRotationCallback is an alias for a user-supplied callback function that is invoked after the file observer attempts to rotate its log file. The callback takes two arguments: (1) an integer status value where 0 indicates a new log file was successfully created and a non-zero value indicates an error occurred during rotation, and (2) a string that provides the name of the rotated log file if the rotation was successful. E.g.:

void onLogFileRotation(int                rotationStatus,
                       const bsl::string& rotatedLogFileName);

Constructor & Destructor Documentation

AsyncFileObserver() [1/5]

ball::AsyncFileObserver::AsyncFileObserver ( bslma::Allocator *  basicAllocator = 0 )

explicit

AsyncFileObserver() [2/5]

ball::AsyncFileObserver::AsyncFileObserver ( Severity::Level  stdoutThreshold, bslma::Allocator *  basicAllocator = 0  )

explicit

Create an async file observer that asynchronously publishes log records to stdout if their severity is at least as severe as the optionally specified stdoutThreshold level, and has file logging initially disabled. If stdoutThreshold is not specified, log records are published to stdout if their severity is at least as severe as Severity::e_WARN. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. Records received by the publish method are appended to a queue having a maximum (fixed) length of 8192, and published later by an independent publication thread. All records received while the queue is full are discarded. (See {Log Record Queue} for further information.) Note that isPublishInLocalTimeEnabled returns false following construction indicating that the timestamp attribute of published records will be written in UTC time (see enablePublishInLocalTime). Also note that independent default record formats are in effect for stdout and file logging (see setLogFormat).

AsyncFileObserver() [3/5]

ball::AsyncFileObserver::AsyncFileObserver	(	Severity::Level	stdoutThreshold,
		bool	publishInLocalTime,
		bslma::Allocator *	basicAllocator = 0
	)

Create an async file observer that asynchronously publishes log records to stdout if their severity is at least as severe as the specified stdoutThreshold level, and has file logging initially disabled. The timestamp attribute of published records is written in local time if the specified publishInLocalTime flag is true, and in UTC time otherwise. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. Records received by the publish method are appended to a queue having a maximum (fixed) length of 8192, and published later by an independent publication thread. All records received while the queue is full are discarded. (See {Log Record Queue} for further information.) Note that independent default record formats are in effect for stdout and file logging (see setLogFormat).

AsyncFileObserver() [4/5]

ball::AsyncFileObserver::AsyncFileObserver	(	Severity::Level	stdoutThreshold,
		bool	publishInLocalTime,
		int	maxRecordQueueSize,
		bslma::Allocator *	basicAllocator = 0
	)

AsyncFileObserver() [5/5]

ball::AsyncFileObserver::AsyncFileObserver	(	Severity::Level	stdoutThreshold,
		bool	publishInLocalTime,
		int	maxRecordQueueSize,
		Severity::Level	dropRecordsOnFullQueueThreshold,
		bslma::Allocator *	basicAllocator = 0
	)

Create an async file observer that asynchronously publishes log records to stdout if their severity is at least as severe as the specified stdoutThreshold level, and has file logging initially disabled. The timestamp attribute of published records is written in local time if the specified publishInLocalTime flag is true, and in UTC time otherwise. Records received by the publish method are appended to a queue having the specified (fixed) maxRecordQueueSize, and published later by an independent publication thread. Optionally specify a dropRecordsOnFullQueueThreshold indicating the severity threshold below which records received when the queue is full will be discarded; records received whose severity is at least as severe as this threshold will block the calling thread if the queue is full, until space is available. If dropRecordsOnFullQueueThreshold is not specified, all records received while the queue is full are discarded. (See {Log Record Queue} for further information.) Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. Note that independent default record formats are in effect for stdout and file logging (see setLogFormat).

~AsyncFileObserver()

ball::AsyncFileObserver::~AsyncFileObserver

(

)

Publish all records that were on the record queue upon entry if a publication thread is running, stop the publication thread (if any), close the log file if file logging is enabled, and destroy this async file observer.

Member Function Documentation

BSLMF_NESTED_TRAIT_DECLARATION()

ball::AsyncFileObserver::BSLMF_NESTED_TRAIT_DECLARATION	(	AsyncFileObserver	,
		bslma::UsesBslmaAllocator
	)

disableFileLogging()

void ball::AsyncFileObserver::disableFileLogging ( )

inline

Disable file logging for this async file observer. This method has no effect if file logging is not enabled. Calling this method will prevent the logging to a file of any unpublished records held by this observer. Note that records subsequently received through the publish method as well as those that are currently on the queue may still be logged to stdout after calling this method.

disablePublishInLocalTime()

void ball::AsyncFileObserver::disablePublishInLocalTime ( )

inline

Disable publishing of the timestamp attribute of records in local time by this async file observer; henceforth, timestamps will be in UTC time. This method has no effect if publishing in local time is not enabled. Note that this method also affects log filenames (see {Log Filename Patterns}). Also note that this method affects records subsequently received through the publish method as well as those that are currently on the queue.

disableSizeRotation()

void ball::AsyncFileObserver::disableSizeRotation ( )

inline

Disable log file rotation based on log file size for this async file observer. This method has no effect if rotation-on-size is not enabled.

disableStdoutLoggingPrefix()

void ball::AsyncFileObserver::disableStdoutLoggingPrefix ( )

inline

Disable this async file observer from using the long output format when logging to stdout. Henceforth, this async file observer will use the default short output format ("\n%s %f:%l %c %m %u\n") when logging to stdout. This method has no effect if the long output format for stdout logging is not enabled. Note that this method omits the "%d %p:%t " prefix from the default long output format. Also note that this method affects records subsequently received through the publish method as well as those that are currently on the queue.

disableTimeIntervalRotation()

void ball::AsyncFileObserver::disableTimeIntervalRotation ( )

inline

Disable log file rotation based on a periodic time interval for this async file observer. This method has no effect if rotation-on-time-interval is not enabled.

enableFileLogging()

int ball::AsyncFileObserver::enableFileLogging ( const char *  logFilenamePattern )

inline

Enable logging of all records published to this async file observer to a file whose name is derived from the specified logFilenamePattern. Return 0 on success, a positive value if file logging is already enabled (with no effect), and a negative value otherwise. The basename of logFilenamePattern may contain %-escape sequences that are interpreted as follows:

 %Y - current year   (4 digits with leading zeros)
 %M - current month  (2 digits with leading zeros)
 %D - current day    (2 digits with leading zeros)
 %h - current hour   (2 digits with leading zeros)
 %m - current minute (2 digits with leading zeros)
 %s - current second (2 digits with leading zeros)
 %T - current datetime, equivalent to "%Y%M%D_%h%m%s"
 %p - process ID

Each time a log file is opened by this async file observer (upon a successful call to this method and following each log file rotation), the name of the new log file is derived from logFilenamePattern by interpreting the above recognized %-escape sequences. If isPublishInLocalTimeEnabled returns true, the %-escape sequences related to time will be substituted with local time values, and UTC time values otherwise. Note that, if a publication thread is running, it will now publish queued records to the log file where it previously was only publishing queued records to stdout.

enablePublishInLocalTime()

void ball::AsyncFileObserver::enablePublishInLocalTime ( )

inline

Enable publishing of the timestamp attribute of records in local time by this async file observer. This method has no effect if publishing in local time is already enabled. Note that this method also affects log filenames (see {Log Filename Patterns}). Also note that this method affects records subsequently received through the publish method as well as those that are currently on the queue.

enableStdoutLoggingPrefix()

void ball::AsyncFileObserver::enableStdoutLoggingPrefix ( )

inline

Enable this async file observer to use the long output format when logging to stdout. Henceforth, this async file observer will use the output format for stdout logging that was set by the most recent call to setLogFormat, or the default long output format ("\n%d %p:%t %s %f:%l %c %m %u\n") if setLogFormat has not yet been called. This method has no effect if the long output format for stdout logging is already enabled. Note that this method affects records subsequently received through the publish method as well as those that are currently on the queue.

forceRotation()

void ball::AsyncFileObserver::forceRotation ( )

inline

Forcefully perform a log file rotation by this async file observer. Close the current log file, rename the log file if necessary, and open a new log file. This method has no effect if file logging is not enabled. See {Rotated File Naming} for details on filenames of rotated log files.

getLogFormat()

void ball::AsyncFileObserver::getLogFormat ( const char **  logFileFormat, const char **  stdoutFormat  ) const

inline

Load the format specification for log records written by this async file observer to the log file into the specified *logFileFormat address and the format specification for log records written to stdout into the specified *stdoutFormat address. See {Log Record Formatting} for details on the syntax of format specifications.

isFileLoggingEnabled() [1/3]

bool ball::AsyncFileObserver::isFileLoggingEnabled ( ) const

inline

Return true if file logging is enabled for this async file observer, and false otherwise. Load the optionally specified result with the name of the current log file if file logging is enabled, and leave result unmodified otherwise. Note that records received through the publish method of this async file observer may still be logged to stdout when this method returns false.

isFileLoggingEnabled() [2/3]

bool ball::AsyncFileObserver::isFileLoggingEnabled ( bsl::string *  result ) const

inline

isFileLoggingEnabled() [3/3]

bool ball::AsyncFileObserver::isFileLoggingEnabled ( std::string *  result ) const

inline

isPublicationThreadRunning()

bool ball::AsyncFileObserver::isPublicationThreadRunning ( ) const

inline

Return true if a publication thread is running, and false otherwise. Note that records received by the publish method will still be added to the record queue even if there is no publication thread running.

isPublishInLocalTimeEnabled()

bool ball::AsyncFileObserver::isPublishInLocalTimeEnabled ( ) const

inline

Return true if this async file observer writes the timestamp attribute of records that it publishes in local time, and false otherwise (in which case timestamps are written in UTC time). Note that the value returned by this method also affects log filenames (see {Log Filename Patterns}).

isStdoutLoggingPrefixEnabled()

bool ball::AsyncFileObserver::isStdoutLoggingPrefixEnabled ( ) const

inline

Return true if this async file observer uses the long output format when writing to stdout, and false otherwise (in which case the default short output format is used). See enableStdoutLoggingPrefix and disableStdoutLoggingPrefix.

isSuppressUniqueFileNameOnRotation()

bool ball::AsyncFileObserver::isSuppressUniqueFileNameOnRotation ( ) const

inline

Return true if the log filename uniqueness check on rotation is suppressed, and false otherwise.

isUserFieldsLoggingEnabled()

bool ball::AsyncFileObserver::isUserFieldsLoggingEnabled ( ) const

inline

Return true if the logging of user-defined fields is enabled for this async file observer, and false otherwise.

Deprecated:

Do not use.

localTimeOffset()

bdlt::DatetimeInterval ball::AsyncFileObserver::localTimeOffset ( ) const

inline

Return the difference between the local time and UTC time in effect when this async file observer was constructed. Note that this value remains unchanged during the lifetime of this object and therefore may become incorrect when the difference between the local time and UTC time changes (e.g., when transitioning into or out of daylight savings time).

Deprecated:

Use bdlt::LocalTimeOffset instead.

publish() [1/3]

virtual void ball::Observer::publish ( const bsl::shared_ptr< const Record > &  record, const Context &  context  )

virtual

Process the specified log record having the specified publishing context. The exact definition of publish depends on the implementing class, though the intention is that the log record (whose publication has occurred according to context) be distributed in a human or machine readable form.

Reimplemented from ball::Observer.

publish() [2/3]

void ball::AsyncFileObserver::publish ( const bsl::shared_ptr< const Record > &  record, const Context &  context  )

virtual

Process the record referenced by the specified record shared pointer having the specified publishing context by writing the record and context to the current log file if file logging is enabled for this async file observer, and to stdout if the severity of record is at least as severe as the value returned by stdoutThreshold. record and context are appended to the record queue and published (asynchronously) later by the publication thread. If the queue is full, record and context are discarded unless the constructor taking dropRecordsOnFullQueueThreshold was used; if dropRecordsOnFullQueueThreshold was supplied with a Severity::Level at construction, record and context are discarded only if the severity of record is below that threshold, otherwise, this method will block waiting until space is available on the queue. See {Log Record Queue} for further information.

Reimplemented from ball::Observer.

publish() [3/3]

virtual void ball::Observer::publish ( const Record &  record, const Context &  context  )

virtual

Process the specified log record having the specified publishing context.

Deprecated:

Use the alternative publish overload instead.

Reimplemented from ball::Observer.

recordQueueLength()

bsl::size_t ball::AsyncFileObserver::recordQueueLength ( ) const

inline

Return the number of log records currently on the record queue of this async file observer.

releaseRecords()

void ball::AsyncFileObserver::releaseRecords ( )

virtual

Discard any shared references to Record objects that were supplied to the publish method, and are held by this observer. Note that this operation should be called if resources underlying the previously provided shared pointers must be released. Also note that all currently queued records are discarded.

Reimplemented from ball::Observer.

rotateOnSize()

void ball::AsyncFileObserver::rotateOnSize ( int  size )

inline

Set this async file observer to perform log file rotation when the size of the file exceeds the specified size (in kilobytes). This rule replaces any rotation-on-size rule currently in effect. The behavior is undefined unless size > 0.

rotateOnTimeInterval() [1/2]

void ball::AsyncFileObserver::rotateOnTimeInterval ( const bdlt::DatetimeInterval &  interval )

inline

rotateOnTimeInterval() [2/2]

void ball::AsyncFileObserver::rotateOnTimeInterval ( const bdlt::DatetimeInterval &  interval, const bdlt::Datetime &  startTime  )

inline

Set this file observer to perform a periodic log file rotation at multiples of the specified interval. Optionally specify a startTime indicating the datetime to use as the starting point for computing the periodic rotation schedule. If isPublishInLocalTimeEnabled is true, the startTime is interpreted as local time, and as a UTC time otherwise. If startTime is not specified, the current time is used. This rule replaces any rotation-on-time-interval rule currently in effect. The behavior is undefined unless 0 < interval.totalMilliseconds(). Note that startTime may be a fixed time in the past; e.g., a reference time of bdlt::Datetime(1, 1, 1) and an interval of 24 hours would configure a periodic rotation at midnight each day.

rotationLifetime()

bdlt::DatetimeInterval ball::AsyncFileObserver::rotationLifetime ( ) const

inline

Return the log file lifetime that will trigger a file rotation by this async file observer if rotation-on-lifetime is in effect, and a 0 time interval otherwise.

rotationSize()

int ball::AsyncFileObserver::rotationSize ( ) const

inline

Return the size (in kilobytes) of the log file that will trigger a file rotation by this async file observer if rotation-on-size is in effect, and 0 otherwise.

setLogFormat()

void ball::AsyncFileObserver::setLogFormat ( const char *  logFileFormat, const char *  stdoutFormat  )

inline

Set the format specifications for log records written to the log file and to stdout to the specified logFileFormat and stdoutFormat, respectively. If the default short output format is currently in effect for logging to stdout, this method has the effect of calling enableStdoutLoggingPrefix (see that method and disableStdoutLoggingPrefix). See {Log Record Formatting} for details on the syntax of format specifications. Note that default formats are in effect following construction until this method is called ("\n%d %p:%t %s %f:%l %c %m %u\n" for both file and stdout logging). Also note that the observer emits newline characters at the beginning and at the end of a log record by default, so the user needs to add them explicitly to the format string to preserve this behavior. Also note that this method affects records subsequently received through the publish method as well as those that are currently on the queue.

setOnFileRotationCallback()

void ball::AsyncFileObserver::setOnFileRotationCallback ( const OnFileRotationCallback &  onRotationCallback )

inline

Set the specified onRotationCallback to be invoked after each time this async file observer attempts to perform a log file rotation. The behavior is undefined if the supplied function calls either setOnFileRotationCallback, forceRotation, or publish on this async file observer (i.e., the supplied callback should not attempt to write to the ball log).

setStdoutThreshold()

void ball::AsyncFileObserver::setStdoutThreshold ( Severity::Level  stdoutThreshold )

inline

Set the minimum severity of records logged to stdout by this async file observer to the specified stdoutThreshold level. Note that if the value of stdoutThreshold is Severity::e_OFF, logging to stdout is disabled. Also note that this method affects records subsequently received through the publish method as well as those that are currently on the queue.

shutdownPublicationThread()

int ball::AsyncFileObserver::shutdownPublicationThread

(

)

Stop the publication thread without waiting for log records currently on the record queue to be published. Return 0 on success, and a non-zero value if there is an error joining the publication thread. Note that log records received by the publish method will continue to be added to the queue after the publication thread is shut down.

startPublicationThread()

int ball::AsyncFileObserver::startPublicationThread

(

)

Start a publication thread to asynchronously publish log records from the record queue. If a publication thread is already active, this operation has no effect. Return 0 on success, and a non-zero value if there is an error creating the publication thread. Note that log records received by the publish method may have accumulated on the queue before the publication thread is started.

stdoutThreshold()

Severity::Level ball::AsyncFileObserver::stdoutThreshold ( ) const

inline

Return the minimum severity of records that will be logged to stdout by this async file observer. Note that records with a threshold less severe than stdoutThreshold() may still be output to the log file if file logging is enabled.

stopPublicationThread()

int ball::AsyncFileObserver::stopPublicationThread

(

)

Block until all records that were on the record queue upon entry have been published, then stop the publication thread. If there is no publication thread this operation has no effect. Return 0 on success, and a non-zero value if there is an error joining the publication thread. Note that log records received by the publish method will continue to be added to the queue after the publication thread is stopped.

suppressUniqueFileNameOnRotation()

void ball::AsyncFileObserver::suppressUniqueFileNameOnRotation ( bool  suppress )

inline

Suppress generating a unique log file name upon rotation if the specified suppress is true, and generate a unique filename otherwise. See {Rotated File Naming} for details.

---

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

• ball_asyncfileobserver.h