log.h

Go to the documentation of this file.

#pragma once
 
 
#include <cx/cx.h>
#include <cx/string/strbase.h>
#include <cx/stype/stvar.h>
#include <cx/thread/atomic.h>
 
CX_C_BEGIN
 
enum LOG_LEVEL_ENUM {
    LOG_Fatal,     
    LOG_Error,     
    LOG_Warn,      
    LOG_Notice,    
    LOG_Info,      
    LOG_Verbose,   
    LOG_Diag,      
    LOG_Debug,     
    LOG_Trace,     
 
    LOG_Count      // Not a real level, used for array sizing
};
 
extern strref LogLevelNames[];
 
extern strref LogLevelAbbrev[];
 
#define LOG_Broadcast 0x00000001
 
#define LOG_Restricted 0x00000002
 
#define LOG_Declared 0x00000004
 
typedef struct LogChannel {
    string path;                 
    struct LogChannel* parent;   
    uint32 idx;                  
    uint32 gatedepth;            
    flags_t flags;               
 
    atomic(int32) maxlevel;
 
    atomic(int32) destlevel;
 
    atomic(ptr) ring;
 
    bool ownring;   
 
    atomic(uint32) groupmask;
 
    atomic(uint32) sample;      
    atomic(uint32) samplecnt;   
} LogChannel;
 
typedef struct LogDest LogDest;
 
typedef struct LogSite {
    atomic(uint32) count;   
    atomic(uint32) last;    
} LogSite;
 
enum LOG_SITE_GATE {
    LOG_SiteAlways = 0,   
    LOG_SiteOnce,         
    LOG_SiteEveryN,       
    LOG_SiteEveryT,       
};
 
extern LogChannel* LogDefault;
 
typedef struct LogCtx LogCtx;
 
_Ret_opt_valid_ LogChannel* logChan(_In_ strref path);
 
_Ret_opt_valid_ LogChannel* logDeclareChan(_In_ strref path, flags_t flags);
 
// Drain-owned cache of a record's flat rendering, shared between the destinations of one
// dispatch. Not part of the destination interface; use logRecordRender().
typedef struct LogRenderCache {
    string str;
    bool valid;
} LogRenderCache;
 
typedef struct LogRecord {
    int level;             
    LogChannel* chan;      
    int64 timestamp;       
    uint64 seq;            
    const LogSite* site;   
    strref msgtmpl;        
    const stvar* args;     
    int nargs;             
 
    int trigger;
 
    bool istmpl;
 
    const LogCtx* ctx;   
    uint32 batchid;      
 
    uint32 sample;
 
    strref origin;
 
    uint8 hops;
 
    bool localonly;
 
    LogRenderCache* _cache;   // internal: shared rendering, use logRecordRender()
} LogRecord;
 
void logRecordRender(_Inout_ string* out, _In_ const LogRecord* rec);
 
typedef void (*LogDestMsg)(_In_ const LogRecord* rec, _In_opt_ void* userdata);
 
typedef void (*LogDestBatchDone)(uint32 batchid, _In_opt_ void* userdata);
 
typedef void (*LogDestClose)(_In_opt_ void* userdata);
 
_Ret_opt_valid_ LogDest*
logRegisterDest(int maxlevel, _In_opt_ strref chanfilter, _In_ LogDestMsg msgfunc,
                _In_opt_ LogDestBatchDone batchfunc, _In_opt_ LogDestClose closefunc,
                _In_opt_ void* userdata);
 
bool logDestAddFilter(_In_ LogDest* dhandle, _In_ strref pattern, bool exclude);
 
bool logDestSetFilter(_In_ LogDest* dhandle, _In_opt_ strref pattern);
 
bool logDestSetLevel(_In_ LogDest* dhandle, int maxlevel);
 
typedef bool (*LogChanEnumCB)(_In_ LogChannel* chan, _In_opt_ void* ctx);
 
void logEnumChans(_In_ LogChanEnumCB cb, _In_opt_ void* ctx);
 
bool logUnregisterDest(_Pre_valid_ _Post_invalid_ LogDest* dhandle);
 
void logFlush(void);
 
void logShutdown(void);
 
void logRestart(void);
 
void logBatchBegin(void);
 
void logBatchEnd(void);
 
_meta_inline bool logWouldLog(int level, _In_opt_ LogChannel* chan)
{
    if (!chan)
        chan = LogDefault;
    return level <= atomicLoad(int32, &chan->maxlevel, Relaxed);
}
 
 
 
