diff options
Diffstat (limited to 'src/corelib/io/qloggingcategory.cpp')
| -rw-r--r-- | src/corelib/io/qloggingcategory.cpp | 267 |
1 files changed, 127 insertions, 140 deletions
diff --git a/src/corelib/io/qloggingcategory.cpp b/src/corelib/io/qloggingcategory.cpp index f6ff56c83c..4d4784cdf7 100644 --- a/src/corelib/io/qloggingcategory.cpp +++ b/src/corelib/io/qloggingcategory.cpp @@ -70,14 +70,16 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift) QLoggingCategory represents a certain logging category - identified by a string - at runtime. A category can be configured to enable or disable - logging of messages per message type. Whether a message type is enabled or - not can be checked with the \l isDebugEnabled(), \l isInfoEnabled(), - \l isWarningEnabled(), and \l isCriticalEnabled() methods. - - All objects are meant to be configured by a common registry (see also - \l{Configuring Categories}). Different objects can also represent the same - category. It is therefore not recommended to export objects across module - boundaries, nor to manipulate the objects directly, nor to inherit from + logging of messages per message type. + + To check whether a message type is enabled or not, use one of these methods: + \l isDebugEnabled(), \l isInfoEnabled(), \l isWarningEnabled(), and + \l isCriticalEnabled(). + + All objects are meant to be configured by a common registry, as described in + \l{Configuring Categories}. Different objects can also represent the same + category. Therefore, it's \b{not} recommended to export objects across + module boundaries, to manipulate the objects directly, or to inherit from QLoggingCategory. \section1 Creating Category Objects @@ -87,17 +89,17 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift) \snippet qloggingcategory/main.cpp 1 - \note Category names are free text. However, to allow easy configuration - of the categories using \l{Logging Rules} the names should follow some rules: + Category names are free text; to configure categories using \l{Logging Rules}, their + names should follow this convention: \list \li Use letters and numbers only. - \li Further structure categories into common areas by using dots. - \li Avoid the category names \c{debug}, \c{info}, \c{warning}, and \c{critical}. - \li Category names starting with \c{qt} are reserved for Qt modules. + \li Use dots to further structure categories into common areas. + \li Avoid the category names: \c{debug}, \c{info}, \c{warning}, and \c{critical}. + \li Category names with the \c{qt} prefix are solely reserved for Qt modules. \endlist - QLoggingCategory objects implicitly defined by Q_LOGGING_CATEGORY() - are created on first use in a thread-safe manner. + QLoggingCategory objects that are implicitly defined by Q_LOGGING_CATEGORY() + are created on first use, in a thread-safe manner. \section1 Checking Category Configuration @@ -105,8 +107,8 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift) \l isWarningEnabled(), \l isCriticalEnabled(), as well as \l isEnabled() to check whether messages for the given message type should be logged. - \note The qCDebug(), qCWarning(), qCCritical() macros prevent arguments - from being evaluated if the respective message types are not enabled for the + The qCDebug(), qCWarning(), and qCCritical() macros prevent arguments from + being evaluated if the respective message types are not enabled for the category, so explicit checking is not needed: \snippet qloggingcategory/main.cpp 4 @@ -119,28 +121,27 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift) \snippet qloggingcategory/main.cpp 5 - will log messages of type \c QtWarningMsg, \c QtCriticalMsg, \c QtFatalMsg, but will - ignore messages of type \c QtDebugMsg and \c QtInfoMsg. + logs messages of type \c QtWarningMsg, \c QtCriticalMsg, \c QtFatalMsg, but + ignores messages of type \c QtDebugMsg and \c QtInfoMsg. - If no argument is passed, all messages will be logged. + If no argument is passed, all messages are logged. \section1 Configuring Categories - The default configuration of categories can be overridden either by setting logging - rules, or by installing a custom filter. + You can override the default configuration for categories either by setting + logging rules, or by installing a custom filter. \section2 Logging Rules - Logging rules allow logging for categories to be enabled or disabled in a - flexible way. Rules are specified in text, where every line must have the - format + Logging rules let you enable or disable logging for categories in a flexible + way. Rules are specified in text, where every line must have the format: \snippet code/src_corelib_io_qloggingcategory.cpp 0 \c <category> is the name of the category, potentially with \c{*} as a - wildcard symbol as the first or last character (or at both positions). - The optional \c <type> must be either \c debug, \c info, \c warning, or \c critical. - Lines that do not fit this scheme are ignored. + wildcard symbol for the first or last character; or at both positions. + The optional \c <type> must be \c debug, \c info, \c warning, or \c critical. + Lines that don't fit this scheme are ignored. Rules are evaluated in text order, from first to last. That is, if two rules apply to a category/type, the rule that comes later is applied. @@ -149,47 +150,37 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift) \snippet code/src_corelib_io_qloggingcategory.cpp 1 - Since Qt 5.3, logging rules are also - automatically loaded from the \c [Rules] section of a logging - configuration file. Such configuration files are looked up in the QtProject - configuration directory, or explicitly set in a \c QT_LOGGING_CONF - environment variable: + Logging rules are automatically loaded from the \c [Rules] section in a logging + configuration file. These configuration files are looked up in the QtProject + configuration directory, or explicitly set in a \c QT_LOGGING_CONF environment + variable: \snippet code/src_corelib_io_qloggingcategory.cpp 2 - Since Qt 5.3, logging rules can also be specified in a \c QT_LOGGING_RULES - environment variable. And since Qt 5.6, multiple rules can also be - separated by semicolons: + Logging rules can also be specified in a \c QT_LOGGING_RULES environment variable; + multiple rules can also be separated by semicolons: \snippet code/src_corelib_io_qloggingcategory.cpp 3 - Rules set by \l setFilterRules() take precedence over rules specified - in the QtProject configuration directory, and can, in turn, be - overwritten by rules from the configuration file specified by - \c QT_LOGGING_CONF, and rules set by \c QT_LOGGING_RULES. - - Order of evaluation: - \list - \li [QLibraryInfo::DataPath]/qtlogging.ini - \li QtProject/qtlogging.ini - \li \l setFilterRules() - \li \c QT_LOGGING_CONF - \li \c QT_LOGGING_RULES + Rules set by \l setFilterRules() take precedence over rules specified in the + QtProject configuration directory. In turn, these rules can be overwritten by those + from the configuration file specified by \c QT_LOGGING_CONF, and those set by + \c QT_LOGGING_RULES. + + The order of evaluation is as follows: + \list 1 + \li [QLibraryInfo::DataPath]/qtlogging.ini + \li QtProject/qtlogging.ini + \li \l setFilterRules() + \li \c QT_LOGGING_CONF + \li \c QT_LOGGING_RULES \endlist The \c QtProject/qtlogging.ini file is looked up in all directories returned - by QStandardPaths::GenericConfigLocation, e.g. + by QStandardPaths::GenericConfigLocation. - \list - \li on \macos and iOS: \c ~/Library/Preferences - \li on Unix: \c ~/.config, \c /etc/xdg - \li on Windows: \c %LOCALAPPDATA%, \c %ProgramData%, - \l QCoreApplication::applicationDirPath(), - QCoreApplication::applicationDirPath() + \c "/data" - \endlist - - Set the \c QT_LOGGING_DEBUG environment variable to see from where - logging rules are loaded. + Set the \c QT_LOGGING_DEBUG environment variable to find out where you logging + rules are loaded from. \section2 Installing a Custom Filter @@ -211,7 +202,7 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift) If \a category is \c{0}, the category name is changed to \c "default". - Note that \a category must be kept valid during the lifetime of this object. + \note \a category must be kept valid during the lifetime of this object. */ QLoggingCategory::QLoggingCategory(const char *category) : d(nullptr), @@ -226,7 +217,7 @@ QLoggingCategory::QLoggingCategory(const char *category) If \a category is \c{0}, the category name is changed to \c "default". - Note that \a category must be kept valid during the lifetime of this object. + \note \a category must be kept valid during the lifetime of this object. \since 5.4 */ @@ -251,7 +242,7 @@ void QLoggingCategory::init(const char *category, QtMsgType severityLevel) } /*! - Destructs a QLoggingCategory object. + Destroys a QLoggingCategory object. */ QLoggingCategory::~QLoggingCategory() { @@ -268,24 +259,24 @@ QLoggingCategory::~QLoggingCategory() /*! \fn bool QLoggingCategory::isDebugEnabled() const - Returns \c true if debug messages should be shown for this category. - Returns \c false otherwise. + Returns \c true if debug messages should be shown for this category; + \c false otherwise. - \note The \l qCDebug() macro already does this check before executing any - code. However, calling this method may be useful to avoid - expensive generation of data that is only used for debug output. + \note The \l qCDebug() macro already does this check before running any + code. However, calling this method may be useful to avoid the + expensive generation of data for debug output only. */ /*! \fn bool QLoggingCategory::isInfoEnabled() const - Returns \c true if informational messages should be shown for this category. - Returns \c false otherwise. + Returns \c true if informational messages should be shown for this category; + \c false otherwise. \note The \l qCInfo() macro already does this check before executing any - code. However, calling this method may be useful to avoid - expensive generation of data that is only used for debug output. + code. However, calling this method may be useful to avoid the + expensive generation of data for debug output only. \since 5.5 */ @@ -294,28 +285,28 @@ QLoggingCategory::~QLoggingCategory() /*! \fn bool QLoggingCategory::isWarningEnabled() const - Returns \c true if warning messages should be shown for this category. - Returns \c false otherwise. + Returns \c true if warning messages should be shown for this category; + \c false otherwise. \note The \l qCWarning() macro already does this check before executing any - code. However, calling this method may be useful to avoid - expensive generation of data that is only used for debug output. + code. However, calling this method may be useful to avoid the + expensive generation of data for debug output only. */ /*! \fn bool QLoggingCategory::isCriticalEnabled() const - Returns \c true if critical messages should be shown for this category. - Returns \c false otherwise. + Returns \c true if critical messages should be shown for this category; + \c false otherwise. \note The \l qCCritical() macro already does this check before executing any - code. However, calling this method may be useful to avoid - expensive generation of data that is only used for debug output. + code. However, calling this method may be useful to avoid the + expensive generation of data for debug output only. */ /*! Returns \c true if a message of type \a msgtype for the category should be - shown. Returns \c false otherwise. + shown; \c false otherwise. */ bool QLoggingCategory::isEnabled(QtMsgType msgtype) const { @@ -332,11 +323,11 @@ bool QLoggingCategory::isEnabled(QtMsgType msgtype) const /*! Changes the message type \a type for the category to \a enable. - This method is meant to be used only from inside a filter - installed by \l installFilter(). See \l {Configuring Categories} for - an overview on how to configure categories globally. + This method is meant for use only from inside a filter installed with + \l installFilter(). For an overview on how to configure categories globally, + see \l {Configuring Categories}. - \note \c QtFatalMsg cannot be changed. It will always remain \c true. + \note \c QtFatalMsg cannot be changed; it will always remain \c true. */ void QLoggingCategory::setEnabled(QtMsgType type, bool enable) { @@ -359,28 +350,25 @@ void QLoggingCategory::setEnabled(QtMsgType type, bool enable) /*! \fn QLoggingCategory &QLoggingCategory::operator()() - Returns the object itself. This allows both a QLoggingCategory variable, and - a factory method returning a QLoggingCategory, to be used in \l qCDebug(), - \l qCWarning(), \l qCCritical() macros. + Returns the object itself. This allows for both: a QLoggingCategory variable, and + a factory method that returns a QLoggingCategory, to be used in \l qCDebug(), + \l qCWarning(), or \l qCCritical() macros. */ /*! \fn const QLoggingCategory &QLoggingCategory::operator()() const - Returns the object itself. This allows both a QLoggingCategory variable, and - a factory method returning a QLoggingCategory, to be used in \l qCDebug(), - \l qCWarning(), \l qCCritical() macros. + Returns the object itself. This allows for both: a QLoggingCategory variable, and + a factory method that returns a QLoggingCategory, to be used in \l qCDebug(), + \l qCWarning(), or \l qCCritical() macros. */ /*! - Returns a pointer to the global category \c "default" that - is used e.g. by qDebug(), qInfo(), qWarning(), qCritical(), qFatal(). + Returns a pointer to the global category \c "default" that is used, for + example, by qDebug(), qInfo(), qWarning(), qCritical(), or qFatal(). - \note The returned pointer may be null during destruction of - static objects. - - \note Ownership of the category is not transferred, do not - \c delete the returned pointer. + \note The pointer returned may be null during destruction of static objects. + Also, don't \c delete this pointer, as ownership of the category isn't transferred. */ QLoggingCategory *QLoggingCategory::defaultCategory() @@ -391,8 +379,7 @@ QLoggingCategory *QLoggingCategory::defaultCategory() /*! \typedef QLoggingCategory::CategoryFilter - This is a typedef for a pointer to a function with the following - signature: + This is a typedef for a pointer to a function with the following signature: \snippet qloggingcategory/main.cpp 20 @@ -408,14 +395,13 @@ QLoggingCategory *QLoggingCategory::defaultCategory() filter is free to change the respective category configuration with \l setEnabled(). - The filter might be called from different threads, but never concurrently. - The filter shall not call any static functions of QLoggingCategory. + When you define your filter, note that it can be called from different threads; but never + concurrently. This filter cannot call any static functions from QLoggingCategory. Example: \snippet qloggingcategory/main.cpp 21 - An alternative way of configuring the default filter is via - \l setFilterRules(). + Alternatively, you can configure the default filter via \l setFilterRules(). */ QLoggingCategory::CategoryFilter QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter) @@ -425,15 +411,15 @@ QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter) /*! Configures which categories and message types should be enabled through a - a set of \a rules. + set of \a rules. Example: \snippet qloggingcategory/main.cpp 2 \note The rules might be ignored if a custom category filter is installed - with \l installFilter(), or if the user defined \c QT_LOGGING_CONF or \c QT_LOGGING_RULES - environment variable. + with \l installFilter(), or if the user has defined the \c QT_LOGGING_CONF + or the \c QT_LOGGING_RULES environment variable. */ void QLoggingCategory::setFilterRules(const QString &rules) { @@ -446,7 +432,7 @@ void QLoggingCategory::setFilterRules(const QString &rules) \threadsafe \since 5.2 - Returns an output stream for debug messages in the logging category + Returns an output stream for debug messages in the logging category, \a category. The macro expands to code that checks whether @@ -457,8 +443,8 @@ void QLoggingCategory::setFilterRules(const QString &rules) \snippet qloggingcategory/main.cpp 10 - \note Arguments are not processed if debug output for the category is not - enabled, so do not rely on any side effects. + \note Arguments aren't processed if the debug output for that \a category is not + enabled, so don't rely on any side effects. \sa qDebug() */ @@ -469,16 +455,16 @@ void QLoggingCategory::setFilterRules(const QString &rules) \threadsafe \since 5.3 - Logs a debug message \a message in the logging category \a category. - \a message might contain place holders that are replaced by additional - arguments, similar to the C printf() function. + Logs a debug message, \a message, in the logging category, \a category. + \a message may contain place holders to be replaced by additional arguments, + similar to the C printf() function. Example: \snippet qloggingcategory/main.cpp 13 - \note Arguments might not be processed if debug output for the category is - not enabled, so do not rely on any side effects. + \note Arguments aren't processed if the debug output for that \a category is not + enabled, so don't rely on any side effects. \sa qDebug() */ @@ -489,7 +475,7 @@ void QLoggingCategory::setFilterRules(const QString &rules) \threadsafe \since 5.5 - Returns an output stream for informational messages in the logging category + Returns an output stream for informational messages in the logging category, \a category. The macro expands to code that checks whether @@ -500,8 +486,8 @@ void QLoggingCategory::setFilterRules(const QString &rules) \snippet qloggingcategory/main.cpp qcinfo_stream - \note Arguments are not processed if debug output for the category is not - enabled, so do not rely on any side effects. + \note If the debug output for a particular category isn't enabled, arguments + won't be processed, so don't rely on any side effects. \sa qInfo() */ @@ -512,16 +498,16 @@ void QLoggingCategory::setFilterRules(const QString &rules) \threadsafe \since 5.5 - Logs an informational message \a message in the logging category \a category. - \a message might contain place holders that are replaced by additional - arguments, similar to the C printf() function. + Logs an informational message, \a message, in the logging category, \a category. + \a message may contain place holders to be replaced by additional arguments, + similar to the C printf() function. Example: \snippet qloggingcategory/main.cpp qcinfo_printf - \note Arguments might not be processed if debug output for the category is - not enabled, so do not rely on any side effects. + \note If the debug output for a particular category isn't enabled, arguments + won't be processed, so don't rely on any side effects. \sa qInfo() */ @@ -532,7 +518,7 @@ void QLoggingCategory::setFilterRules(const QString &rules) \threadsafe \since 5.2 - Returns an output stream for warning messages in the logging category + Returns an output stream for warning messages in the logging category, \a category. The macro expands to code that checks whether @@ -543,8 +529,8 @@ void QLoggingCategory::setFilterRules(const QString &rules) \snippet qloggingcategory/main.cpp 11 - \note Arguments are not processed if warning output for the category is not - enabled, so do not rely on any side effects. + \note If the warning output for a particular category isn't enabled, arguments + won't be processed, so don't rely on any side effects. \sa qWarning() */ @@ -555,16 +541,16 @@ void QLoggingCategory::setFilterRules(const QString &rules) \threadsafe \since 5.3 - Logs a warning message \a message in the logging category \a category. - \a message might contain place holders that are replaced by additional - arguments, similar to the C printf() function. + Logs a warning message, \a message, in the logging category, \a category. + \a message may contain place holders to be replaced by additional arguments, + similar to the C printf() function. Example: \snippet qloggingcategory/main.cpp 14 - \note Arguments might not be processed if warning output for the category is - not enabled, so do not rely on any side effects. + \note If the warning output for a particular category isn't enabled, arguments + won't be processed, so don't rely on any side effects. \sa qWarning() */ @@ -575,7 +561,7 @@ void QLoggingCategory::setFilterRules(const QString &rules) \threadsafe \since 5.2 - Returns an output stream for critical messages in the logging category + Returns an output stream for critical messages in the logging category, \a category. The macro expands to code that checks whether @@ -586,8 +572,9 @@ void QLoggingCategory::setFilterRules(const QString &rules) \snippet qloggingcategory/main.cpp 12 - \note Arguments are not processed if critical output for the category is not - enabled, so do not rely on any side effects. + + \note If the critical output for a particular category isn't enabled, arguments + won't be processed, so don't rely on any side effects. \sa qCritical() */ @@ -598,16 +585,16 @@ void QLoggingCategory::setFilterRules(const QString &rules) \threadsafe \since 5.3 - Logs a critical message \a message in the logging category \a category. - \a message might contain place holders that are replaced by additional - arguments, similar to the C printf() function. + Logs a critical message, \a message, in the logging category, \a category. + \a message may contain place holders to be replaced by additional arguments, + similar to the C printf() function. Example: \snippet qloggingcategory/main.cpp 15 - \note Arguments might not be processed if critical output for the category - is not enabled, so do not rely on any side effects. + \note If the critical output for a particular category isn't enabled, arguments + won't be processed, so don't rely on any side effects. \sa qCritical() */ @@ -633,7 +620,7 @@ void QLoggingCategory::setFilterRules(const QString &rules) \a string identifier. By default, all message types are enabled. Only one translation unit in a library or executable can define a category - with a specific name. The implicitly defined QLoggingCategory object is + with a specific name. The implicitly-defined QLoggingCategory object is created on first use, in a thread-safe manner. This macro must be used outside of a class or method. @@ -650,7 +637,7 @@ void QLoggingCategory::setFilterRules(const QString &rules) and more severe are enabled, types with a lower severity are disabled. Only one translation unit in a library or executable can define a category - with a specific name. The implicitly defined QLoggingCategory object is + with a specific name. The implicitly-defined QLoggingCategory object is created on first use, in a thread-safe manner. This macro must be used outside of a class or method. It is only defined |