Core Logging API

Data Structures
struct	LogCategory

Typedefs
typedef struct LogCategory	LogCategory
typedef struct LogDest	LogDest
	Opaque handle to a registered log destination.
typedef void(*	LogDestMsg) (int level, LogCategory *cat, int64 timestamp, strref msg, uint32 batchid, void *userdata)
typedef void(*	LogDestBatchDone) (uint32 batchid, void *userdata)
typedef void(*	LogDestClose) (void *userdata)

Enumerations
enum	LOG_LEVEL_ENUM {   LOG_Fatal , LOG_Error , LOG_Warn , LOG_Notice ,   LOG_Info , LOG_Verbose , LOG_Diag , LOG_Debug ,   LOG_Trace , LOG_Count }

Functions
LogCategory *	logCreateCat (strref name, bool priv)
LogDest *	logRegisterDest (int maxlevel, LogCategory *catfilter, LogDestMsg msgfunc, LogDestBatchDone batchfunc, LogDestClose closefunc, void *userdata)
bool	logUnregisterDest (LogDest *dhandle)
void	logFlush (void)
void	logShutdown (void)
void	logRestart (void)
void	logBatchBegin (void)
void	logBatchEnd (void)

Variables
strref	LogLevelNames []
	Array of log level names as strings (e.g., "Fatal", "Error", etc.)
strref	LogLevelAbbrev []
	Array of single-character log level abbreviations (e.g., "F", "E", etc.)
LogCategory *	LogDefault
	Default log category used when no category is specified.

Detailed Description

The CX logging system provides asynchronous, multi-threaded logging with support for multiple destinations, log levels, categories, and batching. Logging is performed on a dedicated background thread to minimize impact on application performance.

Basic Usage:

logStr(Info, _S"Application started");
logFmt(Warn, _S"Invalid value: ${int}", stvar(int32, value));

Categories: Categories allow filtering logs by subsystem. Create a category once and reuse it:

LogCategory *netcat = logCreateCat(_S"Network", false);
logStrC(Info, netcat, _S"Connection established");

Destinations: Register destinations to control where logs are written. Multiple destinations can be active simultaneously:

// Register a file destination
LogFileData *lfd = logfileCreate(vfs, _S"app.log", &config);
LogDest *dest = logfileRegister(LOG_Info, NULL, lfd);
 
// Later, unregister when done
logUnregisterDest(dest);

Batching: Batch multiple log messages together to ensure they appear consecutively in output:

logBatchBegin();
logStr(Info, _S"Starting operation");
logStr(Info, _S"Step 1 complete");
logStr(Info, _S"Step 2 complete");
logBatchEnd();

Typedef Documentation

LogCategory

typedef struct LogCategory LogCategory

Log category for filtering and organizing log messages

Categories allow grouping related log messages together and filtering them at destinations. Create categories with logCreateCat() and use them with logStrC() and logFmtC() macros.

LogDestBatchDone

typedef void(* LogDestBatchDone) (uint32 batchid, void *userdata)

Callback function type for batch completion notification

Called after all messages in a batch have been delivered to the destination. Destinations can use this to flush buffers or perform cleanup after a batch.

Parameters

batchid	The batch that was completed
userdata	User-provided context pointer from logRegisterDest()

Definition at line 130 of file log.h.

LogDestClose

typedef void(* LogDestClose) (void *userdata)

Callback function type for destination cleanup

Called when a destination is unregistered. The destination should release any resources it holds.

Parameters

userdata

User-provided context pointer from logRegisterDest()

Definition at line 138 of file log.h.

LogDestMsg

typedef void(* LogDestMsg) (int level, LogCategory *cat, int64 timestamp, strref msg, uint32 batchid, void *userdata)

Callback function type for log destinations

This function is called for each log message that passes the destination's level and category filters. Messages with the same batchid should be kept together when possible (e.g., not split across log file rotations).

Parameters

