/*

* 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