#define logStr(level, str) _logStr_##level(LOG_##level, LOG_CHANNEL, LOG_SiteAlways, 0, str)
 
#define logStrC(level, chan, str) _logStr_##level(LOG_##level, chan, LOG_SiteAlways, 0, str)
 
#define logFmt(level, fmt, ...) _logFmtArgs(level, LOG_CHANNEL, LOG_SiteAlways, 0, fmt, __VA_ARGS__)
 
#define logFmtC(level, chan, fmt, ...) _logFmtArgs(level, chan, LOG_SiteAlways, 0, fmt, __VA_ARGS__)
 
 
 
#define logStrOnce(level, str) _logStr_##level(LOG_##level, LOG_CHANNEL, LOG_SiteOnce, 0, str)
 
#define logStrEveryN(level, n, str) \
    _logStr_##level(LOG_##level, LOG_CHANNEL, LOG_SiteEveryN, (n), str)
 
#define logStrEveryT(level, interval, str) \
    _logStr_##level(LOG_##level, LOG_CHANNEL, LOG_SiteEveryT, (interval), str)
 
#define logFmtOnce(level, fmt, ...) \
    _logFmtArgs(level, LOG_CHANNEL, LOG_SiteOnce, 0, fmt, __VA_ARGS__)
 
#define logFmtEveryN(level, n, fmt, ...) \
    _logFmtArgs(level, LOG_CHANNEL, LOG_SiteEveryN, (n), fmt, __VA_ARGS__)
 
#define logFmtEveryT(level, interval, fmt, ...) \
    _logFmtArgs(level, LOG_CHANNEL, LOG_SiteEveryT, (interval), fmt, __VA_ARGS__)
 
 
// The channel logStr()/logFmt() use. A source file overrides it with #undef followed by its own
// #define; see the log_macros documentation above.
#define LOG_CHANNEL LogDefault
 
// Internal implementation functions used by macros - do not call directly
void _logStr(int level, int64 timestamp, _In_ LogChannel* chan, _In_opt_ const LogSite* site,
             _In_ strref str);
void _logFmt(int level, int64 timestamp, _In_ LogChannel* chan, _In_opt_ const LogSite* site,
             _In_ strref fmtstr, int n, _In_ stvar* args);
 
// Advances a call site's counters and decides whether it emits this time. Only called for gates
// other than LOG_SiteAlways.
bool _logSiteGate(_Inout_ LogSite* site, int gate, int64 garg);
 
_meta_inline bool _logSitePasses(_Inout_ LogSite* site, int level, _In_ LogChannel* chan, int gate,
                                 int64 garg)
{
    // gate is a constant at every call site, so an ungated call folds this away entirely and
    // costs exactly what it did before sites existed
    if (gate == LOG_SiteAlways)
        return true;
 
    // The level check comes first deliberately: a gate consumed while nothing is listening would
    // spend logStrOnce()'s single emission on a message that goes nowhere.
    return logWouldLog(level, chan) && _logSiteGate(site, gate, garg);
}
 
// Opens the block that holds the call site's LogSite. The static is declared here, inside each
// level's own macro, rather than by the outer macro, so that a level compiled out by DEBUG_LEVEL
// costs no storage either. The channel is bound to a local because the gated forms would
// otherwise evaluate the expression twice.
#define _logStrSite(level, chan, gate, garg, str)                          \
    do {                                                                   \
        static LogSite _log_site;                                          \
        LogChannel* _log_site_chan = (chan);                               \
        if (_logSitePasses(&_log_site, level, _log_site_chan, gate, garg)) \
            _logStr(level, -1, _log_site_chan, &_log_site, str);           \
    } while (0)
 
#define _logFmtSite(level, chan, gate, garg, fmt, nargs, args)                \
    do {                                                                      \
        static LogSite _log_site;                                             \
        LogChannel* _log_site_chan = (chan);                                  \
        if (_logSitePasses(&_log_site, level, _log_site_chan, gate, garg))    \
            _logFmt(level, -1, _log_site_chan, &_log_site, fmt, nargs, args); \
    } while (0)
 
// Collapses a variadic argument list before handing off to the per-level table, so that the
// table itself stays non-variadic and every user-facing logFmt variant is one line.
//
// count_macro_args() reports 1 for an empty list and there is no portable way to do better, so
// every logFmt() needs at least one argument; a template that substitutes only context fields
// passes stvNone. Expanding __VA_ARGS__ a second time to count it exactly is not an option --
// format.h records what that costs on MSVC.
#define _logFmtArgs(level, chan, gate, garg, fmt, ...) \
    _logFmt_##level(LOG_##level,                       \
                    chan,                              \
                    gate,                              \
                    garg,                              \
                    fmt,                               \
                    count_macro_args(__VA_ARGS__),     \
                    ((stvar[]) { __VA_ARGS__ }))
 
