UT_ErrorLog.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.
 *
 * NAME:        UT_ErrorLog.h (UT Library, C++)
 *
 * COMMENTS:
 */

#ifndef __UT_ErrorLog__
#define __UT_ErrorLog__

#include "UT_API.h"
#include "UT_Function.h"
#include "UT_Lock.h"
#include "UT_String.h"
#include "UT_StringHolder.h"
#include "UT_SymbolTable.h"
#include "UT_WorkBuffer.h"
#include <SYS/SYS_Types.h>

#include <time.h>

class UT_Error;

class UT_API UT_ErrorLog
{
public:
    UT_ErrorLog();
    ~UT_ErrorLog();

    using HeaderCallback = UT_Function<void(UT_WorkBuffer&)>;

    /// Functor to handle errors printed out using the mantra* methods.
    class UT_API ErrorCallback
    {
    public:
        ErrorCallback() {}
        /// The destructor automatically de-registers the callback
        virtual ~ErrorCallback();

        ErrorCallback(const ErrorCallback &) = delete;
        ErrorCallback &operator=(const ErrorCallback &) = delete;

        /// If the method returns @c true, the error will not be printed out
        /// by the built-in error handler.  If it returns @c false, processing
        /// continues in the normal way.
        /// The @c level is the verbosity level of the error.
        /// The built-in process will print out:
        ///     ("%s%s", prefix, message).
        virtual bool    filterError(int verbosity,
                                    const char *message,
                                    const char *prefix) = 0;

        /// This method takes the verbosity *and* the error level.  Sometimes,
        /// programs will print a message with verbosity 1, which is not a
        /// warning.  `error_level` will be 0 (error), 1 (warning), or 2
        /// (message).
        virtual bool    filterMessage(int verbosity, int error_level,
                                const char *message,
                                const char *prefix)
        {
            return filterError(verbosity, message, prefix);
        }
    };
    /// If you want to un-register the callback, just delete the object.
    static void registerCallback(ErrorCallback *err);
    /// Get the universal logging source name for this log source.
    static const UT_StringHolder &universalLogSourceName();

    // Log the error's description to the error file if its severity is greater
    // than or equal to our minimum level
    void                logError(const UT_Error *);

    // We only worry about locking when we set strings; we assume integers
    // and booleans are atomic
    const UT_String    &getLogFileName() const 
                        { return myLogFileName; }
    void                setLogFileName(const UT_String &name) 
                        {
                            myLock.lock(); 
                            myLogFileName.harden(name);
                            myLogFileName.expandVariables();
                            myLock.unlock();
                        }

    int                 getMinLevel() const 
                        { return myMinLevel; }
    void                setMinLevel(const int level)
                        {
                            UT_Lock::Scope lock(myLock);
                            myMinLevel = level;
                            myMinConsoleLevel = level;
                        }
    int                 getMinConsoleLevel() const
                        { return myMinConsoleLevel; }
    void                setMinConsoleLevel(const int level)
                        {
                            UT_Lock::Scope lock(myLock);
                            myMinConsoleLevel = level;
                        }

    bool                getDoLogging() const
                        { return myDoLogging; }
    void                setDoLogging(bool log)
                        {
                            UT_Lock::Scope lock(myLock);
                            myDoLogging = log; }
    bool                getLogToConsole() const
                        { return myLogToConsole; }
    void                setLogToConsole(bool log)
                        {
                            UT_Lock::Scope lock(myLock);
                            myLogToConsole = log;
                        }
    bool                getForceConsoleColor() const
                        { return myForceConsoleColor; }
    void                setForceConsoleColor(bool log)
                        {
                            UT_Lock::Scope lock(myLock);
                            myForceConsoleColor = log; }
    bool                getLogToSystem() const
                        { return myLogToSystem; }
    void                setLogToSystem(bool log)
                        {
                            UT_Lock::Scope lock(myLock);
                            myLogToSystem = log;
                        }
    const UT_StringHolder& getPrefix() const
                        { return myPrefix; }
    void                setPrefix(const UT_StringHolder& prefix)
                        {
                            UT_Lock::Scope lock(myLock);
                            myPrefix = prefix;
                        }
    bool                getAppendDate() const
    {
        return myAppendDate;
    }
    void                setAppendDate(bool append_date)
    {
        UT_Lock::Scope lock(myLock);
        myAppendDate = append_date;
    }

    void                resetState()
                        {
                            myLock.lock(); 
                            myErrorLogTimes.clear();
                            myLock.unlock();
                        }

    void                setMaxLogSize(int64 size)
    {
        UT_Lock::Scope lock(myLock);
        myMaxLogSize = size;
    }
    void                setHeaderCallback(HeaderCallback callback)
    {
        UT_Lock::Scope lock(myLock);
        myHeaderCallback = callback;
    }
    // Callback function to check whether mantra verbosity is enabled for a
    // particular callback level.
    typedef int         (*MantraVerboseCallback)();
    typedef int         (*MantraColorCallback)();
    typedef bool        (*MantraTimestampCallback)();

