1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Trace macro declarations.

    15 *

    16 */

    17 

    18 

    19 #ifndef CNTDEBUG_H

    20 #define CNTDEBUG_H

    21 

    22 #include <QDebug>   // QDebug

    23 #include <QtGlobal> // qDebug()

    24 

    25 /*!

    26     \def CNT_UNUSED(name)

    27     \brief Declares a single variable as unused when tracing is disabled.

    28 

    29     CNT_UNUSED allows variables (usually method parameters) to be declared as used only if

    30     tracing is enabled. Without this variables that are included in trace macros, but not otherwise

    31     used, would cause unused variable warnings on compilation. If tracing is enabled, CNT_UNUSED

    32     has no effect.

    33 

    34     Consider the following class method where the parameter number is not used at all, except for

    35     tracing its value on entry:

    36 

    37     \code

    38     #include <cntdebug.h>

    39 

    40     void MyClass::myMethod(int number)

    41     {

    42         CNT_UNUSED(number)

    43         CNT_ENTRY("number =" << number)

    44 

    45         // ...some more code where the parameter number is not used.

    46 

    47         CNT_EXIT

    48     }

    49     \endcode

    50 

    51     Compiling this method with tracing completely disabled at compile time would cause an unused

    52     variable warning to be issued unless the CNT_UNUSED macro is used to declare the variable as

    53     trace-only.

    54 

    55     \param name The name of the variable to declare as unused if tracing is disabled. To mark

    56     several variables as trace-only, add a separate CNT_UNUSED statement for each.

    57     \sa CNT_STATIC_ENTRY_ARGS(args), CNT_ENTRY_ARGS(args).

    58 */

    59 

    60 /*!

    61     \def CNT_STATIC_ENTRY

    62     \brief A method entry trace macro for static class methods or global functions.

    63 

    64     Invoking CNT_STATIC_ENTRY outputs a timestamp followed by the scope in which the macro

    65     was invoked and the word "entry".

    66 

    67     CNT_STATIC_ENTRY is intended to be used as the first line of static class methods or

    68     global functions. There is a corresponding exit macro, CNT_EXIT.

    69 

    70     The following example shows proper usage of the CNT_STATIC_ENTRY macro. Assuming a class

    71     has been declared with a static method that is implemented like this:

    72 

    73     \code

    74     #include <cntdebug.h>

    75 

    76     void MyClass::myStaticMethod()

    77     {

    78         CNT_STATIC_ENTRY

    79 

    80         int i = 1;

    81         i++;

    82 

    83         CNT_EXIT

    84     }

    85     \endcode

    86 

    87     calling MyClass::myStaticMethod() generates output lines of the following format:

    88 

    89     \code

    90     2009-03-25 11:00:50.171 : static void MyClass::myStaticMethod() entry

    91     2009-03-25 11:00:50.171 : static void MyClass::myStaticMethod() exit

    92     \endcode

    93 

    94     \sa CNT_STATIC_ENTRY_ARGS(args), CNT_EXIT.

    95 */

    96 

    97 /*!

    98     \def CNT_STATIC_ENTRY_ARGS(args)

    99     \brief A method entry trace macro with arguments for static class methods or global functions.

   100 

   101     CNT_STATIC_ENTRY_ARGS(args) is similar to CNT_STATIC_ENTRY but it allows arguments to be

   102     output on the same line without needing to resort to a separate CNT_LOG_ARGS call. This is

   103     especially handy for outputting the parameters of the method call.

   104 

   105     The following example shows proper usage of the CNT_STATIC_ENTRY_ARGS(args) macro. Assuming

   106     a class has been declared with a static method that is implemented like this:

   107 

   108     \code

   109     #include <QString>

   110     #include <cntdebug.h>

   111 

   112     void MyClass::myStaticMethod(const QString &text, int number)

   113     {

   114         CNT_STATIC_ENTRY_ARGS("text =" << text << "number =" << number);

   115 

   116         int i = 1;

   117         i++;

   118 

   119         CNT_EXIT

   120     }

   121     \endcode

   122 

   123     calling MyClass::myStaticMethod(QString("foo"), 74) generates output lines of the following

   124     format:

   125 

   126     \code

   127     2009-03-25 11:00:50.171 : static void MyClass::myStaticMethod(const QString&, int) entry, text = "foo" number = 74

   128     2009-03-25 11:00:50.171 : static void MyClass::myStaticMethod(const QString&, int) exit

   129     \endcode

   130 

   131     \param args Any number of arguments that can be streamed into a QTextStream, joined together

   132     by the streaming operator <<.

   133     \sa CNT_STATIC_ENTRY.

   134 */

   135 

   136 /*!

   137     \def CNT_ENTRY

   138     \brief A method entry trace macro for class methods.

   139 

   140     Invoking CNT_ENTRY outputs a timestamp followed by the scope in which the macro

   141     was invoked, the word "entry" and the this pointer value of the instance invoking the

   142     macro.

   143 

   144     The this pointer value included in the debug output can help make the output more readable, as

   145     it allows different instances of the same class to be distinguished from each other.

   146 

   147     CNT_ENTRY is intended to be used as the first line of class methods. There is a corresponding

   148     exit macro, CNT_EXIT.

   149 

   150     The following example shows proper usage of the CNT_ENTRY macro. Assuming a class has been

   151     declared with a non-static method that is implemented like this:

   152 

   153     \code

   154     #include <cntdebug.h>

   155 

   156     void MyClass::myMethod()

   157     {

   158         CNT_ENTRY

   159 

   160         int i = 1;

   161         i++;

   162 

   163         CNT_EXIT

   164     }

   165     \endcode

   166 

   167     calling myMethod() on an instance of MyClass generates output lines of the following format:

   168 

   169     \code

   170     2009-03-25 11:00:50.171 : void MyClass::myMethod() this 0x6cdab90 entry

   171     2009-03-25 11:00:50.171 : void MyClass::myMethod() exit

   172     \endcode

   173 

   174     \sa CNT_ENTRY_ARGS(args), CNT_EXIT.

   175 */

   176 

   177 /*!

   178     \def CNT_ENTRY_ARGS(args)

   179     \brief A method entry trace macro with arguments for class methods.

   180 

   181     CNT_ENTRY_ARGS(args) is similar to CNT_ENTRY but it allows arguments to be output on the

   182     same line without needing to resort to a separate CNT_LOG_ARGS call. This is especially

   183     handy for outputting the parameters of the method call.

   184 

   185     The following example shows proper usage of the CNT_ENTRY_ARGS(args)) macro. Assuming a

   186     class has been declared with a non-static method that is implemented like this:

   187 

   188     \code

   189     #include <QString>

   190     #include <cntdebug.h>

   191 

   192     void MyClass::myMethod(const QString &text, int number)

   193     {

   194         CNT_ENTRY_ARGS("text =" << text << "number =" << number);

   195 

   196         int i = 1;

   197         i++;

   198 

   199         CNT_EXIT

   200     }

   201     \endcode

   202 

   203     calling myMethod(QString("foo"), 74) on an instance of MyClass generates output lines of the

   204     following format:

   205 

   206     \code

   207     2009-03-25 11:00:50.171 : void MyClass::myMethod(const QString&, int) this 0x6cdab90 entry, text = "foo" number = 74

   208     2009-03-25 11:00:50.171 : void MyClass::myMethod(const QString&, int) exit

   209     \endcode

   210 

   211     \param args Any number of arguments that can be streamed into a QTextStream, joined together

   212     by the streaming operator <<.

   213     \sa CNT_ENTRY, CNT_EXIT.

   214 */

   215 

   216 /*!

   217     \def CNT_EXIT

   218     \brief A method exit trace macro for class methods or global functions.

   219 

   220     Invoking CNT_EXIT outputs a timestamp followed by the scope in which the macro

   221     was invoked and the word "exit".

   222 

   223     CNT_EXIT is intended to be used as the last line of class methods and global functions,

   224     just before the return statement, if any. There are two corresponding entry macros,

   225     CNT_ENTRY and CNT_STATIC_ENTRY, depending on whether the method being traced is a

   226     non-static or a static class method. CNT_EXIT makes no distinction between these two types

   227     of methods and is to be used for both.

   228 

   229     See CNT_ENTRY or CNT_STATIC_ENTRY for an example of how to use CNT_EXIT.

   230 

   231     \sa CNT_EXIT_ARGS(args), CNT_ENTRY, CNT_STATIC_ENTRY.

   232 */

   233 

   234 /*!

   235     \def CNT_EXIT_ARGS(args)

   236     \brief A method exit trace macro with arguments for class methods or global functions.

   237 

   238     CNT_EXIT_ARGS(args) is similar to CNT_EXIT but it allows arguments to be output on the

   239     same line without needing to resort to a separate CNT_LOG_ARGS call. This is especially

   240     handy for outputting the return value of the method call.

   241 

   242     The following example shows proper usage of the CNT_EXIT_ARGS(args) macro. Assuming a

   243     class has been declared with a static method that is implemented like this:

   244 

   245     \code

   246     #include <QString>

   247     #include <cntdebug.h>

   248 

   249     int MyClass::myStaticMethod(const QString &text)

   250     {

   251         CNT_STATIC_ENTRY_ARGS("text =" << text);

   252 

   253         int length = text.length();

   254 

   255         CNT_EXIT_ARGS("length" << length);

   256 

   257         return length;

   258     }

   259     \endcode

   260 

   261     calling MyClass::myStaticMethod(QString("foo")) generates output lines of the following format:

   262 

   263     \code

   264     2009-03-25 13:20:36.448 : static int MyClass::myStaticMethod(const QString&) entry, text = "foo"

   265     2009-03-25 13:20:36.448 : static int MyClass::myStaticMethod(const QString&) exit, length 3

   266     \endcode

   267 

   268     Although the example above is a static method, CNT_EXIT_ARGS(args) works identically for

   269     non-static class methods and global functions.

   270 

   271     \param args Any number of arguments that can be streamed into a QTextStream, joined together

   272     by the streaming operator <<.

   273     \sa CNT_EXIT

   274 */

   275 

   276 /*!

   277     \def CNT_LOG

   278     \brief A trace macro for class methods or global functions.

   279 

   280     Invoking CNT_LOG outputs a timestamp followed by the scope in which the macro

   281     was invoked and the this pointer value of the instance invoking the

   282     macro.

   283 

   284     CNT_LOG is similar to CNT_ENTRY but it is especially handy for marking calls to methods that

   285     cannot fail, such as an empty constructor, without needing to resort to a separate CNT_EXIT call.

   286 

   287     The following example shows proper usage of the CNT_LOG(args) macro. Assuming a

   288     class has been declared with a static method that is implemented like this:

   289 

   290     \code

   291     #include <QString>

   292     #include <cntdebug.h>

   293 

   294     MyClass::MyClass()

   295     {

   296         CNT_LOG

   297     }

   298     \endcode

   299 

   300     calling new MyClass() generates output lines of the following format:

   301 

   302     \code

   303     2009-03-25 13:20:36.448 : MyClass::MyClass() this 0x6cdab90

   304     \endcode

   305 

   306     \sa CNT_LOG_ARGS

   307 */

   308 

   309 /*!

   310     \def CNT_LOG_ARGS(args)

   311     \brief A generic trace macro with arguments for class methods or global functions.

   312 

   313     The following example shows how to produce arbitrary debug output:

   314 

   315     \code

   316     #include <QString>

   317     #include <cntdebug.h>

   318 

   319     void MyClass::myMethod()

   320     {

   321         CNT_ENTRY

   322 

   323         QString myString("This is a string.");

   324         int myValue = 109;

   325 

   326         CNT_LOG_ARGS("this is a debug message, myString =" << myString << "myValue =" << myValue)

   327 

   328         CNT_EXIT

   329     }

   330     \endcode

   331 

   332     calling myMethod() on an instance of MyClass generates output lines of the following format:

   333 

   334     \code

   335     2009-03-25 13:45:22.083 : void MyClass::myMethod() this 0x6cdab90 entry

   336     2009-03-25 13:45:22.083 : void MyClass::myMethod() this is a debug message, myString = "This is a string." myValue = 109

   337     2009-03-25 13:45:22.083 : void MyClass::myMethod() exit

   338     \endcode

   339 

   340     Any number of arguments may be printed by chaining them together with the streaming operator

   341     <<. Notice that a single space character is automatically added between each streamed

   342     argument, hence the hardcoded strings in the example above, such as "myValue =", do not have

   343     a space at the beginning and end of the string. This automatic space addition is a feature

   344     of qDebug() streaming and cannot be disabled.

   345 

   346     \param args Any number of arguments that can be streamed into a QTextStream, joined together

   347     by the streaming operator <<.

   348 */

   349 

   350 

   351 #ifdef _DEBUG

   352     #define CNT_UNUSED(name)

   353     #define CNT_STATIC_ENTRY qDebug() << __PRETTY_FUNCTION__ << "entry";

   354     #define CNT_STATIC_ENTRY_ARGS(args) qDebug() << __PRETTY_FUNCTION__ << "entry," << args;

   355     #define CNT_ENTRY qDebug() << __PRETTY_FUNCTION__ << "this" << (void *)this << "entry";

   356     #define CNT_ENTRY_ARGS(args) qDebug() << __PRETTY_FUNCTION__ << "this" << (void *)this << "entry," << args;

   357     #define CNT_EXIT qDebug() << __PRETTY_FUNCTION__ << "exit";

   358     #define CNT_EXIT_ARGS(args) qDebug() << __PRETTY_FUNCTION__ << "exit," << args;

   359     #define CNT_LOG qDebug() << __PRETTY_FUNCTION__ << "this" << (void *)this;

   360     #define CNT_LOG_ARGS(args) qDebug() << __PRETTY_FUNCTION__ << args;

   361 #else

   362     #define CNT_UNUSED(name) Q_UNUSED(name)

   363     #define CNT_STATIC_ENTRY

   364     #define CNT_STATIC_ENTRY_ARGS(args)

   365     #define CNT_ENTRY

   366     #define CNT_ENTRY_ARGS(args)

   367     #define CNT_EXIT

   368     #define CNT_EXIT_ARGS(args)

   369     #define CNT_LOG

   370     #define CNT_LOG_ARGS(args)

   371 #endif // _DEBUG

   372 

   373 #endif // CNTDEBUG_H