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.
74
75 To check whether a message type is enabled or not, use one of these methods:
76 \l isDebugEnabled(), \l isInfoEnabled(), \l isWarningEnabled(), and
77 \l isCriticalEnabled().
78
79 All objects are meant to be configured by a common registry, as described in
80 \l{Configuring Categories}. Different objects can also represent the same
81 category. Therefore, it's \b{not} recommended to export objects across
82 module boundaries, to manipulate the objects directly, or to inherit from
83 QLoggingCategory.
84
85 \section1 Creating Category Objects
86
87 The Q_DECLARE_LOGGING_CATEGORY() and Q_LOGGING_CATEGORY() macros
88 conveniently declare and create QLoggingCategory objects:
89
90 \snippet qloggingcategory/main.cpp 1
91
92 Category names are free text; to configure categories using \l{Logging Rules}, their
93 names should follow this convention:
94 \list
95 \li Use letters and numbers only.
96 \li Use dots to further structure categories into common areas.
97 \li Avoid the category names: \c{debug}, \c{info}, \c{warning}, and \c{critical}.
98 \li Category names with the \c{qt} prefix are solely reserved for Qt modules.
99 \endlist
100
101 QLoggingCategory objects that are implicitly defined by Q_LOGGING_CATEGORY()
102 are created on first use, in a thread-safe manner.
103
104 \section1 Checking Category Configuration
105
106 QLoggingCategory provides \l isDebugEnabled(), \l isInfoEnabled(),
107 \l isWarningEnabled(), \l isCriticalEnabled(), as well as \l isEnabled()
108 to check whether messages for the given message type should be logged.
109
110 The qCDebug(), qCWarning(), and qCCritical() macros prevent arguments from
111 being evaluated if the respective message types are not enabled for the
112 category, so explicit checking is not needed:
113
114 \snippet qloggingcategory/main.cpp 4
115
116 \section1 Default Category Configuration
117
118 Both the QLoggingCategory constructor and the Q_LOGGING_CATEGORY() macro
119 accept an optional QtMsgType argument, which disables all message types with
120 a lower severity. That is, a category declared with
121
122 \snippet qloggingcategory/main.cpp 5
123
124 logs messages of type \c QtWarningMsg, \c QtCriticalMsg, \c QtFatalMsg, but
125 ignores messages of type \c QtDebugMsg and \c QtInfoMsg.
126
127 If no argument is passed, all messages are logged.
128
129 \section1 Configuring Categories
130
131 You can override the default configuration for categories either by setting
132 logging rules, or by installing a custom filter.
133
134 \section2 Logging Rules
135
136 Logging rules let you enable or disable logging for categories in a flexible
137 way. Rules are specified in text, where every line must have the format:
138
139 \snippet code/src_corelib_io_qloggingcategory.cpp 0
140
141 \c <category> is the name of the category, potentially with \c{*} as a
142 wildcard symbol for the first or last character; or at both positions.
143 The optional \c <type> must be \c debug, \c info, \c warning, or \c critical.
144 Lines that don't fit this scheme are ignored.
145
146 Rules are evaluated in text order, from first to last. That is, if two rules
147 apply to a category/type, the rule that comes later is applied.
148
149 Rules can be set via \l setFilterRules():
150
151 \snippet code/src_corelib_io_qloggingcategory.cpp 1
152
153 Logging rules are automatically loaded from the \c [Rules] section in a logging
154 configuration file. These configuration files are looked up in the QtProject
155 configuration directory, or explicitly set in a \c QT_LOGGING_CONF environment
156 variable:
157
158 \snippet code/src_corelib_io_qloggingcategory.cpp 2
159
160 Logging rules can also be specified in a \c QT_LOGGING_RULES environment variable;
161 multiple rules can also be separated by semicolons:
162
163 \snippet code/src_corelib_io_qloggingcategory.cpp 3
164
165 Rules set by \l setFilterRules() take precedence over rules specified in the
166 QtProject configuration directory. In turn, these rules can be overwritten by those
167 from the configuration file specified by \c QT_LOGGING_CONF, and those set by
168 \c QT_LOGGING_RULES.
169
170 The order of evaluation is as follows:
171 \list 1
172 \li [QLibraryInfo::DataPath]/qtlogging.ini
173 \li QtProject/qtlogging.ini
174 \li \l setFilterRules()
175 \li \c QT_LOGGING_CONF
176 \li \c QT_LOGGING_RULES
177 \endlist
178
179 The \c QtProject/qtlogging.ini file is looked up in all directories returned
180 by QStandardPaths::GenericConfigLocation.
181
182 Set the \c QT_LOGGING_DEBUG environment variable to find out where your logging
183 rules are loaded from.
184
185 \section2 Installing a Custom Filter
186
187 As a lower-level alternative to the text rules, you can also implement a
188 custom filter via \l installFilter(). All filter rules are ignored in this
189 case.
190
191 \section1 Printing the Category
192
193 Use the \c %{category} placeholder to print the category in the default
194 message handler:
195
196 \snippet qloggingcategory/main.cpp 3
197*/
198
199/*!
200 Constructs a QLoggingCategory object with the provided \a category name,
201 and enables all messages with types at least as verbose as \a enableForLevel,
202 which defaults to QtDebugMsg (which enables all categories).
203
204 If \a category is \nullptr, the category name \c "default" is used.
205
206 \note \a category must be kept valid during the lifetime of this object.
207 Using a string literal for it is the usual way to achieve this.
208
209 \since 5.4
210*/
211QLoggingCategory::QLoggingCategory(const char *category, QtMsgType enableForLevel)
212 : d(nullptr),
213 name(nullptr)
214{
215 init(category, enableForLevel);
216}
217
218void QLoggingCategory::init(const char *category, QtMsgType severityLevel)
219{
220 enabled.storeRelaxed(0x01010101); // enabledDebug = enabledWarning = enabledCritical = true;
221
222 if (category)
223 name = category;
224 else
225 name = qtDefaultCategoryName;
226
227 if (QLoggingRegistry *reg = QLoggingRegistry::instance())
228 reg->registerCategory(this, severityLevel);
229}
230
231/*!
232 Destroys a QLoggingCategory object.
233*/
234QLoggingCategory::~QLoggingCategory()
235{
236 if (QLoggingRegistry *reg = QLoggingRegistry::instance())
237 reg->unregisterCategory(this);
238}
239
240/*!
241 \fn const char *QLoggingCategory::categoryName() const
242
243 Returns the name of the category.
244*/
245
246/*!
247 \fn bool QLoggingCategory::isDebugEnabled() const
248
249 Returns \c true if debug messages should be shown for this category;
250 \c false otherwise.
251
252 \note The \l qCDebug() macro already does this check before running any
253 code. However, calling this method may be useful to avoid the
254 expensive generation of data for debug output only.
255*/
256
257
258/*!
259 \fn bool QLoggingCategory::isInfoEnabled() const
260
261 Returns \c true if informational messages should be shown for this category;
262 \c false otherwise.
263
264 \note The \l qCInfo() macro already does this check before executing any
265 code. However, calling this method may be useful to avoid the
266 expensive generation of data for debug output only.
267
268 \since 5.5
269*/
270
271
272/*!
273 \fn bool QLoggingCategory::isWarningEnabled() const
274
275 Returns \c true if warning messages should be shown for this category;
276 \c false otherwise.
277
278 \note The \l qCWarning() macro already does this check before executing any
279 code. However, calling this method may be useful to avoid the
280 expensive generation of data for debug output only.
281*/
282
283/*!
284 \fn bool QLoggingCategory::isCriticalEnabled() const
285
286 Returns \c true if critical messages should be shown for this category;
287 \c false otherwise.
288
289 \note The \l qCCritical() macro already does this check before executing any
290 code. However, calling this method may be useful to avoid the
291 expensive generation of data for debug output only.
292*/
293
294/*!
295 Returns \c true if a message of type \a msgtype for the category should be
296 shown; \c false otherwise.
297*/
298bool QLoggingCategory::isEnabled(QtMsgType msgtype) const
299{
300 switch (msgtype) {
301 case QtDebugMsg: return isDebugEnabled();
302 case QtInfoMsg: return isInfoEnabled();
303 case QtWarningMsg: return isWarningEnabled();
304 case QtCriticalMsg: return isCriticalEnabled();
305 case QtFatalMsg: return true;
306 }
307 return false;
308}
309
310/*!
311 Changes the message type \a type for the category to \a enable.
312
313 This method is meant for use only from inside a filter installed with
314 \l installFilter(). For an overview on how to configure categories globally,
315 see \l {Configuring Categories}.
316
317 \note \c QtFatalMsg cannot be changed; it will always remain \c true.
318*/
319void QLoggingCategory::setEnabled(QtMsgType type, bool enable)
320{
321 switch (type) {
322#ifdef Q_ATOMIC_INT8_IS_SUPPORTED
323 case QtDebugMsg: bools.enabledDebug.storeRelaxed(enable); break;
324 case QtInfoMsg: bools.enabledInfo.storeRelaxed(enable); break;
325 case QtWarningMsg: bools.enabledWarning.storeRelaxed(enable); break;
326 case QtCriticalMsg: bools.enabledCritical.storeRelaxed(enable); break;
327#else
328 case QtDebugMsg: setBoolLane(&enabled, enable, DebugShift); break;
329 case QtInfoMsg: setBoolLane(&enabled, enable, InfoShift); break;
330 case QtWarningMsg: setBoolLane(&enabled, enable, WarningShift); break;
331 case QtCriticalMsg: setBoolLane(&enabled, enable, CriticalShift); break;
332#endif
333 case QtFatalMsg: break;
334 }
335}
336
337/*!
338 \fn QLoggingCategory &QLoggingCategory::operator()()
339
340 Returns the object itself. This allows for both: a QLoggingCategory variable, and
341 a factory method that returns a QLoggingCategory, to be used in \l qCDebug(),
342 \l qCWarning(), or \l qCCritical() macros.
343 */
344
345/*!
346 \fn const QLoggingCategory &QLoggingCategory::operator()() const
347
348 Returns the object itself. This allows for both: a QLoggingCategory variable, and
349 a factory method that returns a QLoggingCategory, to be used in \l qCDebug(),
350 \l qCWarning(), or \l qCCritical() macros.
351 */
352
353/*!
354 Returns a pointer to the global category \c "default" that is used, for
355 example, by qDebug(), qInfo(), qWarning(), qCritical(), or qFatal().
356
357 \note The pointer returned may be null during destruction of static objects.
358 Also, don't \c delete this pointer, as ownership of the category isn't transferred.
359
360 */
361QLoggingCategory *QLoggingCategory::defaultCategory()
362{
363 return qtDefaultCategory();
364}
365
366/*!
367 \typedef QLoggingCategory::CategoryFilter
368
369 This is a typedef for a pointer to a function with the following signature:
370
371 \snippet qloggingcategory/main.cpp 20
372
373 A function with this signature can be installed with \l installFilter().
374*/
375
376/*!
377 Installs a function \a filter that is used to determine which categories
378 and message types should be enabled. Returns a pointer to the previous
379 installed filter.
380
381 Every QLoggingCategory object created is passed to the filter, and the
382 filter is free to change the respective category configuration with
383 \l setEnabled().
384
385 When you define your filter, note that it can be called from different threads; but never
386 concurrently. This filter cannot call any static functions from QLoggingCategory.
387
388 Example:
389 \snippet qloggingcategory/main.cpp 21
390
391 Alternatively, you can configure the default filter via \l setFilterRules().
392 */
393QLoggingCategory::CategoryFilter
394QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter)
395{
396 return QLoggingRegistry::instance()->installFilter(filter);
397}
398
399/*!
400 Configures which categories and message types should be enabled through a
401 set of \a rules.
402
403 Example:
404
405 \snippet qloggingcategory/main.cpp 2
406
407 \note The rules might be ignored if a custom category filter is installed
408 with \l installFilter(), or if the user has defined the \c QT_LOGGING_CONF
409 or the \c QT_LOGGING_RULES environment variable.
410*/
411void QLoggingCategory::setFilterRules(const QString &rules)
412{
413 QLoggingRegistry::instance()->setApiRules(rules);
414}
415
416/*!
417 \macro qCDebug(category)
418 \relates QLoggingCategory
419 \threadsafe
420 \since 5.2
421
422 Returns an output stream for debug messages in the logging category,
423 \a category.
424
425 The macro expands to code that checks whether
426 \l QLoggingCategory::isDebugEnabled() evaluates to \c true.
427 If so, the stream arguments are processed and sent to the message handler.
428
429 Example:
430
431 \snippet qloggingcategory/main.cpp 10
432
433 \note Arguments aren't processed if the debug output for that \a category is not
434 enabled, so don't rely on any side effects.
435
436 \sa qDebug()
437*/
438
439/*!
440 \macro qCDebug(category, const char *message, ...)
441 \relates QLoggingCategory
442 \threadsafe
443 \since 5.3
444
445 Logs a debug message, \a message, in the logging category, \a category.
446 \a message may contain place holders to be replaced by additional arguments,
447 similar to the C printf() function.
448
449 Example:
450
451 \snippet qloggingcategory/main.cpp 13
452
453 \note Arguments aren't processed if the debug output for that \a category is not
454 enabled, so don't rely on any side effects.
455
456 \sa qDebug()
457*/
458
459/*!
460 \macro qCInfo(category)
461 \relates QLoggingCategory
462 \threadsafe
463 \since 5.5
464
465 Returns an output stream for informational messages in the logging category,
466 \a category.
467
468 The macro expands to code that checks whether
469 \l QLoggingCategory::isInfoEnabled() evaluates to \c true.
470 If so, the stream arguments are processed and sent to the message handler.
471
472 Example:
473
474 \snippet qloggingcategory/main.cpp qcinfo_stream
475
476 \note If the debug output for a particular category isn't enabled, arguments
477 won't be processed, so don't rely on any side effects.
478
479 \sa qInfo()
480*/
481
482/*!
483 \macro qCInfo(category, const char *message, ...)
484 \relates QLoggingCategory
485 \threadsafe
486 \since 5.5
487
488 Logs an informational message, \a message, in the logging category, \a category.
489 \a message may contain place holders to be replaced by additional arguments,
490 similar to the C printf() function.
491
492 Example:
493
494 \snippet qloggingcategory/main.cpp qcinfo_printf
495
496 \note If the debug output for a particular category isn't enabled, arguments
497 won't be processed, so don't rely on any side effects.
498
499 \sa qInfo()
500*/
501
502/*!
503 \macro qCWarning(category)
504 \relates QLoggingCategory
505 \threadsafe
506 \since 5.2
507
508 Returns an output stream for warning messages in the logging category,
509 \a category.
510
511 The macro expands to code that checks whether
512 \l QLoggingCategory::isWarningEnabled() evaluates to \c true.
513 If so, the stream arguments are processed and sent to the message handler.
514
515 Example:
516
517 \snippet qloggingcategory/main.cpp 11
518
519 \note If the warning output for a particular category isn't enabled, arguments
520 won't be processed, so don't rely on any side effects.
521
522 \sa qWarning()
523*/
524
525/*!
526 \macro qCWarning(category, const char *message, ...)
527 \relates QLoggingCategory
528 \threadsafe
529 \since 5.3
530
531 Logs a warning message, \a message, in the logging category, \a category.
532 \a message may contain place holders to be replaced by additional arguments,
533 similar to the C printf() function.
534
535 Example:
536
537 \snippet qloggingcategory/main.cpp 14
538
539 \note If the warning output for a particular category isn't enabled, arguments
540 won't be processed, so don't rely on any side effects.
541
542 \sa qWarning()
543*/
544
545/*!
546 \macro qCCritical(category)
547 \relates QLoggingCategory
548 \threadsafe
549 \since 5.2
550
551 Returns an output stream for critical messages in the logging category,
552 \a category.
553
554 The macro expands to code that checks whether
555 \l QLoggingCategory::isCriticalEnabled() evaluates to \c true.
556 If so, the stream arguments are processed and sent to the message handler.
557
558 Example:
559
560 \snippet qloggingcategory/main.cpp 12
561
562
563 \note If the critical output for a particular category isn't enabled, arguments
564 won't be processed, so don't rely on any side effects.
565
566 \sa qCritical()
567*/
568
569/*!
570 \macro qCCritical(category, const char *message, ...)
571 \relates QLoggingCategory
572 \threadsafe
573 \since 5.3
574
575 Logs a critical message, \a message, in the logging category, \a category.
576 \a message may contain place holders to be replaced by additional arguments,
577 similar to the C printf() function.
578
579 Example:
580
581 \snippet qloggingcategory/main.cpp 15
582
583 \note If the critical output for a particular category isn't enabled, arguments
584 won't be processed, so don't rely on any side effects.
585
586 \sa qCritical()
587*/
588/*!
589 \macro Q_DECLARE_LOGGING_CATEGORY(name)
590 \sa Q_LOGGING_CATEGORY()
591 \relates QLoggingCategory
592 \since 5.2
593
594 Declares a logging category \a name. The macro can be used to declare
595 a common logging category shared in different parts of the program.
596
597 This macro must be used outside of a class or method.
598*/
599
600/*!
601 \macro Q_LOGGING_CATEGORY(name, string)
602 \sa Q_DECLARE_LOGGING_CATEGORY()
603 \relates QLoggingCategory
604 \since 5.2
605
606 Defines a logging category \a name, and makes it configurable under the
607 \a string identifier. By default, all message types are enabled.
608
609 Only one translation unit in a library or executable can define a category
610 with a specific name. The implicitly-defined QLoggingCategory object is
611 created on first use, in a thread-safe manner.
612
613 This macro must be used outside of a class or method.
614*/
615
616/*!
617 \macro Q_LOGGING_CATEGORY(name, string, msgType)
618 \sa Q_DECLARE_LOGGING_CATEGORY()
619 \relates QLoggingCategory
620 \since 5.4
621
622 Defines a logging category \a name, and makes it configurable under the
623 \a string identifier. By default, messages of QtMsgType \a msgType
624 and more severe are enabled, types with a lower severity are disabled.
625
626 Only one translation unit in a library or executable can define a category
627 with a specific name. The implicitly-defined QLoggingCategory object is
628 created on first use, in a thread-safe manner.
629
630 This macro must be used outside of a class or method. It is only defined
631 if variadic macros are supported.
632*/
633
634QT_END_NAMESPACE
635