PDGE_DebugUtils.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * COMMENTS:
 */

#ifndef __PDGE_DEBUG_UTILS_H__
#define __PDGE_DEBUG_UTILS_H__

/**
 * The following defines can be used to enable debugging utilities:
 *
 *  PDGE_DEBUG_ENABLE_LOGGING will enable a thread-specific that is collected
 *  and dumped to stdout when evaluation completes
 *
 *  PDGE_DEBUG_ENABLE_DOT will enable a DOT graph print out at the end of
 *  evaluation. This graph become prohibitively complicated for large
 *  dependency graphs and the DOT layout engine may struggle to correctly
 *  display it.
 *
 *  PDGE_DEBUG_ENABLE_NAMES enables storage of string name identifiers on
 *  each dependency object. This is typically also enabled when enabling either
 *  PDGE_DEBUG_ENABLE_LOGGING or PDGE_DEBUG_ENABLE_DOT, otherwise the output 
 *  of those is of limited use.
 *
 *  PDGE_DEBUG_DELAY adds a delay to dependency resolution, putting the
 *  evaluator into "slow motion" to make it easier to observe execution
 *  order.
 */

//#define PDGE_DEBUG_ENABLE_LOGGING 1
//#define PDGE_DEBUG_ENABLE_DOT 1
//#define PDGE_DEBUG_ENABLE_NAMES 1
//#define PDGE_DEBUG_ENABLE_IDS 1
//#define PDGE_DEBUG_DELAY 500

#include <UT/UT_Array.h>
#include <UT/UT_ArrayMap.h>
#include <UT/UT_ArraySet.h>
#include <UT/UT_ConcurrentVector.h>
#include <UT/UT_ThreadSpecificValue.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_SysClone.h>
#include <UT/UT_WorkBuffer.h>

#include <SYS/SYS_AtomicInt.h>

class PDGE_Dependency;
class PDGE_DependencyOwner;

/*
 * Utility functions to debuging dependency graph evaluations. The
 * functionality in this file is completely disabled when the PDGE_DEBUG
 * defines are commented out.
 *
 * It currently offers three utilities to assist in debugging dependency
 * graph evaluation:
 *
 * - A mechanism for adding an artificial delay to evaluation, to make it
 *   easier to observe evaluation sequencing.
 * - A threaded log, which keeps messages in thread specific queues. The
 *   messages can be dumped after evaluation completes, including a thread
 *   id prefix on each message to track evaluation order.
 * - A method for dumping a graph to the DOT format.
 *
 * Additionally, the PDGE_DEBUG_ENABLE_NAMES flag can be enabled so that
 * all PDGE_Dependency objects store a string name for easier identification.
 * When that flag is off, the code for storing the name is not built.
 */
class PDGE_DebugUtils
{
public:
    /// Appends a message to a thread-safe log. Each thread stores its own
    /// list of messages along with a unique id for each message. This 
    /// method expects a format string and variadic arg list, which are
    /// handled using UT_Format.
    template <typename... Args>
    inline static void      appendLog(const char* fmt, Args&&... args)
                                {
                                #ifdef PDGE_DEBUG_ENABLE_LOGGING
                                    UT_WorkBuffer buffer;
                                    buffer.format(fmt,
                                        std::forward<Args>(args)...);

                                    int id = SYSgetSTID();
                                    auto&& log = myLog.getValueForThread(id);
                                    log.append({buffer.buffer(),
                                        myLogCounter.add(1), id});
                                #endif
                                }

    /// Adds a dependency to the tracking list. This method should be used
    /// to inform the debug utils about depdendcies involved during
    /// evaluation for the purpose of dumping a DOT graph.
    inline static void      addDependency(PDGE_Dependency* dependency)
                                {
                                #ifdef PDGE_DEBUG_ENABLE_DOT
                                    myDependencies.push_back(dependency);
                                #endif
                                }

    /// Artificially delays dependency evaluation if the PDGE_DEBUG_DELAY
    /// value is defined. The value is the number of milliseconds to spend
    /// waiting for evaluations.
    inline static void      artificialDelay()
                                {
                                #ifdef PDGE_DEBUG_DELAY
                                    UTnap(PDGE_DEBUG_DELAY);
                                #endif
                                }

    /// Returns a unique if for a dependency, if PDGE_DEBUG_ENABLE_IDS is on.
    /// This is useful for DOT graph output as it can be used to reduce the
    /// label size.
    inline static int       uniqueId()
                                {
                                #ifdef PDGE_DEBUG_ENABLE_IDS
                                    return myIdCounter.add(1);
                                #else
                                    return 0;
                                #endif
                                }
                        

    /// Dumps the contents of the log to stdout. Messages are sorted by their
    /// unique ID and printed along with the thread ID from which they were
    /// initially reported. When PDGE_DEBUG_ENABLE_LOGGING is not enabled
    /// this method does nothing.
    static void             dumpLog();

    /// Dumps the recorded dependencies as a DOT graph to the specified
    /// buffer. PDGE_DEBUG_ENABLE_NAMES should be enabled so that the DOT
    /// graph has useful labels. When PDGE_DEBUG_ENABLE_DOT is not enabled
    /// this method does nothing.
    static void             dumpDOT(UT_WorkBuffer& buffer);

private:
    struct Message
    {
        UT_StringHolder     myMessage;
        int                 myIndex;
        int                 myId;

        static bool         sort(const Message& a, const Message& b)
                                { return (a.myIndex < b.myIndex); }
    };

    using DepList       = UT_ConcurrentVector<PDGE_Dependency*>;
    using EdgeMap       = UT_ArrayMap<PDGE_Dependency*,
                                      UT_ArraySet<PDGE_Dependency*>>;
    using LogArray      = UT_Array<Message>;
    using ThreadedLog   = UT_ThreadSpecificValue<LogArray>;


private:
    static void             dumpDOT(UT_WorkBuffer& buffer,
                                    PDGE_Dependency* dependency,
                                    EdgeMap& exclusion_map);

private:

#ifdef PDGE_DEBUG_ENABLE_DOT
    static DepList          myDependencies;
#endif

#ifdef PDGE_DEBUG_ENABLE_LOGGING
    static ThreadedLog      myLog;
    static SYS_AtomicInt32  myLogCounter;
#endif

#ifdef PDGE_DEBUG_ENABLE_IDS
    static SYS_AtomicInt32  myIdCounter;
#endif
};

#endif