--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/mptrace.h Tue Aug 31 15:12:29 2010 +0300
@@ -0,0 +1,373 @@
+/*
+* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Trace macro declarations.
+*
+*/
+
+
+#ifndef MPTX_H
+#define MPTX_H
+
+#include <QDebug> // QDebug
+#include <QtGlobal> // qDebug()
+
+/*!
+ \def TX_UNUSED(name)
+ \brief Declares a single variable as unused when tracing is disabled.
+
+ TX_UNUSED allows variables (usually method parameters) to be declared as used only if
+ tracing is enabled. Without this variables that are included in trace macros, but not otherwise
+ used, would cause unused variable warnings on compilation. If tracing is enabled, TX_UNUSED
+ has no effect.
+
+ Consider the following class method where the parameter number is not used at all, except for
+ tracing its value on entry:
+
+ \code
+ #include <mptrace.h>
+
+ void MyClass::myMethod(int number)
+ {
+ TX_UNUSED(number)
+ TX_ENTRY("number =" << number)
+
+ // ...some more code where the parameter number is not used.
+
+ TX_EXIT
+ }
+ \endcode
+
+ Compiling this method with tracing completely disabled at compile time would cause an unused
+ variable warning to be issued unless the TX_UNUSED macro is used to declare the variable as
+ trace-only.
+
+ \param name The name of the variable to declare as unused if tracing is disabled. To mark
+ several variables as trace-only, add a separate TX_UNUSED statement for each.
+ \sa TX_STATIC_ENTRY_ARGS(args), TX_ENTRY_ARGS(args).
+*/
+
+/*!
+ \def TX_STATIC_ENTRY
+ \brief A method entry trace macro for static class methods or global functions.
+
+ Invoking TX_STATIC_ENTRY outputs a timestamp followed by the scope in which the macro
+ was invoked and the word "entry".
+
+ TX_STATIC_ENTRY is intended to be used as the first line of static class methods or
+ global functions. There is a corresponding exit macro, TX_EXIT.
+
+ The following example shows proper usage of the TX_STATIC_ENTRY macro. Assuming a class
+ has been declared with a static method that is implemented like this:
+
+ \code
+ #include <mptrace.h>
+
+ void MyClass::myStaticMethod()
+ {
+ TX_STATIC_ENTRY
+
+ int i = 1;
+ i++;
+
+ TX_EXIT
+ }
+ \endcode
+
+ calling MyClass::myStaticMethod() generates output lines of the following format:
+
+ \code
+ 2009-03-25 11:00:50.171 : static void MyClass::myStaticMethod() entry
+ 2009-03-25 11:00:50.171 : static void MyClass::myStaticMethod() exit
+ \endcode
+
+ \sa TX_STATIC_ENTRY_ARGS(args), TX_EXIT.
+*/
+
+/*!
+ \def TX_STATIC_ENTRY_ARGS(args)
+ \brief A method entry trace macro with arguments for static class methods or global functions.
+
+ TX_STATIC_ENTRY_ARGS(args) is similar to TX_STATIC_ENTRY but it allows arguments to be
+ output on the same line without needing to resort to a separate TX_LOG_ARGS call. This is
+ especially handy for outputting the parameters of the method call.
+
+ The following example shows proper usage of the TX_STATIC_ENTRY_ARGS(args) macro. Assuming
+ a class has been declared with a static method that is implemented like this:
+
+ \code
+ #include <QString>
+ #include <mptrace.h>
+
+ void MyClass::myStaticMethod(const QString &text, int number)
+ {
+ TX_STATIC_ENTRY_ARGS("text =" << text << "number =" << number);
+
+ int i = 1;
+ i++;
+
+ TX_EXIT
+ }
+ \endcode
+
+ calling MyClass::myStaticMethod(QString("foo"), 74) generates output lines of the following
+ format:
+
+ \code
+ 2009-03-25 11:00:50.171 : static void MyClass::myStaticMethod(const QString&, int) entry, text = "foo" number = 74
+ 2009-03-25 11:00:50.171 : static void MyClass::myStaticMethod(const QString&, int) exit
+ \endcode
+
+ \param args Any number of arguments that can be streamed into a QTextStream, joined together
+ by the streaming operator <<.
+ \sa TX_STATIC_ENTRY.
+*/
+
+/*!
+ \def TX_ENTRY
+ \brief A method entry trace macro for class methods.
+
+ Invoking TX_ENTRY outputs a timestamp followed by the scope in which the macro
+ was invoked, the word "entry" and the this pointer value of the instance invoking the
+ macro.
+
+ The this pointer value included in the debug output can help make the output more readable, as
+ it allows different instances of the same class to be distinguished from each other.
+
+ TX_ENTRY is intended to be used as the first line of class methods. There is a corresponding
+ exit macro, TX_EXIT.
+
+ The following example shows proper usage of the TX_ENTRY macro. Assuming a class has been
+ declared with a non-static method that is implemented like this:
+
+ \code
+ #include <mptrace.h>
+
+ void MyClass::myMethod()
+ {
+ TX_ENTRY
+
+ int i = 1;
+ i++;
+
+ TX_EXIT
+ }
+ \endcode
+
+ calling myMethod() on an instance of MyClass generates output lines of the following format:
+
+ \code
+ 2009-03-25 11:00:50.171 : void MyClass::myMethod() this 0x6cdab90 entry
+ 2009-03-25 11:00:50.171 : void MyClass::myMethod() exit
+ \endcode
+
+ \sa TX_ENTRY_ARGS(args), TX_EXIT.
+*/
+
+/*!
+ \def TX_ENTRY_ARGS(args)
+ \brief A method entry trace macro with arguments for class methods.
+
+ TX_ENTRY_ARGS(args) is similar to TX_ENTRY but it allows arguments to be output on the
+ same line without needing to resort to a separate TX_LOG_ARGS call. This is especially
+ handy for outputting the parameters of the method call.
+
+ The following example shows proper usage of the TX_ENTRY_ARGS(args)) macro. Assuming a
+ class has been declared with a non-static method that is implemented like this:
+
+ \code
+ #include <QString>
+ #include <mptrace.h>
+
+ void MyClass::myMethod(const QString &text, int number)
+ {
+ TX_ENTRY_ARGS("text =" << text << "number =" << number);
+
+ int i = 1;
+ i++;
+
+ TX_EXIT
+ }
+ \endcode
+
+ calling myMethod(QString("foo"), 74) on an instance of MyClass generates output lines of the
+ following format:
+
+ \code
+ 2009-03-25 11:00:50.171 : void MyClass::myMethod(const QString&, int) this 0x6cdab90 entry, text = "foo" number = 74
+ 2009-03-25 11:00:50.171 : void MyClass::myMethod(const QString&, int) exit
+ \endcode
+
+ \param args Any number of arguments that can be streamed into a QTextStream, joined together
+ by the streaming operator <<.
+ \sa TX_ENTRY, TX_EXIT.
+*/
+
+/*!
+ \def TX_EXIT
+ \brief A method exit trace macro for class methods or global functions.
+
+ Invoking TX_EXIT outputs a timestamp followed by the scope in which the macro
+ was invoked and the word "exit".
+
+ TX_EXIT is intended to be used as the last line of class methods and global functions,
+ just before the return statement, if any. There are two corresponding entry macros,
+ TX_ENTRY and TX_STATIC_ENTRY, depending on whether the method being traced is a
+ non-static or a static class method. TX_EXIT makes no distinction between these two types
+ of methods and is to be used for both.
+
+ See TX_ENTRY or TX_STATIC_ENTRY for an example of how to use TX_EXIT.
+
+ \sa TX_EXIT_ARGS(args), TX_ENTRY, TX_STATIC_ENTRY.
+*/
+
+/*!
+ \def TX_EXIT_ARGS(args)
+ \brief A method exit trace macro with arguments for class methods or global functions.
+
+ TX_EXIT_ARGS(args) is similar to TX_EXIT but it allows arguments to be output on the
+ same line without needing to resort to a separate TX_LOG_ARGS call. This is especially
+ handy for outputting the return value of the method call.
+
+ The following example shows proper usage of the TX_EXIT_ARGS(args) macro. Assuming a
+ class has been declared with a static method that is implemented like this:
+
+ \code
+ #include <QString>
+ #include <mptrace.h>
+
+ int MyClass::myStaticMethod(const QString &text)
+ {
+ TX_STATIC_ENTRY_ARGS("text =" << text);
+
+ int length = text.length();
+
+ TX_EXIT_ARGS("length" << length);
+
+ return length;
+ }
+ \endcode
+
+ calling MyClass::myStaticMethod(QString("foo")) generates output lines of the following format:
+
+ \code
+ 2009-03-25 13:20:36.448 : static int MyClass::myStaticMethod(const QString&) entry, text = "foo"
+ 2009-03-25 13:20:36.448 : static int MyClass::myStaticMethod(const QString&) exit, length 3
+ \endcode
+
+ Although the example above is a static method, TX_EXIT_ARGS(args) works identically for
+ non-static class methods and global functions.
+
+ \param args Any number of arguments that can be streamed into a QTextStream, joined together
+ by the streaming operator <<.
+ \sa TX_EXIT
+*/
+
+/*!
+ \def TX_LOG
+ \brief A trace macro for class methods or global functions.
+
+ Invoking TX_LOG outputs a timestamp followed by the scope in which the macro
+ was invoked and the this pointer value of the instance invoking the
+ macro.
+
+ TX_LOG is similar to TX_ENTRY but it is especially handy for marking calls to methods that
+ cannot fail, such as an empty constructor, without needing to resort to a separate TX_EXIT call.
+
+ The following example shows proper usage of the TX_LOG(args) macro. Assuming a
+ class has been declared with a static method that is implemented like this:
+
+ \code
+ #include <QString>
+ #include <mptrace.h>
+
+ MyClass::MyClass()
+ {
+ TX_LOG
+ }
+ \endcode
+
+ calling new MyClass() generates output lines of the following format:
+
+ \code
+ 2009-03-25 13:20:36.448 : MyClass::MyClass() this 0x6cdab90
+ \endcode
+
+ \sa TX_LOG_ARGS
+*/
+
+/*!
+ \def TX_LOG_ARGS(args)
+ \brief A generic trace macro with arguments for class methods or global functions.
+
+ The following example shows how to produce arbitrary debug output:
+
+ \code
+ #include <QString>
+ #include <mptrace.h>
+
+ void MyClass::myMethod()
+ {
+ TX_ENTRY
+
+ QString myString("This is a string.");
+ int myValue = 109;
+
+ TX_LOG_ARGS("this is a debug message, myString =" << myString << "myValue =" << myValue)
+
+ TX_EXIT
+ }
+ \endcode
+
+ calling myMethod() on an instance of MyClass generates output lines of the following format:
+
+ \code
+ 2009-03-25 13:45:22.083 : void MyClass::myMethod() this 0x6cdab90 entry
+ 2009-03-25 13:45:22.083 : void MyClass::myMethod() this is a debug message, myString = "This is a string." myValue = 109
+ 2009-03-25 13:45:22.083 : void MyClass::myMethod() exit
+ \endcode
+
+ Any number of arguments may be printed by chaining them together with the streaming operator
+ <<. Notice that a single space character is automatically added between each streamed
+ argument, hence the hardcoded strings in the example above, such as "myValue =", do not have
+ a space at the beginning and end of the string. This automatic space addition is a feature
+ of qDebug() streaming and cannot be disabled.
+
+ \param args Any number of arguments that can be streamed into a QTextStream, joined together
+ by the streaming operator <<.
+*/
+
+
+#ifdef _DEBUG
+ #define TX_UNUSED(name)
+ #define TX_STATIC_ENTRY qDebug() << __PRETTY_FUNCTION__ << "entry";
+ #define TX_STATIC_ENTRY_ARGS(args) qDebug() << __PRETTY_FUNCTION__ << "entry," << args;
+ #define TX_ENTRY qDebug() << __PRETTY_FUNCTION__ << "this" << (void *)this << "entry";
+ #define TX_ENTRY_ARGS(args) qDebug() << __PRETTY_FUNCTION__ << "this" << (void *)this << "entry," << args;
+ #define TX_EXIT qDebug() << __PRETTY_FUNCTION__ << "exit";
+ #define TX_EXIT_ARGS(args) qDebug() << __PRETTY_FUNCTION__ << "exit," << args;
+ #define TX_LOG qDebug() << __PRETTY_FUNCTION__ << "this" << (void *)this;
+ #define TX_LOG_ARGS(args) qDebug() << __PRETTY_FUNCTION__ << args;
+#else
+ #define TX_UNUSED(name) Q_UNUSED(name)
+ #define TX_STATIC_ENTRY
+ #define TX_STATIC_ENTRY_ARGS(args)
+ #define TX_ENTRY
+ #define TX_ENTRY_ARGS(args)
+ #define TX_EXIT
+ #define TX_EXIT_ARGS(args)
+ #define TX_LOG
+ #define TX_LOG_ARGS(args)
+#endif // _DEBUG
+
+#endif // MPTX_H