level	Log severity level (LOG_Fatal, LOG_Error, etc.)
cat	Category of the message, or NULL for default
timestamp	Wall clock timestamp when message was logged
msg	The log message text
batchid	Opaque batch identifier for grouping related messages
userdata	User-provided context pointer from logRegisterDest()

Definition at line 120 of file log.h.

Enumeration Type Documentation

LOG_LEVEL_ENUM

enum LOG_LEVEL_ENUM

Log severity levels

Levels are ordered from most to least severe. When registering a destination with a maximum level, all messages at that level and below (more severe) will be delivered.

Enumerator
LOG_Fatal	Fatal errors, application cannot continue.
LOG_Error	Non-fatal errors requiring attention.
LOG_Warn	Warning conditions that may indicate problems.
LOG_Notice	Normal but significant conditions.
LOG_Info	Informational messages.
LOG_Verbose	Detailed informational messages.
LOG_Diag	Release build diagnostics not normally needed.
LOG_Debug	Debug messages (compiled out of non-development builds)
LOG_Trace	Detailed trace messages (only available in debug builds)

Definition at line 56 of file log.h.

Function Documentation

logBatchBegin()

void logBatchBegin

(

void

)

Begin a log batch

Groups subsequent log messages into a batch that will be delivered together. Batches can be nested; only when the outermost batch ends will messages be sent.

logBatchBegin();
logStr(Info, _S"Operation started");
logStr(Info, _S"Step 1 complete");
logStr(Info, _S"Step 2 complete");
logBatchEnd();  // All three messages delivered together

logBatchEnd()

void logBatchEnd

(

void

)

End a log batch

Completes a log batch started with logBatchBegin(). When the outermost batch ends, all batched messages are queued for delivery to destinations.

logCreateCat()

LogCategory * logCreateCat	(	strref	name,
		bool	priv
	)

Create a new log category

Categories are used to organize and filter log messages by subsystem or component. The same category pointer can be passed to multiple log calls.

Parameters

name	Name of the category for display and identification
priv	If true, this is a private category that will be filtered out by default

Returns

Category handle, or NULL if logging system is not initialized

LogCategory *netcat = logCreateCat(_S"Network", false);
logStrC(Info, netcat, _S"Connection established");

logFlush()

void logFlush

(

void

)

Flush all pending log messages

Blocks until all queued log messages have been processed by all destinations. Useful before critical operations or shutdown to ensure logs are written.

logRegisterDest()

LogDest * logRegisterDest	(	int	maxlevel,
		LogCategory *	catfilter,
		LogDestMsg	msgfunc,
		LogDestBatchDone	batchfunc,
		LogDestClose	closefunc,
		void *	userdata
	)

Register a new log destination

Registers callbacks that will receive log messages matching the specified level and category filters. Multiple destinations can be registered simultaneously.

Parameters

maxlevel	Maximum log level to receive (e.g., LOG_Info receives Fatal through Info)
catfilter	Category filter, or NULL to receive all non-private categories
msgfunc	Callback invoked for each log message
batchfunc	Optional callback invoked when a batch completes
closefunc	Optional callback invoked when destination is unregistered
userdata	User context pointer passed to all callbacks

Returns

Destination handle for later unregistration, or NULL on failure

LogDest *dest = logRegisterDest(LOG_Info, NULL, myMsgFunc, NULL, myCloseFunc, &mydata);

logRestart()

void logRestart

(

void

)

Restart the logging system after shutdown

Reinitializes the logging system after a previous logShutdown() call. This allows logging to resume after being explicitly stopped.

logShutdown()

void logShutdown

(

void

)

Shutdown the logging system

Flushes all pending logs, unregisters all destinations, and invalidates all categories. After shutdown, logging calls will be ignored until logRestart() is called.

logUnregisterDest()

bool logUnregisterDest

(

LogDest *

dhandle

)

Unregister a log destination

Removes the destination from the logging system and calls its close callback if provided. The destination handle becomes invalid after this call.

Parameters

dhandle

Destination handle returned from logRegisterDest()

Returns

true if destination was found and removed, false otherwise