[#BloombergLP-ball-AsyncFileObserver]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/ball.adoc[ball]::AsyncFileObserver
:relfileprefix: ../../
:mrdocs:

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.

== Synopsis

Declared in `<ball_asyncfileobserver.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class AsyncFileObserver
    : public xref:BloombergLP/ball/Observer.adoc[Observer]
----

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/ball/Observer.adoc[Observer]`
| This class provides a protocol for receiving and processing log record output.
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/AsyncFileObserver/OnFileRotationCallback.adoc[`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); `
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/AsyncFileObserver/2constructor-0b.adoc[`AsyncFileObserver`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/ball/AsyncFileObserver/2destructor.adoc[`~AsyncFileObserver`] [.small]#[destructor]# [.small]#[virtual]#
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/disableFileLogging.adoc[`disableFileLogging`] 
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/disablePublishInLocalTime.adoc[`disablePublishInLocalTime`] 
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/disableSizeRotation.adoc[`disableSizeRotation`] 
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/disableStdoutLoggingPrefix.adoc[`disableStdoutLoggingPrefix`] 
| 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 %un") 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.
| xref:BloombergLP/ball/AsyncFileObserver/disableTimeIntervalRotation.adoc[`disableTimeIntervalRotation`] 
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/enableFileLogging.adoc[`enableFileLogging`] 
| 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`.
| xref:BloombergLP/ball/AsyncFileObserver/enablePublishInLocalTime.adoc[`enablePublishInLocalTime`] 
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/enableStdoutLoggingPrefix.adoc[`enableStdoutLoggingPrefix`] 
| 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 %un") 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.
| xref:BloombergLP/ball/AsyncFileObserver/forceRotation.adoc[`forceRotation`] 
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/getFileLogFormat.adoc[`getFileLogFormat`] 
| Return the format specification for log records written to the log file by this async file observer. See {Log Record Formatting} for details on the syntax of format specifications.
| xref:BloombergLP/ball/AsyncFileObserver/getLogFormat.adoc[`getLogFormat`] 
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/getStdoutLogFormat.adoc[`getStdoutLogFormat`] 
| Return the format specification for log records written to `stdout` by this async file observer. See {Log Record Formatting} for details on the syntax of format specifications.
| xref:BloombergLP/ball/AsyncFileObserver/isFileLoggingEnabled-0ac.adoc[`isFileLoggingEnabled`] 
| `isFileLoggingEnabled` overloads
| xref:BloombergLP/ball/AsyncFileObserver/isPublicationThreadRunning.adoc[`isPublicationThreadRunning`] 
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/isPublishInLocalTimeEnabled.adoc[`isPublishInLocalTimeEnabled`] 
| 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}).
| xref:BloombergLP/ball/AsyncFileObserver/isStdoutLoggingPrefixEnabled.adoc[`isStdoutLoggingPrefixEnabled`] 
| 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`.
| xref:BloombergLP/ball/AsyncFileObserver/isSuppressUniqueFileNameOnRotation.adoc[`isSuppressUniqueFileNameOnRotation`] 
| Return `true` if the log filename uniqueness check on rotation is suppressed, and false otherwise.
| xref:BloombergLP/ball/AsyncFileObserver/isUserFieldsLoggingEnabled.adoc[`isUserFieldsLoggingEnabled`]  [.small]#[deprecated]#
| Return `true` if the logging of user‐defined fields is enabled for this async file observer, and `false` otherwise.
| xref:BloombergLP/ball/AsyncFileObserver/localTimeOffset.adoc[`localTimeOffset`] 
| 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).
| xref:BloombergLP/ball/AsyncFileObserver/publish-00.adoc[`publish`] 
| `publish` overloads
| xref:BloombergLP/ball/AsyncFileObserver/recordQueueLength.adoc[`recordQueueLength`] 
| Return the number of log records currently on the record queue of this async file observer.
| xref:BloombergLP/ball/AsyncFileObserver/releaseRecords.adoc[`releaseRecords`]  [.small]#[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.
| xref:BloombergLP/ball/AsyncFileObserver/rotateOnSize.adoc[`rotateOnSize`] 
| 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`.
| xref:BloombergLP/ball/AsyncFileObserver/rotateOnTimeInterval-07.adoc[`rotateOnTimeInterval`] 
| `rotateOnTimeInterval` overloads
| xref:BloombergLP/ball/AsyncFileObserver/rotationLifetime.adoc[`rotationLifetime`] 
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/rotationSize.adoc[`rotationSize`] 
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/setFileLogFormat.adoc[`setFileLogFormat`] 
| Set the format specifications for log records written to the log file `logFileFormat`. See {Log Record Formatting} for details on the syntax of format specifications. Return zero if the format is valid and the corresponding formatter has been set. Otherwise, if the format is invalid, return a non‐zero value and do not change the formatter. Note that default format is in effect following construction until a format‐setting method is called ("n%d %p:%t %s %f:%l %c %m %un" for both file and `stdout` logging).
| xref:BloombergLP/ball/AsyncFileObserver/setLogFormat.adoc[`setLogFormat`] 
| Same as `setLogFormats`.
| xref:BloombergLP/ball/AsyncFileObserver/setLogFormats.adoc[`setLogFormats`] 
| 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`) and setting the format corresponding to enabled `stdout` logging prefix to `stdoutFormat`. See {Log Record Formatting} for details on the syntax of format specifications. Return zero if both formats are valid and have been set. Otherwise, if either format is invalid return a non‐zero value. If one of the formats is invalid it will not be set, but the valid format will. Note that default formats are in effect following construction until a format‐setting method is called ("n%d %p:%t %s %f:%l %c %m %un" for both file and `stdout` logging).
| xref:BloombergLP/ball/AsyncFileObserver/setOnFileRotationCallback.adoc[`setOnFileRotationCallback`] 
| 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).
| xref:BloombergLP/ball/AsyncFileObserver/setStdoutLogFormat.adoc[`setStdoutLogFormat`] 
| Set the format specifications for log records written to `stdout` to the `stdoutFormat`. 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`) and setting the format corresponding to enabled `stdout` logging prefix to `stdoutFormat`. See {Log Record Formatting} for details on the syntax of format specifications. Return zero if the format is valid and the corresponding formatter has been set. Otherwise, if the format is invalid, return a non‐zero value and do not change the formatter. Note that default format is in effect following construction until a format‐setting method is called ("n%d %p:%t %s %f:%l %c %m %un" for both file and `stdout` logging).
| xref:BloombergLP/ball/AsyncFileObserver/setStdoutThreshold.adoc[`setStdoutThreshold`] 
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/shutdownPublicationThread.adoc[`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.
| xref:BloombergLP/ball/AsyncFileObserver/startPublicationThread.adoc[`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.
| xref:BloombergLP/ball/AsyncFileObserver/stdoutThreshold.adoc[`stdoutThreshold`] 
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/stopPublicationThread.adoc[`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.
| xref:BloombergLP/ball/AsyncFileObserver/suppressUniqueFileNameOnRotation.adoc[`suppressUniqueFileNameOnRotation`] 
| 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.
| xref:BloombergLP/ball/AsyncFileObserver/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<AsyncFileObserver, UsesBslmaAllocator>`] 
| Declare that this type uses a `bslma` allocator.
|===


== Using Declarations

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/AsyncFileObserver/publish-0d.adoc[`publish`] 
| Import the base‐class `publish` overloads.
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#