#include <ball_fileobserver2.h>
Detailed Description
This class implements the Observer protocol. The publish method of this class outputs the log records that it receives 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 Component ball_fileobserver2
Member Typedef Documentation
| typedef bsl::function<void(bsl::ostream&, const Record&)> ball::FileObserver2::LogRecordFunctor |
LogRecordFunctor is an alias for the type of the functor used for formatting log records to a stream.
| typedef bsl::function<void(int, const bsl::string&)> ball::FileObserver2::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
| ball::FileObserver2::FileObserver2 | ( | bslma::Allocator * | basicAllocator = 0 |
) | [explicit] |
Create a file observer with file logging initially disabled. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. 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 a default record format is in effect for file logging (see setLogFileFunctor).
| ball::FileObserver2::~FileObserver2 | ( | ) |
Close the log file of this file observer if file logging is enabled, and destroy this file observer.
Member Function Documentation
| ball::FileObserver2::BSLMF_NESTED_TRAIT_DECLARATION | ( | FileObserver2 | , | |
| bslma::UsesBslmaAllocator | ||||
| ) |
| void ball::FileObserver2::disableFileLogging | ( | ) |
Disable file logging for this file observer. This method has no effect if file logging is not enabled. Note that records subsequently received through the publish method will be dropped until file logging is re-enabled.
| void ball::FileObserver2::disableLifetimeRotation | ( | ) |
Disable log file rotation based on a periodic time interval for this file observer. This method has no effect if rotation-on-time-interval is not enabled.
DEPRECATED: Use disableTimeIntervalRotation instead.
| void ball::FileObserver2::disablePublishInLocalTime | ( | ) |
Disable publishing of the timestamp attribute of records in local time by this 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).
| void ball::FileObserver2::disableSizeRotation | ( | ) |
Disable log file rotation based on log file size for this file observer. This method has no effect if rotation-on-size is not enabled.
| void ball::FileObserver2::disableTimeIntervalRotation | ( | ) |
Disable log file rotation based on a periodic time interval for this file observer. This method has no effect if rotation-on-time-interval is not enabled.
| int ball::FileObserver2::enableFileLogging | ( | const char * | logFilenamePattern | ) |
Enable logging of all records published to this 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 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. See Log Filename Patterns.
| int ball::FileObserver2::enableFileLogging | ( | const char * | logFilenamePattern, | |
| bool | appendTimestampFlag | |||
| ) |
Enable logging of all records published to this file observer to a file whose name is derived from the specified logFilenamePattern and append a timestamp to the log filename if the specified appendTimestampFlag is true. Return 0 on success, a positive value if file logging is already enabled (with no effect), and a negative value otherwise. If the appendTimestampFlag is true and logFilenamePattern does not contain any %-escape sequences, this method behaves as if ".%T" is appended to logFilenamePattern.
DEPRECATED: Use enableFileLogging(logFilenamePattern) instead (use the ".%T" pattern to replicate true == appendTimestampFlag behavior).
| void ball::FileObserver2::enablePublishInLocalTime | ( | ) |
Enable publishing of the timestamp attribute of records in local time by this 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).
Process the specified log record having the specified publishing context by writing record and context to the current log file if file logging is enabled for this file observer. The method has no effect if file logging is not enabled, in which case record is dropped.
Reimplemented from ball::Observer.
| void ball::FileObserver2::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 file observer. The method has no effect if file logging is not enabled, in which case record is dropped.
Reimplemented from ball::Observer.
| void ball::FileObserver2::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.
Reimplemented from ball::Observer.
| void ball::FileObserver2::forceRotation | ( | ) |
Forcefully perform a log file rotation by this 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.
| void ball::FileObserver2::rotateOnSize | ( | int | size | ) |
Set this 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.
| void ball::FileObserver2::rotateOnLifetime | ( | const bdlt::DatetimeInterval & | timeInterval | ) |
Set this file observer to perform a periodic log file rotation at multiples of the specified timeInterval. This rule replaces any rotation-on-time-interval rule currently in effect. The behavior is undefined unless 0 < timeInterval.totalMilliseconds().
DEPRECATED: Use rotateOnTimeInterval instead.
| void ball::FileObserver2::rotateOnTimeInterval | ( | const bdlt::DatetimeInterval & | interval | ) |
| void ball::FileObserver2::rotateOnTimeInterval | ( | const bdlt::DatetimeInterval & | interval, | |
| const bdlt::Datetime & | startTime | |||
| ) |
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.
| void ball::FileObserver2::setLogFileFunctor | ( | const LogRecordFunctor & | logFileFunctor | ) |
Set the formatting functor used when writing records to the log file of this file observer to the specified logFileFunctor. Note that a default format ("\n%d %p:%t %s %f:%l %c %m %u\n") is in effect until this method is called (see ball_recordstringformatter). 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.
| void ball::FileObserver2::setOnFileRotationCallback | ( | const OnFileRotationCallback & | onRotationCallback | ) |
Set the specified onRotationCallback to be invoked after each time this 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 file observer (i.e., the supplied callback should not attempt to write to the ball log).
| void ball::FileObserver2::suppressUniqueFileNameOnRotation | ( | bool | suppress | ) |
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.
| bool ball::FileObserver2::isFileLoggingEnabled | ( | ) | const |
| bool ball::FileObserver2::isFileLoggingEnabled | ( | bsl::string * | result | ) | const |
| bool ball::FileObserver2::isFileLoggingEnabled | ( | std::string * | result | ) | const |
Return true if file logging is enabled for this 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 file observer will be dropped when this method returns false.
| bool ball::FileObserver2::isPublishInLocalTimeEnabled | ( | ) | const |
Return true if this 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).
| bool ball::FileObserver2::isSuppressUniqueFileNameOnRotation | ( | ) | const |
Return true if the log filename uniqueness check on rotation is suppressed, and false otherwise.
| bdlt::DatetimeInterval ball::FileObserver2::rotationLifetime | ( | ) | const |
Return the lifetime of the log file that will trigger a file rotation by this file observer if rotation-on-lifetime is in effect, and a 0 time interval otherwise.
| int ball::FileObserver2::rotationSize | ( | ) | const |
Return the size (in kilobytes) of the log file that will trigger a file rotation by this file observer if rotation-on-size is in effect, and 0 otherwise.
| bdlt::DatetimeInterval ball::FileObserver2::localTimeOffset | ( | ) | const |
Return the difference between the local time and UTC time in effect when this 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.
The documentation for this class was generated from the following file:
Generated on Fri Mar 31 2023 13:26:58 for BDE Release 3.115.0.0 Production Release by
1.7.1