1/****************************************************************************
2**
3** Copyright (C) 2017 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtCore module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include "qloggingcategory.h"
41#include "qloggingregistry_p.h"
42
43QT_BEGIN_NAMESPACE
44
45const char qtDefaultCategoryName[] = "default";
46
47Q_GLOBAL_STATIC_WITH_ARGS(QLoggingCategory, qtDefaultCategory,
48 (qtDefaultCategoryName))
49
50#ifndef Q_ATOMIC_INT8_IS_SUPPORTED
51static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
52{
53 const int bit = 1 << shift;
54
55 if (enable)
56 atomic->fetchAndOrRelaxed(bit);
57 else
58 atomic->fetchAndAndRelaxed(~bit);
59}
60#endif
61
62/*!
63 \class QLoggingCategory
64 \inmodule QtCore
65 \since 5.2
66 \threadsafe
67
68 \brief The QLoggingCategory class represents a category, or 'area' in the
69 logging infrastructure.
70
71 QLoggingCategory represents a certain logging category - identified by a
72 string - at runtime. A category can be configured to enable or disable
73 logging of messages per message type. Whether a message type is enabled or
74 not can be checked with the \l isDebugEnabled(), \l isInfoEnabled(),
75 \l isWarningEnabled(), and \l isCriticalEnabled() methods.
76
77 All objects are meant to be configured by a common registry (see also
78 \l{Configuring Categories}). Different objects can also represent the same
79 category. It is therefore not recommended to export objects across module
80 boundaries, nor to manipulate the objects directly, nor to inherit from
81 QLoggingCategory.
82
83 \section1 Creating Category Objects
84
85 The Q_DECLARE_LOGGING_CATEGORY() and Q_LOGGING_CATEGORY() macros
86 conveniently declare and create QLoggingCategory objects:
87
88 \snippet qloggingcategory/main.cpp 1
89
90 \note Category names are free text. However, to allow easy configuration
91 of the categories using \l{Logging Rules} the names should follow some rules:
92 \list
93 \li Use letters and numbers only.
94 \li Further structure categories into common areas by using dots.
95 \li Avoid the category names \c{debug}, \c{info}, \c{warning}, and \c{critical}.
96 \li Category names starting with \c{qt} are reserved for Qt modules.
97 \endlist
98
99 QLoggingCategory objects implicitly defined by Q_LOGGING_CATEGORY()
100 are created on first use in a thread-safe manner.
101
102 \section1 Checking Category Configuration
103
104 QLoggingCategory provides \l isDebugEnabled(), \l isInfoEnabled(),
105 \l isWarningEnabled(), \l isCriticalEnabled(), as well as \l isEnabled()
106 to check whether messages for the given message type should be logged.
107
108 \note The qCDebug(), qCWarning(), qCCritical() macros prevent arguments
109 from being evaluated if the respective message types are not enabled for the
110 category, so explicit checking is not needed:
111
112 \snippet qloggingcategory/main.cpp 4
113
114 \section1 Default Category Configuration
115
116 Both the QLoggingCategory constructor and the Q_LOGGING_CATEGORY() macro
117 accept an optional QtMsgType argument, which disables all message types with
118 a lower severity. That is, a category declared with
119
120 \snippet qloggingcategory/main.cpp 5
121
122 will log messages of type \c QtWarningMsg, \c QtCriticalMsg, \c QtFatalMsg, but will
123 ignore messages of type \c QtDebugMsg and \c QtInfoMsg.
124
125 If no argument is passed, all messages will be logged.
126
127 \section1 Configuring Categories
128
129 The default configuration of categories can be overridden either by setting logging
130 rules, or by installing a custom filter.
131
132 \section2 Logging Rules
133
134 Logging rules allow logging for categories to be enabled or disabled in a
135 flexible way. Rules are specified in text, where every line must have the
136 format
137
138 \snippet code/src_corelib_io_qloggingcategory.cpp 0
139
140 \c <category> is the name of the category, potentially with \c{*} as a
141 wildcard symbol as the first or last character (or at both positions).
142 The optional \c <type> must be either \c debug, \c info, \c warning, or \c critical.
143 Lines that do not fit this scheme are ignored.
144
145 Rules are evaluated in text order, from first to last. That is, if two rules
146 apply to a category/type, the rule that comes later is applied.
147
148 Rules can be set via \l setFilterRules():
149
150 \snippet code/src_corelib_io_qloggingcategory.cpp 1
151
152 Since Qt 5.3, logging rules are also
153 automatically loaded from the \c [Rules] section of a logging
154 configuration file. Such configuration files are looked up in the QtProject
155 configuration directory, or explicitly set in a \c QT_LOGGING_CONF
156 environment variable:
157
158 \snippet code/src_corelib_io_qloggingcategory.cpp 2
159
160 Since Qt 5.3, logging rules can also be specified in a \c QT_LOGGING_RULES
161 environment variable. And since Qt 5.6, multiple rules can also be
162 separated by semicolons:
163
164 \snippet code/src_corelib_io_qloggingcategory.cpp 3
165
166 Rules set by \l setFilterRules() take precedence over rules specified
167 in the QtProject configuration directory, and can, in turn, be
168 overwritten by rules from the configuration file specified by
169 \c QT_LOGGING_CONF, and rules set by \c QT_LOGGING_RULES.
170
171 Order of evaluation:
172 \list
173 \li [QLibraryInfo::DataPath]/qtlogging.ini
174 \li QtProject/qtlogging.ini
175 \li \l setFilterRules()
176 \li \c QT_LOGGING_CONF
177 \li \c QT_LOGGING_RULES
178 \endlist
179
180 The \c QtProject/qtlogging.ini file is looked up in all directories returned
181 by QStandardPaths::GenericConfigLocation, e.g.
182
183 \list
184 \li on \macos and iOS: \c ~/Library/Preferences
185 \li on Unix: \c ~/.config, \c /etc/xdg
186 \li on Windows: \c %LOCALAPPDATA%, \c %ProgramData%,
187 \l QCoreApplication::applicationDirPath(),
188 QCoreApplication::applicationDirPath() + \c "/data"
189 \endlist
190
191 Set the \c QT_LOGGING_DEBUG environment variable to see from where
192 logging rules are loaded.
193
194 \section2 Installing a Custom Filter
195
196 As a lower-level alternative to the text rules, you can also implement a
197 custom filter via \l installFilter(). All filter rules are ignored in this
198 case.
199
200 \section1 Printing the Category
201
202 Use the \c %{category} placeholder to print the category in the default
203 message handler:
204
205 \snippet qloggingcategory/main.cpp 3
206*/
207
208/*!
209 Constructs a QLoggingCategory object with the provided \a category name.
210 All message types for this category are enabled by default.
211
212 If \a category is \c{0}, the category name is changed to \c "default".
213
214 Note that \a category must be kept valid during the lifetime of this object.
215*/
216QLoggingCategory::QLoggingCategory(const char *category)
217 : d(nullptr),
218 name(nullptr)
219{
220 init(category, QtDebugMsg);
221}
222
223/*!
224 Constructs a QLoggingCategory object with the provided \a category name,
225 and enables all messages with types more severe or equal than \a enableForLevel.
226
227 If \a category is \c{0}, the category name is changed to \c "default".
228
229 Note that \a category must be kept valid during the lifetime of this object.
230
231 \since 5.4
232*/
233QLoggingCategory::QLoggingCategory(const char *category, QtMsgType enableForLevel)
234 : d(nullptr),
235 name(nullptr)
236{
237 init(category, enableForLevel);
238}
239
240void QLoggingCategory::init(const char *category, QtMsgType severityLevel)
241{
242 enabled.storeRelaxed(0x01010101); // enabledDebug = enabledWarning = enabledCritical = true;
243
244 if (category)
245 name = category;
246 else
247 name = qtDefaultCategoryName;
248
249 if (QLoggingRegistry *reg = QLoggingRegistry::instance())
250 reg->registerCategory(this, severityLevel);
251}
252
253/*!
254 Destructs a QLoggingCategory object.
255*/
256QLoggingCategory::~QLoggingCategory()
257{
258 if (QLoggingRegistry *reg = QLoggingRegistry::instance())
259 reg->unregisterCategory(this);
260}
261
262/*!
263 \fn const char *QLoggingCategory::categoryName() const
264
265 Returns the name of the category.
266*/
267
268/*!
269 \fn bool QLoggingCategory::isDebugEnabled() const
270
271 Returns \c true if debug messages should be shown for this category.
272 Returns \c false otherwise.
273
274 \note The \l qCDebug() macro already does this check before executing any
275 code. However, calling this method may be useful to avoid
276 expensive generation of data that is only used for debug output.
277*/
278
279
280/*!
281 \fn bool QLoggingCategory::isInfoEnabled() const
282
283 Returns \c true if informational messages should be shown for this category.
284 Returns \c false otherwise.
285
286 \note The \l qCInfo() macro already does this check before executing any
287 code. However, calling this method may be useful to avoid
288 expensive generation of data that is only used for debug output.
289
290 \since 5.5
291*/
292
293
294/*!
295 \fn bool QLoggingCategory::isWarningEnabled() const
296
297 Returns \c true if warning messages should be shown for this category.
298 Returns \c false otherwise.
299
300 \note The \l qCWarning() macro already does this check before executing any
301 code. However, calling this method may be useful to avoid
302 expensive generation of data that is only used for debug output.
303*/
304
305/*!
306 \fn bool QLoggingCategory::isCriticalEnabled() const
307
308 Returns \c true if critical messages should be shown for this category.
309 Returns \c false otherwise.
310
311 \note The \l qCCritical() macro already does this check before executing any
312 code. However, calling this method may be useful to avoid
313 expensive generation of data that is only used for debug output.
314*/
315
316/*!
317 Returns \c true if a message of type \a msgtype for the category should be
318 shown. Returns \c false otherwise.
319*/
320bool QLoggingCategory::isEnabled(QtMsgType msgtype) const
321{
322 switch (msgtype) {
323 case QtDebugMsg: return isDebugEnabled();
324 case QtInfoMsg: return isInfoEnabled();
325 case QtWarningMsg: return isWarningEnabled();
326 case QtCriticalMsg: return isCriticalEnabled();
327 case QtFatalMsg: return true;
328 }
329 return false;
330}
331
332/*!
333 Changes the message type \a type for the category to \a enable.
334
335 This method is meant to be used only from inside a filter
336 installed by \l installFilter(). See \l {Configuring Categories} for
337 an overview on how to configure categories globally.
338
339 \note \c QtFatalMsg cannot be changed. It will always remain \c true.
340*/
341void QLoggingCategory::setEnabled(QtMsgType type, bool enable)
342{
343 switch (type) {
344#ifdef Q_ATOMIC_INT8_IS_SUPPORTED
345 case QtDebugMsg: bools.enabledDebug.storeRelaxed(enable); break;
346 case QtInfoMsg: bools.enabledInfo.storeRelaxed(enable); break;
347 case QtWarningMsg: bools.enabledWarning.storeRelaxed(enable); break;
348 case QtCriticalMsg: bools.enabledCritical.storeRelaxed(enable); break;
349#else
350 case QtDebugMsg: setBoolLane(&enabled, enable, DebugShift); break;
351 case QtInfoMsg: setBoolLane(&enabled, enable, InfoShift); break;
352 case QtWarningMsg: setBoolLane(&enabled, enable, WarningShift); break;
353 case QtCriticalMsg: setBoolLane(&enabled, enable, CriticalShift); break;
354#endif
355 case QtFatalMsg: break;
356 }
357}
358
359/*!
360 \fn QLoggingCategory &QLoggingCategory::operator()()
361
362 Returns the object itself. This allows both a QLoggingCategory variable, and
363 a factory method returning a QLoggingCategory, to be used in \l qCDebug(),
364 \l qCWarning(), \l qCCritical() macros.
365 */
366
367/*!
368 \fn const QLoggingCategory &QLoggingCategory::operator()() const
369
370 Returns the object itself. This allows both a QLoggingCategory variable, and
371 a factory method returning a QLoggingCategory, to be used in \l qCDebug(),
372 \l qCWarning(), \l qCCritical() macros.
373 */
374
375/*!
376 Returns a pointer to the global category \c "default" that
377 is used e.g. by qDebug(), qInfo(), qWarning(), qCritical(), qFatal().
378
379 \note The returned pointer may be null during destruction of
380 static objects.
381
382 \note Ownership of the category is not transferred, do not
383 \c delete the returned pointer.
384
385 */
386QLoggingCategory *QLoggingCategory::defaultCategory()
387{
388 return qtDefaultCategory();
389}
390
391/*!
392 \typedef QLoggingCategory::CategoryFilter
393
394 This is a typedef for a pointer to a function with the following
395 signature:
396
397 \snippet qloggingcategory/main.cpp 20
398
399 A function with this signature can be installed with \l installFilter().
400*/
401
402/*!
403 Installs a function \a filter that is used to determine which categories
404 and message types should be enabled. Returns a pointer to the previous
405 installed filter.
406
407 Every QLoggingCategory object created is passed to the filter, and the
408 filter is free to change the respective category configuration with
409 \l setEnabled().
410
411 The filter might be called from different threads, but never concurrently.
412 The filter shall not call any static functions of QLoggingCategory.
413
414 Example:
415 \snippet qloggingcategory/main.cpp 21
416
417 An alternative way of configuring the default filter is via
418 \l setFilterRules().
419 */
420QLoggingCategory::CategoryFilter
421QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter)
422{
423 return QLoggingRegistry::instance()->installFilter(filter);
424}
425
426/*!
427 Configures which categories and message types should be enabled through a
428 a set of \a rules.
429
430 Example:
431
432 \snippet qloggingcategory/main.cpp 2
433
434 \note The rules might be ignored if a custom category filter is installed
435 with \l installFilter(), or if the user defined \c QT_LOGGING_CONF or \c QT_LOGGING_RULES
436 environment variable.
437*/
438void QLoggingCategory::setFilterRules(const QString &rules)
439{
440 QLoggingRegistry::instance()->setApiRules(rules);
441}
442
443/*!
444 \macro qCDebug(category)
445 \relates QLoggingCategory
446 \threadsafe
447 \since 5.2
448
449 Returns an output stream for debug messages in the logging category
450 \a category.
451
452 The macro expands to code that checks whether
453 \l QLoggingCategory::isDebugEnabled() evaluates to \c true.
454 If so, the stream arguments are processed and sent to the message handler.
455
456 Example:
457
458 \snippet qloggingcategory/main.cpp 10
459
460 \note Arguments are not processed if debug output for the category is not
461 enabled, so do not rely on any side effects.
462
463 \sa qDebug()
464*/
465
466/*!
467 \macro qCDebug(category, const char *message, ...)
468 \relates QLoggingCategory
469 \threadsafe
470 \since 5.3
471
472 Logs a debug message \a message in the logging category \a category.
473 \a message might contain place holders that are replaced by additional
474 arguments, similar to the C printf() function.
475
476 Example:
477
478 \snippet qloggingcategory/main.cpp 13
479
480 \note Arguments might not be processed if debug output for the category is
481 not enabled, so do not rely on any side effects.
482
483 \sa qDebug()
484*/
485
486/*!
487 \macro qCInfo(category)
488 \relates QLoggingCategory
489 \threadsafe
490 \since 5.5
491
492 Returns an output stream for informational messages in the logging category
493 \a category.
494
495 The macro expands to code that checks whether
496 \l QLoggingCategory::isInfoEnabled() evaluates to \c true.
497 If so, the stream arguments are processed and sent to the message handler.
498
499 Example:
500
501 \snippet qloggingcategory/main.cpp qcinfo_stream
502
503 \note Arguments are not processed if debug output for the category is not
504 enabled, so do not rely on any side effects.
505
506 \sa qInfo()
507*/
508
509/*!
510 \macro qCInfo(category, const char *message, ...)
511 \relates QLoggingCategory
512 \threadsafe
513 \since 5.5
514
515 Logs an informational message \a message in the logging category \a category.
516 \a message might contain place holders that are replaced by additional
517 arguments, similar to the C printf() function.
518
519 Example:
520
521 \snippet qloggingcategory/main.cpp qcinfo_printf
522
523 \note Arguments might not be processed if debug output for the category is
524 not enabled, so do not rely on any side effects.
525
526 \sa qInfo()
527*/
528
529/*!
530 \macro qCWarning(category)
531 \relates QLoggingCategory
532 \threadsafe
533 \since 5.2
534
535 Returns an output stream for warning messages in the logging category
536 \a category.
537
538 The macro expands to code that checks whether
539 \l QLoggingCategory::isWarningEnabled() evaluates to \c true.
540 If so, the stream arguments are processed and sent to the message handler.
541
542 Example:
543
544 \snippet qloggingcategory/main.cpp 11
545
546 \note Arguments are not processed if warning output for the category is not
547 enabled, so do not rely on any side effects.
548
549 \sa qWarning()
550*/
551
552/*!
553 \macro qCWarning(category, const char *message, ...)
554 \relates QLoggingCategory
555 \threadsafe
556 \since 5.3
557
558 Logs a warning message \a message in the logging category \a category.
559 \a message might contain place holders that are replaced by additional
560 arguments, similar to the C printf() function.
561
562 Example:
563
564 \snippet qloggingcategory/main.cpp 14
565
566 \note Arguments might not be processed if warning output for the category is
567 not enabled, so do not rely on any side effects.
568
569 \sa qWarning()
570*/
571
572/*!
573 \macro qCCritical(category)
574 \relates QLoggingCategory
575 \threadsafe
576 \since 5.2
577
578 Returns an output stream for critical messages in the logging category
579 \a category.
580
581 The macro expands to code that checks whether
582 \l QLoggingCategory::isCriticalEnabled() evaluates to \c true.
583 If so, the stream arguments are processed and sent to the message handler.
584
585 Example:
586
587 \snippet qloggingcategory/main.cpp 12
588
589 \note Arguments are not processed if critical output for the category is not
590 enabled, so do not rely on any side effects.
591
592 \sa qCritical()
593*/
594
595/*!
596 \macro qCCritical(category, const char *message, ...)
597 \relates QLoggingCategory
598 \threadsafe
599 \since 5.3
600
601 Logs a critical message \a message in the logging category \a category.
602 \a message might contain place holders that are replaced by additional
603 arguments, similar to the C printf() function.
604
605 Example:
606
607 \snippet qloggingcategory/main.cpp 15
608
609 \note Arguments might not be processed if critical output for the category
610 is not enabled, so do not rely on any side effects.
611
612 \sa qCritical()
613*/
614/*!
615 \macro Q_DECLARE_LOGGING_CATEGORY(name)
616 \sa Q_LOGGING_CATEGORY()
617 \relates QLoggingCategory
618 \since 5.2
619
620 Declares a logging category \a name. The macro can be used to declare
621 a common logging category shared in different parts of the program.
622
623 This macro must be used outside of a class or method.
624*/
625
626/*!
627 \macro Q_LOGGING_CATEGORY(name, string)
628 \sa Q_DECLARE_LOGGING_CATEGORY()
629 \relates QLoggingCategory
630 \since 5.2
631
632 Defines a logging category \a name, and makes it configurable under the
633 \a string identifier. By default, all message types are enabled.
634
635 Only one translation unit in a library or executable can define a category
636 with a specific name. The implicitly defined QLoggingCategory object is
637 created on first use, in a thread-safe manner.
638
639 This macro must be used outside of a class or method.
640*/
641
642/*!
643 \macro Q_LOGGING_CATEGORY(name, string, msgType)
644 \sa Q_DECLARE_LOGGING_CATEGORY()
645 \relates QLoggingCategory
646 \since 5.4
647
648 Defines a logging category \a name, and makes it configurable under the
649 \a string identifier. By default, messages of QtMsgType \a msgType
650 and more severe are enabled, types with a lower severity are disabled.
651
652 Only one translation unit in a library or executable can define a category
653 with a specific name. The implicitly defined QLoggingCategory object is
654 created on first use, in a thread-safe manner.
655
656 This macro must be used outside of a class or method. It is only defined
657 if variadic macros are supported.
658*/
659
660QT_END_NAMESPACE
661