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

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

== Synopsis

Declared in `&lt;ball&lowbar;asyncfileobserver&period;h&gt;`

[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&period;
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/AsyncFileObserver/OnFileRotationCallback.adoc[`OnFileRotationCallback`] 
| `OnFileRotationCallback` is an alias for a user&hyphen;supplied callback function that is invoked after the file observer attempts to rotate its log file&period; The callback takes two arguments&colon; (1) an integer status value where 0 indicates a new log file was successfully created and a non&hyphen;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&period; E&period;g&period;&colon; &grave; void onLogFileRotation(int rotationStatus, const bsl&colon;&colon;string&amp; rotatedLogFileName)&semi; &grave;
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/AsyncFileObserver/2constructor-0b.adoc[`AsyncFileObserver`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/ball/AsyncFileObserver/2destructor.adoc[`&#126;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&period;
| xref:BloombergLP/ball/AsyncFileObserver/disableFileLogging.adoc[`disableFileLogging`] 
| Disable file logging for this async file observer&period; This method has no effect if file logging is not enabled&period; Calling this method will prevent the logging to a file of any unpublished records held by this observer&period; 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&period;
| xref:BloombergLP/ball/AsyncFileObserver/disablePublishInLocalTime.adoc[`disablePublishInLocalTime`] 
| Disable publishing of the timestamp attribute of records in local time by this async file observer&semi; henceforth, timestamps will be in UTC time&period; This method has no effect if publishing in local time is not enabled&period; Note that this method also affects log filenames (see &lcub;Log Filename Patterns&rcub;)&period; Also note that this method affects records subsequently received through the `publish` method as well as those that are currently on the queue&period;
| xref:BloombergLP/ball/AsyncFileObserver/disableSizeRotation.adoc[`disableSizeRotation`] 
| Disable log file rotation based on log file size for this async file observer&period; This method has no effect if rotation&hyphen;on&hyphen;size is not enabled&period;
| xref:BloombergLP/ball/AsyncFileObserver/disableStdoutLoggingPrefix.adoc[`disableStdoutLoggingPrefix`] 
| Disable this async file observer from using the long output format when logging to `stdout`&period; Henceforth, this async file observer will use the default short output format (&quot;n%s %f&colon;%l %c %m %un&quot;) when logging to `stdout`&period; This method has no effect if the long output format for `stdout` logging is not enabled&period; Note that this method omits the &quot;%d %p&colon;%t &quot; prefix from the default long output format&period; Also note that this method affects records subsequently received through the `publish` method as well as those that are currently on the queue&period;
| xref:BloombergLP/ball/AsyncFileObserver/disableTimeIntervalRotation.adoc[`disableTimeIntervalRotation`] 
| Disable log file rotation based on a periodic time interval for this async file observer&period; This method has no effect if rotation&hyphen;on&hyphen;time&hyphen;interval is not enabled&period;
| 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`&period; Return 0 on success, a positive value if file logging is already enabled (with no effect), and a negative value otherwise&period; The basename of `logFilenamePattern` may contain `%`&hyphen;escape sequences that are interpreted as follows&colon; &grave; %Y &hyphen; current year (4 digits with leading zeros) %M &hyphen; current month (2 digits with leading zeros) %D &hyphen; current day (2 digits with leading zeros) %h &hyphen; current hour (2 digits with leading zeros) %m &hyphen; current minute (2 digits with leading zeros) %s &hyphen; current second (2 digits with leading zeros) %T &hyphen; current datetime, equivalent to &quot;%Y%M%D&lowbar;%h%m%s&quot; %p &hyphen; process ID &grave; 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 `%`&hyphen;escape sequences&period; If `isPublishInLocalTimeEnabled` returns `true`, the `%`&hyphen;escape sequences related to time will be substituted with local time values, and UTC time values otherwise&period; 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`&period;
| xref:BloombergLP/ball/AsyncFileObserver/enablePublishInLocalTime.adoc[`enablePublishInLocalTime`] 
| Enable publishing of the timestamp attribute of records in local time by this async file observer&period; This method has no effect if publishing in local time is already enabled&period; Note that this method also affects log filenames (see &lcub;Log Filename Patterns&rcub;)&period; Also note that this method affects records subsequently received through the `publish` method as well as those that are currently on the queue&period;
| xref:BloombergLP/ball/AsyncFileObserver/enableStdoutLoggingPrefix.adoc[`enableStdoutLoggingPrefix`] 
| Enable this async file observer to use the long output format when logging to `stdout`&period; 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 (&quot;n%d %p&colon;%t %s %f&colon;%l %c %m %un&quot;) if `setLogFormat` has not yet been called&period; This method has no effect if the long output format for `stdout` logging is already enabled&period; Note that this method affects records subsequently received through the `publish` method as well as those that are currently on the queue&period;
| xref:BloombergLP/ball/AsyncFileObserver/forceRotation.adoc[`forceRotation`] 
| Forcefully perform a log file rotation by this async file observer&period; Close the current log file, rename the log file if necessary, and open a new log file&period; This method has no effect if file logging is not enabled&period; See &lcub;Rotated File Naming&rcub; for details on filenames of rotated log files&period;
| xref:BloombergLP/ball/AsyncFileObserver/getFileLogFormat.adoc[`getFileLogFormat`] 
| Return the format specification for log records written to the log file by this async file observer&period; See &lcub;Log Record Formatting&rcub; for details on the syntax of format specifications&period;
| 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 `&ast;logFileFormat` address and the format specification for log records written to `stdout` into the specified `&ast;stdoutFormat` address&period; See &lcub;Log Record Formatting&rcub; for details on the syntax of format specifications&period;
| xref:BloombergLP/ball/AsyncFileObserver/getStdoutLogFormat.adoc[`getStdoutLogFormat`] 
| Return the format specification for log records written to `stdout` by this async file observer&period; See &lcub;Log Record Formatting&rcub; for details on the syntax of format specifications&period;
| 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&period; Note that records received by the `publish` method will still be added to the record queue even if there is no publication thread running&period;
| 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)&period; Note that the value returned by this method also affects log filenames (see &lcub;Log Filename Patterns&rcub;)&period;
| 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)&period; See `enableStdoutLoggingPrefix` and `disableStdoutLoggingPrefix`&period;
| xref:BloombergLP/ball/AsyncFileObserver/isSuppressUniqueFileNameOnRotation.adoc[`isSuppressUniqueFileNameOnRotation`] 
| Return `true` if the log filename uniqueness check on rotation is suppressed, and false otherwise&period;
| xref:BloombergLP/ball/AsyncFileObserver/isUserFieldsLoggingEnabled.adoc[`isUserFieldsLoggingEnabled`]  [.small]#[deprecated]#
| Return `true` if the logging of user&hyphen;defined fields is enabled for this async file observer, and `false` otherwise&period;
| 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&period; 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&period;g&period;, when transitioning into or out of daylight savings time)&period;
| 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&period;
| 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&period; Note that this operation should be called if resources underlying the previously provided shared pointers must be released&period; Also note that all currently queued records are discarded&period;
| 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)&period; This rule replaces any rotation&hyphen;on&hyphen;size rule currently in effect&period; The behavior is undefined unless `size &gt; 0`&period;
| 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&hyphen;on&hyphen;lifetime is in effect, and a 0 time interval otherwise&period;
| 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&hyphen;on&hyphen;size is in effect, and 0 otherwise&period;
| xref:BloombergLP/ball/AsyncFileObserver/setFileLogFormat.adoc[`setFileLogFormat`] 
| Set the format specifications for log records written to the log file `logFileFormat`&period; See &lcub;Log Record Formatting&rcub; for details on the syntax of format specifications&period; Return zero if the format is valid and the corresponding formatter has been set&period; Otherwise, if the format is invalid, return a non&hyphen;zero value and do not change the formatter&period; Note that default format is in effect following construction until a format&hyphen;setting method is called (&quot;n%d %p&colon;%t %s %f&colon;%l %c %m %un&quot; for both file and `stdout` logging)&period;
| xref:BloombergLP/ball/AsyncFileObserver/setLogFormat.adoc[`setLogFormat`] 
| Same as `setLogFormats`&period;
| 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&period; 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`&period; See &lcub;Log Record Formatting&rcub; for details on the syntax of format specifications&period; Return zero if both formats are valid and have been set&period; Otherwise, if either format is invalid return a non&hyphen;zero value&period; If one of the formats is invalid it will not be set, but the valid format will&period; Note that default formats are in effect following construction until a format&hyphen;setting method is called (&quot;n%d %p&colon;%t %s %f&colon;%l %c %m %un&quot; for both file and `stdout` logging)&period;
| 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&period; The behavior is undefined if the supplied function calls either `setOnFileRotationCallback`, `forceRotation`, or `publish` on this async file observer (i&period;e&period;, the supplied callback should _not_ attempt to write to the `ball` log)&period;
| xref:BloombergLP/ball/AsyncFileObserver/setStdoutLogFormat.adoc[`setStdoutLogFormat`] 
| Set the format specifications for log records written to `stdout` to the `stdoutFormat`&period; 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`&period; See &lcub;Log Record Formatting&rcub; for details on the syntax of format specifications&period; Return zero if the format is valid and the corresponding formatter has been set&period; Otherwise, if the format is invalid, return a non&hyphen;zero value and do not change the formatter&period; Note that default format is in effect following construction until a format&hyphen;setting method is called (&quot;n%d %p&colon;%t %s %f&colon;%l %c %m %un&quot; for both file and `stdout` logging)&period;
| 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&period; Note that if the value of `stdoutThreshold` is `Severity&colon;&colon;e&lowbar;OFF`, logging to `stdout` is disabled&period; Also note that this method affects records subsequently received through the `publish` method as well as those that are currently on the queue&period;
| xref:BloombergLP/ball/AsyncFileObserver/shutdownPublicationThread.adoc[`shutdownPublicationThread`] 
| Stop the publication thread without waiting for log records currently on the record queue to be published&period; Return 0 on success, and a non&hyphen;zero value if there is an error joining the publication thread&period; Note that log records received by the `publish` method will continue to be added to the queue after the publication thread is shut down&period;
| xref:BloombergLP/ball/AsyncFileObserver/startPublicationThread.adoc[`startPublicationThread`] 
| Start a publication thread to asynchronously publish log records from the record queue&period; If a publication thread is already active, this operation has no effect&period; Return 0 on success, and a non&hyphen;zero value if there is an error creating the publication thread&period; Note that log records received by the `publish` method may have accumulated on the queue before the publication thread is started&period;
| xref:BloombergLP/ball/AsyncFileObserver/stdoutThreshold.adoc[`stdoutThreshold`] 
| Return the minimum severity of records that will be logged to `stdout` by this async file observer&period; Note that records with a threshold less severe than `stdoutThreshold()` may still be output to the log file if file logging is enabled&period;
| 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&period; If there is no publication thread this operation has no effect&period; Return 0 on success, and a non&hyphen;zero value if there is an error joining the publication thread&period; Note that log records received by the `publish` method will continue to be added to the queue after the publication thread is stopped&period;
| 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&period; See &lcub;Rotated File Naming&rcub; for details&period;
| xref:BloombergLP/ball/AsyncFileObserver/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration&lt;AsyncFileObserver, UsesBslmaAllocator&gt;`] 
| Declare that this type uses a `bslma` allocator&period;
|===


== Using Declarations

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



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