// Implementation macros for conditional compilation based on DEBUG_LEVEL. The disabled forms are
// variadic so that they cannot fall out of step with the enabled ones' arity; a level compiled
// out never expands its arguments at all, which is what keeps a Trace call site and everything
// it computes out of a release binary.
#if DEBUG_LEVEL >= 2
#define _logStr_Trace _logStrSite
#define _logFmt_Trace _logFmtSite
#else
#define _logStr_Trace(...) ((void)0)
#define _logFmt_Trace(...) ((void)0)
#endif
 
#if DEBUG_LEVEL >= 1
#define _logStr_Debug                                 _logStrSite
#define _logFmt_Debug                                 _logFmtSite
#define _logStr_DevDiag(level, chan, gate, garg, str) _logStrSite(LOG_Diag, chan, gate, garg, str)
#define _logFmt_DevDiag(level, chan, gate, garg, fmt, nargs, args) \
    _logFmtSite(LOG_Diag, chan, gate, garg, fmt, nargs, args)
#define _logStr_DevVerbose(level, chan, gate, garg, str) \
    _logStrSite(LOG_Verbose, chan, gate, garg, str)
#define _logFmt_DevVerbose(level, chan, gate, garg, fmt, nargs, args) \
    _logFmtSite(LOG_Verbose, chan, gate, garg, fmt, nargs, args)
#define _logStr_DevInfo(level, chan, gate, garg, str) _logStrSite(LOG_Info, chan, gate, garg, str)
#define _logFmt_DevInfo(level, chan, gate, garg, fmt, nargs, args) \
    _logFmtSite(LOG_Info, chan, gate, garg, fmt, nargs, args)
#define _logStr_DevNotice(level, chan, gate, garg, str) \
    _logStrSite(LOG_Notice, chan, gate, garg, str)
#define _logFmt_DevNotice(level, chan, gate, garg, fmt, nargs, args) \
    _logFmtSite(LOG_Notice, chan, gate, garg, fmt, nargs, args)
#define _logStr_DevWarn(level, chan, gate, garg, str) _logStrSite(LOG_Warn, chan, gate, garg, str)
#define _logFmt_DevWarn(level, chan, gate, garg, fmt, nargs, args) \
    _logFmtSite(LOG_Warn, chan, gate, garg, fmt, nargs, args)
#define _logStr_DevError(level, chan, gate, garg, str) _logStrSite(LOG_Error, chan, gate, garg, str)
#define _logFmt_DevError(level, chan, gate, garg, fmt, nargs, args) \
    _logFmtSite(LOG_Error, chan, gate, garg, fmt, nargs, args)
#else
#define _logStr_Debug(...)      ((void)0)
#define _logFmt_Debug(...)      ((void)0)
#define _logStr_DevDiag(...)    ((void)0)
#define _logFmt_DevDiag(...)    ((void)0)
#define _logStr_DevVerbose(...) ((void)0)
#define _logFmt_DevVerbose(...) ((void)0)
#define _logStr_DevInfo(...)    ((void)0)
#define _logFmt_DevInfo(...)    ((void)0)
#define _logStr_DevNotice(...)  ((void)0)
#define _logFmt_DevNotice(...)  ((void)0)
#define _logStr_DevWarn(...)    ((void)0)
#define _logFmt_DevWarn(...)    ((void)0)
#define _logStr_DevError(...)   ((void)0)
#define _logFmt_DevError(...)   ((void)0)
#endif
 
#define _logStr_Diag    _logStrSite
#define _logFmt_Diag    _logFmtSite
#define _logStr_Verbose _logStrSite
#define _logFmt_Verbose _logFmtSite
#define _logStr_Info    _logStrSite
#define _logFmt_Info    _logFmtSite
#define _logStr_Notice  _logStrSite
#define _logFmt_Notice  _logFmtSite
#define _logStr_Warn    _logStrSite
#define _logFmt_Warn    _logFmtSite
#define _logStr_Error   _logStrSite
#define _logFmt_Error   _logFmtSite
#define _logStr_Fatal   _logStrSite
#define _logFmt_Fatal   _logFmtSite
 
CX_C_END