PDG_LogUtils.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 PDG_LOG_UTILS_H
#define PDG_LOG_UTILS_H

#include "PDG_API.h"
#include "PDG_WorkItemTypes.h"

#include <PDGT/PDGT_Types.h>

#include <UT/UT_Error.h>
#include <UT/UT_TBBSpinLock.h>
#include <UT/UT_WorkBuffer.h>

class PDG_Node;
class PDG_Scheduler;
class PDG_WorkItem;

class UT_StringHolder;

/*
 * Utility methods for logging debug information
 */
class PDG_API PDG_LogUtils
{
public:
    /**
     * Enumeration of log types
     */
    enum LogType
    {
        /// Cache and handler logging
        eLogTypeCache,

        /// Expression evaluation logging
        eLogTypeExpr,

        /// Node status/debug logging
        eLogTypeNode,

        /// Scheduler status/debug logging
        eLogTypeScheduler,

        /// Service client status/debug logging
        eLogTypeService,

        /// Work item status/debug logging
        eLogTypeWorkItem,

        /// File transer debug logging
        eLogTypeTransfer,

        /// Type registration errors and warnings
        eLogTypeTypeRegistration,

        /// Total number of log types, should always be last
        eLogTypeCount
    };

    /**
     * Enumeration of node debug log levels
     */
    enum NodeDebug
    {
        /// No debug logging
        eNodeDebugNone,

        /// Log node status updates, e.g. generated or cooked
        eNodeDebugStatus,

        /// Log node status + errors
        eNodeDebugError,

        /// Log node status + errors + warnings
        eNodeDebugWarning,

        /// Log node status + errors + warning + callback invocations
        eNodeDebugCallback
    };

    /**
     * Enumeration of scheduler debug log levels
     */
    enum SchedulerDebug
    {
        /// No debug logging
        eSchedulerDebugNone,

        /// Log messages for events that occur at the scheduler level
        eSchedulerDebugScheduler,

        /// Log messages for events that occur at both the scheduler and
        /// work item level
        eSchedulerDebugWorkItem,
    };

    /**
     * Enumeration of service debug log levels
     */
    enum ServiceDebug
    {
        /// No debug logging
        eServiceDebugNone,

        /// Log messages for when a service client is acquired/released
        eServiceDebugClientUsage,

        /// Log messages for when a service client isn't found, in addition
        /// to the above
        eServiceDebugClientDefer,

        /// Log messages for when a service starts up or is shutdown, in
        /// addition to the above
        eServiceDebugStartup,

        /// Logs messages for each time a job is a sent to a service client,
        /// addition to the above
        eServiceDebugJob
    };

    /**
     * Enumeration of work item log levels
     */
    enum WorkItemDebug
    {
        /// No work item logging
        eWorkItemDebugNone,

        /// Work item status updates for scheduled work items
        eWorkItemDebugScheduled,

        /// Work item status updates for all work items
        eWorkItemDebugAll
    };

    /**
     * Enumeration of cache debug log levels
     */
    enum CacheDebug
    {
        /// No cache logging
        eCacheDebugNone,

        /// Log cache misses
        eCacheDebugMiss,

        /// Log cache misses + hits
        eCacheDebugHit,

        /// Log cache misses + hits + cache id changes
        eCacheDebugId,

        /// Log cache misses + hits + cache ids + custom handlers
        eCacheDebugHandler
    };

    /**
     * Enumeration of expression debug log levels
     */
    enum ExpressionDebug
    {
        /// No expression logging
        eExprDebugNone,

        /// Log expressions that are marked as time dependent becaused of 
        /// attribute references
        eExprDebugTime,

        /// Log all attribute reference evaluations
        eExprDebugAttrib,
    };

    /**
     * Emumeration of file trasfer debug log levels
     */
    enum TransferDebug
    {
        /// No file transfer debug logging
        eTransferDebugNone,

        /// Log only failed file transfers
        eTransferDebugFailure,

        /// Log failed and successful file transfers, but skip logging for
        /// transfers that were cached/not performed
        eTransferDebugSuccess,

        /// Log failed, successful, and skipped transfers
        eTransferDebugAll,