    // Set the verbosity level for mantra error messages.  For any
    // printouts to occur, it is necessary to first call this method with a
    // non-negative value - otherwise calls to mantraPrintf, mantraWarning,
    // and mantraError will be ignored.  As an alternative, you can provide
    // a callback that will dynamically update the verbosity level.
    static void         setMantraVerboseLevel(int level);
    static int          getMantraVerboseLevel();
    static bool         isMantraVerbose(int level);
    static void         setMantraElapsedTime(bool enable);
    static bool         mantraElapsedTime();

    // This method will also cause errors and warnings to use a "mantra: "
    // prefix.
    static void         setMantraVerboseCallback(MantraVerboseCallback cb);
    static void         setMantraColorCallback(MantraColorCallback cb);
    static void         setMantraTimestampCallback(MantraTimestampCallback cb);

    static int          mantraPrintf(int level, const char *msg, ...)
                            SYS_PRINTF_CHECK_ATTRIBUTE(2,3);
    static int          mantraWarning(const char *msg, ...)
                            SYS_PRINTF_CHECK_ATTRIBUTE(1,2);
    static int          mantraError(const char *msg, ...)
                            SYS_PRINTF_CHECK_ATTRIBUTE(1,2);

    /// @{
    /// Use UTformat to format messages
    template <typename... Args>
    static size_t       format(int lev, const char *fmt, const Args &...args)
    {
        if (!isMantraVerbose(lev))
            return 0;
        UT_WorkBuffer   buf;
        buf.format(fmt, args...);
        return mantraPrintf(lev, "%s", buf.buffer());
    }
    template <typename... Args>
    static size_t       warning(const char *fmt, const Args &...args)
    {
        if (!isMantraVerbose(1))
            return 0;
        UT_WorkBuffer   buf;
        buf.format(fmt, args...);
        return mantraWarning("%s", buf.buffer());
    }
    template <typename... Args>
    static size_t       error(const char *fmt, const Args &...args)
    {
        UT_WorkBuffer   buf;
        buf.format(fmt, args...);
        return mantraError("%s", buf.buffer());
    }

    template <typename... Args>
    static size_t       formatOnce(int lev, const char *fmt,
                                const Args &...args)
    {
        if (!isMantraVerbose(lev))
            return 0;
        UT_WorkBuffer   buf;
        buf.format(fmt, args...);
        return mantraPrintfOnce(lev, "%s", buf.buffer());
    }
    template <typename... Args>
    static size_t       warningOnce(const char *fmt, const Args &...args)
    {
        if (!isMantraVerbose(1))
            return 0;
        UT_WorkBuffer   buf;
        buf.format(fmt, args...);
        return mantraWarningOnce("%s", buf.buffer());
    }
    template <typename... Args>
    static size_t       errorOnce(const char *fmt, const Args &...args)
    {
        UT_WorkBuffer   buf;
        buf.format(fmt, args...);
        return mantraErrorOnce("%s", buf.buffer());
    }
    /// @}

    // Print the error message only if it has not been printed before
    static int          mantraPrintfOnce(int level, const char *msg, ...)
                            SYS_PRINTF_CHECK_ATTRIBUTE(2,3);
    static int          mantraWarningOnce(const char *msg, ...)
                            SYS_PRINTF_CHECK_ATTRIBUTE(1,2);
    static int          mantraErrorOnce(const char *msg, ...)
                            SYS_PRINTF_CHECK_ATTRIBUTE(1,2);

    // Clear tables of messages that have been printed before so that if
    // an error recurs, it will be printed again.
    static void         clearMantraOnceErrors();

    static void printErrorToConsole(const char *msg,
                                    const char *prefix = "",
                                    bool enable_color = false);
    static void printWarningToConsole(const char *msg,
                                      const char *prefix = "",
                                      bool enable_color = false);
    static void printMessageToConsole(const char *msg,
                                      const char *prefix = "",
                                      bool enable_color = false);
protected:

private:
    int                 myMinLevel;
    int                 myMinConsoleLevel;
    UT_String           myLogFileName;
    bool                myDoLogging;
    bool                myLogToConsole;
    bool                myLogToSystem;
    bool                myForceConsoleColor;
    bool                myAppendDate;
    // Set to <= 0 to disable maximum file size. Default is no max size
    int64               myMaxLogSize;
    HeaderCallback      myHeaderCallback;
    UT_StringHolder     myPrefix;
    UT_SymbolMap<time_t> myErrorLogTimes;
    time_t              myLastErrorTime;
    UT_Lock             myLock;
};

UT_API UT_ErrorLog *UTgetErrorLog();

#endif