#include <ball_log.h>

Static Public Member Functions
static int	format (char buffer, bsl::size_t numBytes, const char format,...) BSLS_ANNOTATION_PRINTF(3
static int static Record *	getRecord (const Category category, const char fileName, int lineNumber)
static void	logMessage (const Category category, int severity, const char fileName, int lineNumber, const char *message)
static void	logMessage (const Category category, int severity, Record record)
static char *	obtainMessageBuffer (bslmt::Mutex *mutex, int bufferSize)
static void	releaseMessageBuffer (bslmt::Mutex *mutex)
static bslma::ManagedPtr< char >	obtainMessageBuffer (int *bufferSize)
static const Category *	setCategory (const char *categoryName)
template<int t_SEVERITY>
static const CategoryHolder *	categoryHolderIfEnabled (const CategoryHolder *categoryHolder)
static void	setCategory (CategoryHolder categoryHolder, const char categoryName)
static const Category *	setCategoryHierarchically (const char *categoryName)
static const Category *	setCategoryHierarchically (CategoryHolder categoryHolder, const char categoryName)
static bool	isCategoryEnabled (const CategoryHolder *categoryHolder, int severity)

Detailed Description

This struct provides a namespace for a suite of utility functions that simplify usage of the ball_loggermanager component. The direct use of these utility functions is strongly discouraged.

See Component ball_log

Member Function Documentation

static int ball::Log::format	(	char *	buffer,
		bsl::size_t	numBytes,
		const char *	format,
			...
	)			`[static]`

static int static Record* ball::Log::getRecord	(	const Category *	category,
		const char *	fileName,
		int	lineNumber
	)			`[static]`

Fill the specified buffer with at most the specified numBytes characters produced by formatting the variable argument list according to the specified printf-style format argument; return the number of characters in the resulting formatted string. The last character placed into buffer is always a null terminator (leaving at most numBytes - 1 bytes of formatted data). If numBytes is insufficient for the entire formatted string, this method fills buffer with the initial numBytes - 1 bytes of formatted data followed by a null terminator and returns -1. Note that with the exception of the return value, the behavior of this function exactly matches that of the C99 function snprintf. Also note that snprintf is not part of standard C++-98, so its functionality is provided here. Return the address of a modifiable record having the specified fileName and lineNumber attributes. The memory for the record will be supplied by the allocator held by the logger manager singleton if the specified category is non-null, or by the currently installed default allocator otherwise. The behavior is undefined unless the logger manager singleton is initialized when category is non-null. Note that the returned Record must subsequently be supplied to a call to the 3-argument logMessage method.

static void ball::Log::logMessage	(	const Category *	category,
		int	severity,
		const char *	fileName,
		int	lineNumber,
		const char *	message
	)			`[static]`

Log a record containing the specified message text, fileName, lineNumber, severity, and the name of the specified category. (See the component-level documentation of ball_record for more information on the additional fields that are logged.) Store the record in the buffer held by the logger if severity is at least as severe as the current "Record" threshold level of category. Pass the record directly to the registered observer if severity is at least as severe as the current "Pass" threshold level of category. Publish the entire contents of the buffer of the logger if severity is at least as severe as the current "Trigger" threshold level of category. Publish the entire contents of all buffers of all loggers if severity is at least as severe as the current "Trigger-All" threshold level of category (i.e., via the callback supplied at construction of the logger manager singleton). This method has no effect if category is 0 or severity is less severe than each of the threshold levels of category. The behavior is undefined unless severity is in the range [1 .. 255] and the logger manager singleton is initialized when category is non-null.

static void ball::Log::logMessage	(	const Category *	category,
		int	severity,
		Record *	record
	)			`[static]`

Log the specified record after setting its category attribute to the specified category and its severity attribute to the specified severity. (See the component-level documentation of ball_record for more information on the fields that are logged.) Store the record in the buffer held by the logger if severity is at least as severe as the current "Record" threshold level of category. Pass the record directly to the registered observer if severity is at least as severe as the current "Pass" threshold level of category. Publish the entire contents of the buffer of the logger if severity is at least as severe as the current "Trigger" threshold level of category. Publish the entire contents of all buffers of all loggers if severity is at least as severe as the current "Trigger-All" threshold level of category (i.e., via the callback supplied at construction of the logger manager singleton). Finally, dispose of record. This method has no effect (other than disposing of record) if severity is less severe than each of the threshold levels of category. The behavior is undefined unless severity is in the range [1 .. 255], record was obtained by a call to Log::getRecord, and, if category is not 0, the logger manager singleton is initialized. Note that record will be invalid after this method returns.

static char* ball::Log::obtainMessageBuffer	(	bslmt::Mutex **	mutex,
		int *	bufferSize
	)			`[static]`

Block until access to the buffer used for formatting messages in this thread of execution is available. Return the address of the modifiable buffer to which this thread of execution has exclusive access, load the address of the mutex that protects the buffer into the specified *mutex address, and load the size (in bytes) of the buffer into the specified bufferSize address. The address remains valid, and the buffer remains locked by this thread of execution, until the Log::releaseMessageBuffer method is called. The behavior is undefined if this thread of execution currently holds a lock on the buffer. Note that the buffer is intended to be used only for formatting log messages immediately before a call to Log::logMessage; other use may adversely affect performance for the entire program.

static void ball::Log::releaseMessageBuffer ( bslmt::Mutex * mutex ) [static]

Unlock the specified mutex that guards the buffer used for formatting messages in this thread of execution. The behavior is undefined unless mutex was obtained by a call to Log::obtainMessageBuffer and has not yet been unlocked.

static bslma::ManagedPtr<char> ball::Log::obtainMessageBuffer ( int * bufferSize ) [static]

Return a managed pointer that refers to the memory block to which this thread of execution has exclusive access and load the size (in bytes) of this buffer into the specified bufferSize address. Note that this method is intended for internal use only.

static const Category* ball::Log::setCategory ( const char * categoryName ) [static]

Return from the logger manager singleton's category registry the address of the non-modifiable category having the specified categoryName if such a category exists, or if a new category having categoryName can be added to the registry (i.e., if the registry has sufficient capacity to accommodate new entries); otherwise, return the address of the non-modifiable Default Category. Return 0 if the logger manager singleton is not initialized.

template<int t_SEVERITY>

static const CategoryHolder* ball::Log::categoryHolderIfEnabled ( const CategoryHolder * categoryHolder ) [static]

Return the specified categoryHolder if the severity warrants logging according to the specified t_SEVERITY and categoryHolder, and 0 otherwise.

static void ball::Log::setCategory	(	CategoryHolder *	categoryHolder,
		const char *	categoryName
	)			`[static]`

Load into the specified categoryHolder the address of the non-modifiable category having the specified categoryName if such a category exists, or if a new category having categoryName can be added to the registry (i.e., if the registry has sufficient capacity to accommodate new entries); otherwise, load the address of the non-modifiable Default Category. Also load into categoryHolder the maximum threshold level of the category ultimately loaded into categoryHolder. This method has no effect if the logger manager singleton is not initialized.

static const Category* ball::Log::setCategoryHierarchically ( const char * categoryName ) [static]

Return from the logger manager singleton's category registry the address of the non-modifiable category having the specified categoryName, or, if no such category exists, add a new category having categoryName to the registry if possible (i.e., if the registry has sufficient capacity to accommodate new entries); otherwise, return the address of the non-modifiable Default Category. If the logger manager singleton is not initialized, return 0 with no effect. If a new category is created, it will have the same threshold levels as the category in the logger manager singleton whose name is the longest non-empty prefix of categoryName if such a category exists, and the threshold levels will be set as if setCategory had been called otherwise.

static const Category* ball::Log::setCategoryHierarchically	(	CategoryHolder *	categoryHolder,
		const char *	categoryName
	)			`[static]`

Return from the logger manager singleton's category registry the address of the non-modifiable category having the specified categoryName, or, if no such category exists, add a new category having categoryName to the registry if possible (i.e., if the registry has sufficient capacity to accommodate new entries); otherwise, return the address of the non-modifiable Default Category. If the logger manager singleton is not initialized, return 0 with no effect. If a new category is created, it will have the same threshold levels as the category in the logger manager singleton whose name is the longest non-empty prefix of categoryName if such a category exists, and the threshold levels will be set as if setCategory had been called otherwise. If the specified categoryHolder is non-zero, load it with the address of the returned category and the maximum threshold level of that category, and link categoryHolder to the other holders (if any) that currently reference the category. Note that this method has the same effect on the logger manager singleton's category registry as the one-argument setCategoryHierarchically regardless of whether 0 == categoryHolder.

static bool ball::Log::isCategoryEnabled	(	const CategoryHolder *	categoryHolder,
		int	severity
	)			`[static]`

Return true if logging to the category associated with the specified categoryHolder at the specified severity is enabled, or if Severity::e_WARN >= severity and the logger manager singleton is not initialized; return false otherwise.

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

ball_log.h

ball::Log Struct Reference

Static Public Member Functions

Detailed Description

Member Function Documentation