        /// Log all transfer outcomes, as well as custom handler results
        eTransferDebugHandler
    };

public:
    /// Returns the current time stamp as a floating point value. This is
    /// different than calling SYStime() because it's adjusted to be relative
    /// to the unix epoch, rather than an aribtrary value that isn't cross
    /// platform. It's also different than just calling time(nullptr) because
    /// it still includes milliseconds like SYStime().
    static fpreal           currentTime();


    /// Returns the current verbosity
    static int              verbosity()
                                { return theLogVerbosity; }

    /// Sets the verbosity
    static void             setVerbosity(int verbosity)
                                {
                                    theLogVerbosity = verbosity;
                                    theLogHasCustomVerbosity = true;
                                }

    /// Sets the log level variables from the environment. If custom log
    /// levels have been set using setLogLevel(..), then this method only
    /// makes change if force=true. Returns true if the log levels were
    /// updated, else false.
    static bool             configureFromEnvironment(bool force);

    /// Enables all logging with the maximum log level for each log type
    static void             enableAll();

    /// Disables all logging across all log types
    static void             disableAll();

    /// Writes a typed logged message to stdout, assuming the log level is
    /// set appropriately
    template <LogType Type, typename Level, typename... Args>
    static void             debugLog(Level level,
                                     const char* fmt,
                                     Args&&... args)
                                {

                                    if (int(level) > theLogLevels[Type])
                                        return;

                                    UT_WorkBuffer log;
                                    log.format(fmt, std::forward<Args>(args)...);

                                    lockedLog(
                                        stdout, log.buffer(), currentTime());
                                }

    /// Returns the log level for the specified log type
    template <typename Level>
    static Level            logLevel(LogType type)
                                {
                                    return static_cast<Level>(
                                        theLogLevels[type]);
                                }

    /// Sets the log level for the specified log type
    template <typename Level>
    static void             setLogLevel(LogType type, Level level)
                                {
                                    theLogLevels[type] = int(level);
                                    theLogHasCustomLevels = true;
                                }

    /// Writes a work item output message to stdout
    static void             workItemLog(
                                WorkItemDebug level,
                                UT_ErrorSeverity severity,
                                const PDG_WorkItem* work_item,
                                const UT_StringHolder& tag,
                                fpreal time_stamp);

    /// Writes a verbose node output message to stdout
    static void             nodeLog(
                                NodeDebug level,
                                const PDG_Node* node,
                                const UT_StringHolder& tag,
                                const UT_StringHolder& message);

    /// Writes a verbose scheduler output message to stdout
    static void             schedulerLog(
                                SchedulerDebug level,
                                const PDG_Scheduler* scheduler,
                                const PDG_WorkItem* work_item,
                                const UT_StringHolder& tag,
                                const UT_StringHolder& message);

    /// Writes a verbose scheduler output message to stdout, including a
    /// work item ID
    static void             schedulerLog(
                                SchedulerDebug level,
                                const PDG_Scheduler* scheduler,
                                PDG_WorkItemID work_item,
                                const UT_StringHolder& tag,
                                const UT_StringHolder& message);

    /// Writes a service log message to stdout
    static void             serviceLog(
                                ServiceDebug level,
                                PDG_WorkItemID work_item_id,
                                const UT_StringHolder& service_name,
                                const UT_StringHolder& client_name,
                                const UT_StringHolder& tag);

    /// Writes a type registration log message to stdout
    static void             typeLog(
                                PDGT_TypeErrorLevel level,
                                const UT_StringHolder& message,
                                const UT_StringHolder& tag);

    /// Writes a generic log message to stdout
    static void             writeLog(
                                const UT_StringHolder& source,
                                const UT_StringHolder& message);

private:
    static void             lockedLog(
                                FILE* file,
                                const char* message,
                                time_t time_stamp);
private:
    friend class pdg_UniversalLogWorkItemStatusSource;

    static const fpreal     theStartTime;
    static const fpreal     theSystemStartTime;

    static int              theLogLevels[eLogTypeCount];
    static int              theLogVerbosity;
    static bool             theLogHasCustomLevels;
    static bool             theLogHasCustomVerbosity;
    static UT_TBBSpinLock   theLogLock;
};

#endif