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

This class is _usually_ a singleton. It provides a factory for `Logger` objects and is also a wrapper for category administration services. Note that some services provided by this class are available only after the singleton has been initialized.

== Synopsis

Declared in `<ball_loggermanager.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class LoggerManager;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/LoggerManager/AttributeCollector.adoc[`AttributeCollector`] 
| `AttributeCollector` is the type of a user‐supplied functor used to visit a collection of attributes.
| xref:BloombergLP/ball/LoggerManager/AttributeVisitor.adoc[`AttributeVisitor`] 
| `AttributeVisitor` is the type of a user‐supplied functor invoked by an attribute collector for every attribute.
| xref:BloombergLP/ball/LoggerManager/CategoryNameFilterCallback.adoc[`CategoryNameFilterCallback`] 
| `CategoryNameFilterCallback` is the type of the user‐supplied functor that translates external category names to internal names.
| xref:BloombergLP/ball/LoggerManager/DefaultThresholdLevelsCallback.adoc[`DefaultThresholdLevelsCallback`] 
| `DefaultThresholdLevelsCallback` is the type of the functor that determines default threshold levels for categories added to the registry by the `setCategory(const char *)` method.
| xref:BloombergLP/ball/LoggerManager/ObserverRegistry.adoc[`ObserverRegistry`] 
| This `typedef` is an alias for the type of the internal broadcast observer registry.
| xref:BloombergLP/ball/LoggerManager/PublishAllTriggerCallback.adoc[`PublishAllTriggerCallback`] 
| `PublishAllTriggerCallback` is the type of the functor that is invoked to publish all record buffers of all active loggers (i.e., loggers allocated by the logger manager that have not yet been deallocated).
| xref:BloombergLP/ball/LoggerManager/UserFieldsPopulatorCallback-05.adoc[`UserFieldsPopulatorCallback`] 
| `UserFieldsPopulatorCallback` is the type of a user‐supplied callback functor used to populate the user‐defined fields in each log record.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/LoggerManager/2constructor.adoc[`LoggerManager`]         [.small]#[constructor]#
| Create a logger manager having the specified `configuration` of defaults and attributes. Optionally specify a `globalAllocator` used to supply memory. If `globalAllocator` is 0, the currently installed global allocator is used. Note that the new logger manager is _not_ the singleton logger manager used by macros of the BALL logging framework.
| xref:BloombergLP/ball/LoggerManager/2destructor.adoc[`~LoggerManager`] [.small]#[destructor]#
| Destroy this logger manager.
| xref:BloombergLP/ball/LoggerManager/addCategory.adoc[`addCategory`] 
| Add to the category registry of this logger manager a new category having the specified `categoryName` and the specified `recordLevel`, `passLevel`, `triggerLevel`, and `triggerAllLevel` threshold levels, respectively, if (1) `categoryName` is not present in the registry, (2) the number of categories in the registry is less than the registry capacity, and (3) each threshold level is in the range `[0 .. 255]`. Return the address of the new modifiable category on success, and 0 otherwise. The behavior is undefined unless `categoryName` is null‐terminated.
| xref:BloombergLP/ball/LoggerManager/addCategoryHierarchically.adoc[`addCategoryHierarchically`] 
| Add a new category having the specified `categoryName`; return the address of the modifiable new category on success, and 0, with no effect, if a category by that name already exists or if the number of existing categories has reached the maximum capacity. The newly created category will have its threshold levels chosen primarily from two sources: threshold levels of an existing category or a category setting (to which no category exists) choosing the one whose name is the longest non‐empty prefix of `categoryName`. If such a category or setting exists, and the default threshold levels (which might be overridden by a default threshold levels callback) otherwise. See also `ball::CategoryManager::addCategoryHierarchically`.
| xref:BloombergLP/ball/LoggerManager/addRule.adoc[`addRule`] 
| Add a rule having the specified `value` to the set of (unique) rules maintained by this object. Return the number of rules added (i.e., 1 on success and 0 if a rule with the same value is already present).
| xref:BloombergLP/ball/LoggerManager/addRules.adoc[`addRules`] 
| Add each rule in the specified `ruleSet` to the set of (unique) rules maintained by this object. Return the number of rules added. Note that each rule having the same value as an existing rule will be ignored.
| xref:BloombergLP/ball/LoggerManager/allocateLogger-0e.adoc[`allocateLogger`] 
| `allocateLogger` overloads
| xref:BloombergLP/ball/LoggerManager/allocator.adoc[`allocator`] 
| Return the address of the modifiable allocator held by this logger manager.
| xref:BloombergLP/ball/LoggerManager/deallocateLogger.adoc[`deallocateLogger`] 
| Deallocate the specified `logger` and release `logger` from management by this logger manager. The behavior is undefined unless `logger` was obtained by invoking the `allocateLogger` method of this logger manager and `logger` has not yet been deallocated. Note that this method is intended primarily for multi‐threaded applications.
| xref:BloombergLP/ball/LoggerManager/defaultCategory-05.adoc[`defaultCategory`] 
| `defaultCategory` overloads
| xref:BloombergLP/ball/LoggerManager/defaultPassThresholdLevel.adoc[`defaultPassThresholdLevel`] 
| Return the default pass threshold level of this logger manager.
| xref:BloombergLP/ball/LoggerManager/defaultRecordThresholdLevel.adoc[`defaultRecordThresholdLevel`] 
| Return the default record threshold level of this logger manager.
| xref:BloombergLP/ball/LoggerManager/defaultThresholdLevels.adoc[`defaultThresholdLevels`] 
| Return the default threshold levels associated with this logger manager object.
| xref:BloombergLP/ball/LoggerManager/defaultTriggerAllThresholdLevel.adoc[`defaultTriggerAllThresholdLevel`] 
| Return the default trigger‐all threshold level of this logger manager.
| xref:BloombergLP/ball/LoggerManager/defaultTriggerThresholdLevel.adoc[`defaultTriggerThresholdLevel`] 
| Return the default trigger threshold level of this logger manager.
| xref:BloombergLP/ball/LoggerManager/deregisterAllObservers.adoc[`deregisterAllObservers`] 
| Remove all observers from the registry of observers maintained by this logger manager.
| xref:BloombergLP/ball/LoggerManager/deregisterAttributeCollector.adoc[`deregisterAttributeCollector`] 
| Remove the attribute collector having the specified `collectorName` from the registry of collectors maintained by this logger manager. Return 0 if the collector having `collectorName` was successfully deregistered from this logger manager, and a non‐zero value (with no effect) otherwise.
| xref:BloombergLP/ball/LoggerManager/deregisterObserver.adoc[`deregisterObserver`] 
| Remove the observer having the specified `observerName` from the registry of observers maintained by this logger manager. Return 0 if the observer having `observerName` was successfully deregistered from this logger manager, and a non‐zero value (with no effect) otherwise. Henceforth, the observer that had `observerName` will no longer receive log records published by this logger manager.
| xref:BloombergLP/ball/LoggerManager/findObserver-0f.adoc[`findObserver`] 
| `findObserver` overloads
| xref:BloombergLP/ball/LoggerManager/getLogger.adoc[`getLogger`] 
| Return a non‐`const` reference to a logger managed by this logger manager suitable for performing logging operations for this thread of execution.
| xref:BloombergLP/ball/LoggerManager/isCategoryEnabled.adoc[`isCategoryEnabled`] 
| Return `true` if the specified `severity` is more severe (i.e., is numerically less than) at least one of the threshold levels of the specified `category`, and `false` otherwise. If the returned `value` is `false`, then a subsequent call to `getLogger().logMessage()` (with `category` and `severity`) will have no effect. This method compares `severity` with the threshold levels determined by combining `category‐>thresholdLevels()` with the thresholds provided by any relevant and active logging rules (in `ruleSet()`) that apply to `category`. Note that a rule applies to `category` if the rule's pattern matches `category‐>categoryName()`, and a rule is active if all the predicates defined for that rule are satisfied by the current thread's attributes (i.e., `Rule::evaluate()` returns `true` for the collection of attributes maintained by the current thread's `AttributeContext` object).
| xref:BloombergLP/ball/LoggerManager/lookupCategory-0e.adoc[`lookupCategory`] 
| `lookupCategory` overloads
| xref:BloombergLP/ball/LoggerManager/maxNumCategories.adoc[`maxNumCategories`] 
| Return the current capacity of the category registry of this logger manager. A capacity of 0 implies that no limit will be imposed; otherwise, new categories may be added only if `numCategories() < maxNumCategories()`. Note that `0 < maxNumCategories() < numCategories()` _is_ a valid state, implying no new categories may be added.
| xref:BloombergLP/ball/LoggerManager/numCategories.adoc[`numCategories`] 
| Return the number of categories in the category registry of this logger manager.
| xref:BloombergLP/ball/LoggerManager/observer-09.adoc[`observer`] 
| `observer` overloads
| xref:BloombergLP/ball/LoggerManager/publishAll.adoc[`publishAll`] 
| Transmit to the observers registered with this logger manager all log records accumulated in the record buffers of all loggers managed by this logger manager, and indicate the publication cause to be `MANUAL_PUBLISH_ALL`.
| xref:BloombergLP/ball/LoggerManager/registerAttributeCollector.adoc[`registerAttributeCollector`] 
| Add the specified `collector` with the specified `collectorName` to the registry of attribute collectors maintained by this logger manager. Return 0 if `collector` was successfully registered with this logger manager, and a non‐zero value (with no effect) otherwise. Note that this method will fail if a collector having `collectorName` is already registered.
| xref:BloombergLP/ball/LoggerManager/registerObserver.adoc[`registerObserver`] 
| Add the specified `observer` with the specified `observerName` to the registry of observers maintained by this logger manager. Return 0 if `observer` was successfully registered with this logger manager, and a non‐zero value (with no effect) otherwise. Henceforth, all log records published by this logger manager are published to this observer, until `observer` is deregistered. The behavior is undefined if a cyclic reference is created among registered observers. Note that this method will fail if an observer having `observerName` is already registered.
| xref:BloombergLP/ball/LoggerManager/removeAllRules.adoc[`removeAllRules`] 
| Remove every rule from the set of rules maintained by this object.
| xref:BloombergLP/ball/LoggerManager/removeRule.adoc[`removeRule`] 
| Remove the rule having the specified `value` from this set of rules maintained by this object. Return the number of rules removed (i.e., 1 on success and 0 if no rule having the same value is found.)
| xref:BloombergLP/ball/LoggerManager/removeRules.adoc[`removeRules`] 
| Remove each rule in the specified `ruleSet` from this set of rules maintained by this object. Return the number of rules removed.
| xref:BloombergLP/ball/LoggerManager/resetDefaultThresholdLevels.adoc[`resetDefaultThresholdLevels`] 
| Reset the default threshold levels of this logger manager to the original "factory‐supplied" default values or the factory overrides supplied at construction.
| xref:BloombergLP/ball/LoggerManager/ruleSet.adoc[`ruleSet`] 
| Return a `const` reference to the rule set maintained by this object.
| xref:BloombergLP/ball/LoggerManager/setCategory-07f.adoc[`setCategory`] 
| `setCategory` overloads
| xref:BloombergLP/ball/LoggerManager/setCategoryThresholdsToCurrentDefaults.adoc[`setCategoryThresholdsToCurrentDefaults`] 
| Set the threshold levels of the specified `category` in the category registry of this logger manager to the current default threshold values. The behavior is undefined unless `category` is non‐null.
| xref:BloombergLP/ball/LoggerManager/setCategoryThresholdsToFactoryDefaults.adoc[`setCategoryThresholdsToFactoryDefaults`] 
| Set the threshold levels of the specified `category` in the category registry of this logger manager to the original "factory‐supplied" default values or the factory overrides supplied at construction. The behavior is undefined unless `category` is non‐null.
| xref:BloombergLP/ball/LoggerManager/setDefaultThresholdLevels.adoc[`setDefaultThresholdLevels`] 
| Set the default threshold levels of this logger manager to the specified `recordLevel`, `passLevel`, `triggerLevel`, and `triggerAllLevel` values, respectively, if each threshold level is in the range `[0 .. 255]`. Return 0 on success, and a non‐zero value otherwise (with no effect on any default threshold level).
| xref:BloombergLP/ball/LoggerManager/setDefaultThresholdLevelsCallback.adoc[`setDefaultThresholdLevelsCallback`] 
| Set the default‐thresholds callback of this logger manager to the specified `callback`. The default‐thresholds callback is used to determine default threshold levels for categories added to the registry by the `setCategory(const char *)` method.
| xref:BloombergLP/ball/LoggerManager/setLogger.adoc[`setLogger`] 
| Set the default logger used by this thread of execution to the specified `logger`, or to the global default logger if `logger` is 0. The behavior is undefined unless `logger` was obtained from this logger manager, and this thread of execution does not hold exclusive access to the record buffer of its current default logger.
| xref:BloombergLP/ball/LoggerManager/setMaxNumCategories.adoc[`setMaxNumCategories`] 
| Set the capacity of the category registry of this logger manager to the specified `length`. If `length` is 0, no limit will be imposed. No categories are removed from the registry if the current number of categories exceeds `length`. However, subsequent attempts to add categories to the registry will fail. The behavior is undefined unless `0 <= length`.
| xref:BloombergLP/ball/LoggerManager/setThresholdLevelsHierarchically.adoc[`setThresholdLevelsHierarchically`] 
| In case the specified `categoryNamePrefix` is not empty set the threshold levels of every existing and future category whose name has, as a prefix, `categoryNamePrefix` to the specified threshold values, `recordLevel`, `passLevel`, `triggerLevel`, and `triggerAllLevel`. In case `categoryNamePrefix` is empty set the threshold level of every existing category, and remove all preliminary settings (for future categories). Return the number of categories whose threshold levels were set, or a negative value, with no effect, if any of the specified threshold values is outside the range `[0 .. 255]`. See also `ball::CategoryManager::setThresholdLevelsHierarchically`.
| xref:BloombergLP/ball/LoggerManager/thresholdLevelsForNewCategory.adoc[`thresholdLevelsForNewCategory`] 
| Load into the specified `*levels` the threshold levels that would be set for a newly created category, irrespective of whether a category with the specified `categoryName` is already in the registry. Return 0 on success and a non‐zero value otherwise. If the client has configured a default threshold levels callback (see `ball::LoggerManager::DefaultThresholdLevelsCallback` in the component doc), the `categoryName` will be supplied to that callback which will set `*levels`. Otherwise, if no default threshold levels callback has been provided, the default threshold levels are used. Note that this function will report an error if the callback returns invalid levels. Also note that if a category named `categoryName` is already in the registry, the levels returned by this method may differ from the levels of that category.
| xref:BloombergLP/ball/LoggerManager/userFieldsPopulatorCallback-0c.adoc[`userFieldsPopulatorCallback`] 
| Return the address of the non‐modifiable user populator functor registered with this logger manager, or 0 if there is no registered user populator functor.
| xref:BloombergLP/ball/LoggerManager/visitCategories-0d.adoc[`visitCategories`] 
| `visitCategories` overloads
| xref:BloombergLP/ball/LoggerManager/visitObservers-06.adoc[`visitObservers`] 
| `visitObservers` overloads
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/LoggerManager/createLoggerManager-05.adoc[`createLoggerManager`] 
| `createLoggerManager` overloads
| xref:BloombergLP/ball/LoggerManager/getRecord.adoc[`getRecord`] 
| Return the address of a modifiable record with the specified `fileName` and `lineNumber` attributes, and whose memory is supplied by the currently installed default allocator. Note that the returned `Record` must subsequently be supplied to a call to the `LoggerManager::logMessage` method.
| xref:BloombergLP/ball/LoggerManager/initSingleton-01.adoc[`initSingleton`] 
| `initSingleton` overloads
| xref:BloombergLP/ball/LoggerManager/isInitialized.adoc[`isInitialized`] 
| Return `true` if the logger manager singleton exists, and `false` otherwise.
| xref:BloombergLP/ball/LoggerManager/logMessage.adoc[`logMessage`] 
| Publish the specified `record` using `bsls::Log::platformDefaultMessageHandler` after setting its severity attribute to the specified `severity`, and dispose of `record`. The behavior is undefined unless `record` was obtained by a call to the `LoggerManager::getRecord` method. Note that `record` will be invalid after this method returns.
| xref:BloombergLP/ball/LoggerManager/obtainMessageBuffer-01.adoc[`obtainMessageBuffer`] 
| `obtainMessageBuffer` overloads
| xref:BloombergLP/ball/LoggerManager/shutDownSingleton.adoc[`shutDownSingleton`] 
| Destroy the logger manager singleton and release all resources used by it. This method has no effect if the logger manager singleton does not exist (i.e., it has not been initialized or has already been destroyed). The behavior is undefined if this method is called from one thread while another thread is accessing the logger manager singleton (i.e., this method is _not_ thread‐safe).
| xref:BloombergLP/ball/LoggerManager/singleton.adoc[`singleton`] 
| Return a non‐`const` reference to the logger manager singleton. The behavior is undefined unless the logger manager singleton exists.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/ball/LoggerManagerCategoryManip.adoc[BloombergLP::ball::LoggerManagerCategoryManip]`
| This class defines an iterator providing sequential, modifiable access to the categories in the registry of a logger manager's category manager. The order of the iteration is undefined.
| `xref:BloombergLP/ball/LoggerManagerCategoryIter.adoc[BloombergLP::ball::LoggerManagerCategoryIter]`
| This class defines an iterator providing sequential, read‐only access to the categories in the registry of a logger manager's category manager. The order of the iteration is undefined.
|===


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