Singleton for managing the logging streams associated with execution threads.
#include <Workspace/Application/logmanager.h>
◆ addMessageCategory()
- Parameters
-
| category | The new message category to add to the LogManager |
- Returns
- true if the category was added successfully, false if a category with the same name already exists. An error message will also be logged.
The log manager allows us to classify messages into categories. When using the logText function, we can specify a category name. If this category is exists and is enabled, the message will be logged. In addition, a prefix and suffix will be added to the message if one is specified.
- Note
- The log manager adds a set of default categories which can be used.
◆ addStream()
- Parameters
-
| logStream | The LogStream object to use as the main stream for the application. It is the caller's responsibility to ensure that logStream survives for the life of the application or until the stream is popped off the main log stream stack through a call to popMainLogStream(). |
- Warning
- This function should only be called at a time when it can be guaranteed that nothing will try to write to the main log stream. There are no protections against race conditions when pushing or popping the log stream stack.
- See also
- removeStream()
◆ canCaptureStandardOutput()
| bool canCaptureStandardOutput |
( |
| ) |
const |
- Returns
- True if LogStream subclasses are allowed to capture standard output. In practice, this amounts to testing whether or not the user has defined the WORKSPACE_PREVENT_LOG_CAPTURE environment variable.
- See also
- isCapturingStandardOutput()
◆ enableStandardOutputStream()
| void enableStandardOutputStream |
( |
bool |
enabled | ) |
|
- Parameters
-
| enabled | Enable a standard output regard less of output stream |
By default, log messages always forward to standard output (or error if capturing standard output) When an application would like to disable standard output and attach its own logStream, call this to disable standard output (or error).
Note, if no logStream attached to LogManager, all log text are discarded.
- See also
- addStream()
◆ filterMessages() [1/2]
- Parameters
-
| category | The category of log message to suppress. |
- Returns
- A pointer to a FilterToken object. Once this filter goes out of scope, it will no longer apply.
Enables message filtering while the FilterToken object that it returns remains alive. Log messages that match the specified category will be suppressed (ignored) - they will not appear in any log sinks.
- Note
- any threads of execution that are spawned from the same thread that the filter exists in will have the same filter applied to them; the assumption here being that any filtering applies to anything going on in the code within this scope.
See test_logstreamfilter for examples of how the filtering works with respect to threads of execution.
◆ filterMessages() [2/2]
- Parameters
-
| categories | The categories of log message to suppress. |
- Returns
- A pointer to a FilterToken object. Once this filter goes out of scope, it will no longer apply.
Enables message filtering while the FilterToken object that it returns remains alive. Log messages that match the specified categories will be suppressed (ignored) - they will not appear in any log sinks.
- Note
- any threads of execution that are spawned from the same thread that the filter exists in will have the same filter applied to them; the assumption here being that any filtering applies to anything going on in the code within this scope.
See test_logstreamfilter for examples of how the filtering works with respect to threads of execution.
◆ flush()
Causes the current log stream to be flushed.
◆ flushAsync()
Causes the current log stream to be flushed.
◆ getInstance()
- Returns
- The LogManager singleton instance used by the application.
◆ getMessageCategories()
- Returns
- A list of all the categories registered with the log manager.
◆ getMessageCategory()
- Parameters
-
| category | The name of the category to retrieve. |
- Returns
- A pointer to the category with the specified name, 0 if a category with this name does not exist.
◆ getStreams()
- Returns
- Read only list of current log streams
◆ hasMessageCategory()
| bool hasMessageCategory |
( |
const QString & |
category | ) |
const |
- Parameters
-
| category | The category we are testing. |
- Returns
- true if the category exists, false otherwise
Checks whether the log manager has knowledge of a specific category.
- See also
- logText()
◆ installFilter()
- Parameters
-
| filter | The LogStreamFilter object that should be installed in the LogManager. |
Installs a LogStreamFilter in the LogManager. Once a LogStreamFilter is installed, any messages that match the categories of the filter will be suppressed from the log. If, while the filter still lives, additional threads of execution are spawned from scope in which the filter was created, those 'child' threads will also be affected by this filter.
Only FilterToken objects are capable of installing a LogStreamFilter to a LogManager.
◆ isCapturingStandardOutput()
| bool isCapturingStandardOutput |
( |
| ) |
const |
- Returns
- True if all output is being captured. Note that once this has been turned on, it cannot be turned off for the rest of the application because the original output streams cannot be restored.
- See also
- canCaptureStdOutput()
◆ isMessageCategoryEnabled()
| bool isMessageCategoryEnabled |
( |
const QString & |
category | ) |
const |
◆ logLine() [1/3]
- Parameters
-
| category | The category associated with this message. If the category name is not registered with the LogManager (see setMessageCategoryEnabled) or the category is disabled, the message will not be logged. |
| msg | The content of the message to log. |
The same as logText but a newline character is appended to the message.
◆ logLine() [2/3]
| void logLine |
( |
const QString & |
categoryName, |
|
|
const QString & |
msg |
|
) |
| |
|
static |
- Parameters
-
| categoryName | The category name associated with this message. If the category name is not registered with the LogManager (see setMessageCategoryEnabled) or the category is disabled, the message will not be logged. |
| msg | The content of the message to log. |
The same as logText but a newline character is appended to the message.
◆ logLine() [3/3]
| void logLine |
( |
const QString & |
msg | ) |
|
|
static |
- Parameters
-
| msg | The text message to send to the appropriate log stream. |
The same as logText but a newline character is appended to the message.
◆ logLineAsync() [1/3]
| void logLineAsync |
( |
const MessageCategory & |
category, |
|
|
const QString & |
msg |
|
) |
| |
|
static |
- Parameters
-
| category | The category associated with this message. If the category name is not registered with the LogManager (see setMessageCategoryEnabled) or the category is disabled, the message will not be logged. |
| msg | The content of the message to log. |
The same as logText but a newline character is appended to the message.
◆ logLineAsync() [2/3]
| void logLineAsync |
( |
const QString & |
categoryName, |
|
|
const QString & |
msg |
|
) |
| |
|
static |
- Parameters
-
| categoryName | The category name associated with this message. If the category name is not registered with the LogManager (see setMessageCategoryEnabled) or the category is disabled, the message will not be logged. |
| msg | The content of the message to log. |
The same as logText but a newline character is appended to the message.
◆ logLineAsync() [3/3]
| void logLineAsync |
( |
const QString & |
msg | ) |
|
|
static |
- Parameters
-
| msg | The text message to send to the appropriate log stream. |
The same as logText but a newline character is appended to the message.
◆ logText() [1/3]
- Parameters
-
| category | The category associated with this message. If the category name is not registered with the LogManager (see setMessageCategoryEnabled) or the category is disabled, the message will not be logged. |
| msg | The content of the message to log. |
◆ logText() [2/3]
| void logText |
( |
const QString & |
categoryName, |
|
|
const QString & |
msg |
|
) |
| |
|
static |
- Parameters
-
| categoryName | The category name associated with this message. If the category name is not registered with the LogManager (see setMessageCategoryEnabled) or the category is disabled, the message will not be logged. |
| msg | The content of the message to log. |
◆ logText() [3/3]
| void logText |
( |
const QString & |
msg | ) |
|
|
static |
- Parameters
-
| msg | The text message to send to the appropriate log stream. |
This function is a convenience. Client code can call it with text to be logged and it will be sent to the appropriate log stream for the calling thread. It has one main advantage over simply using std::cout and that is that it will send msg to the appropriate place potentially more quickly because it bypasses the capturing of stdout (which happens in a separate thread). It is recommended that you only call logText() when you really want the text logged as early as possible. Its use can potentially result in out-of-order text appearing in the log if an earlier output to std::cout is yet to be delivered.
◆ logTextAsync() [1/3]
| void logTextAsync |
( |
const MessageCategory & |
category, |
|
|
const QString & |
msg |
|
) |
| |
|
static |
- Parameters
-
| category | The category associated with this message. If the category name is not registered with the LogManager (see setMessageCategoryEnabled) or the category is disabled, the message will not be logged. |
| msg | The content of the message to log. |
◆ logTextAsync() [2/3]
| void logTextAsync |
( |
const QString & |
categoryName, |
|
|
const QString & |
msg |
|
) |
| |
|
static |
- Parameters
-
| categoryName | The category name associated with this message. If the category name is not registered with the LogManager (see setMessageCategoryEnabled) or the category is disabled, the message will not be logged. |
| msg | The content of the message to log. |
Writes to the log and doesn't block the calling thread while waiting for it to happen.
◆ logTextAsync() [3/3]
| void logTextAsync |
( |
const QString & |
msg | ) |
|
|
static |
{ Set of async versions of the log text for when we don't care about the results being in order and so don't care to block the calling thread.
- Parameters
-
| msg | The text message to send to the appropriate log stream. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. |
Writes to the log and doesn't block the calling thread while waiting for it to happen.
◆ removeFilter()
- Parameters
-
| filter | The LogStreamFilter object to be removed from the LogManager. |
Removes a LogStreamFilter from the LogManager. Once the filter is removed, it will no longer suppress any log messages on that thread of execution (or any 'child' threads that were spawned after the filter was originally created).
Only FilterToken objects are capable of removing a LogStreamFilter from a LogManager.
◆ removeStream()
- Parameters
-
| logStream | The log stream to pop off the stack. Normally, it will be a null pointer, which means pop the last item off the stack, but in some cases a specific item needs to be removed from the stack which might not be at the top. It is okay to remove an item that is not on the top, but be aware that the main log is then increasingly likely to be getting redirected to unexpected places. |
- Warning
- This function should only be called at a time when it can be guaranteed that nothing will try to write to the main log stream. There are no protections against race conditions when pushing or popping the log stream stack.
- Returns
- True if the logStream exisited in the list and has been removed.
- See also
- addStream()
◆ setDefaultMessageCategory()
| void setDefaultMessageCategory |
( |
const QString & |
category | ) |
|
- Parameters
-
| category | The message category to set as a default. By default, this is not used, so all messages will be logged with no category. |
◆ setGlobalMessagePrefix()
| void setGlobalMessagePrefix |
( |
const QString & |
prefix | ) |
|
◆ setMessageCategoryEnabled()
| void setMessageCategoryEnabled |
( |
const QString & |
category, |
|
|
bool |
enabled |
|
) |
| |
- Parameters
-
| category | The category to enable / disable |
| enabled | The desired enabled state of the category |
Enables / disables a specific category name in the LogManager. The LogManager uses categories with the LogText call to "tag" specific text with a certain category. By disabling category, log messages associated with that category will not be displayed.
- See also
- logText() isMessageCategoryEnabled()
