Deferred Logging

Typedefs
typedef struct LogDeferData	LogDeferData
	Opaque handle for deferred log buffer.

Functions
LogDeferData *	logDeferCreate (void)
LogDest *	logDeferRegister (int level, LogCategory *catfilter, LogDeferData *deferdata)
void	logDeferDest (int level, LogCategory *cat, int64 timestamp, strref msg, uint32 batchid, void *userdata)
LogDest *	logRegisterDestWithDefer (int maxlevel, LogCategory *catfilter, LogDestMsg msgfunc, LogDestBatchDone batchfunc, LogDestClose closefunc, void *userdata, LogDest *deferdest)

Detailed Description

Deferred logging captures log messages in a temporary buffer during application startup, then transfers them to a real destination once it becomes available. This ensures no logs are lost during initialization before file systems or other resources are ready.

Messages are stored in memory with full timestamps and batch information, then replayed to the final destination atomically when it's registered. The defer buffer is destroyed during the transfer.

Basic Usage:

// Very early in startup - before file system is ready
LogDeferData *deferdata = logDeferCreate();
LogDest *deferdest = logDeferRegister(LOG_Info, NULL, deferdata);
 
// Application can log immediately
logStr(Info, _S"Starting initialization...");
logStr(Info, _S"Loading configuration...");
 
// Later - file system is ready, transfer deferred logs
LogFileData *lfd = logfileCreate(vfs, _S"app.log", &cfg);
LogDest *dest = logfileRegisterWithDefer(LOG_Info, NULL, lfd, deferdest);
 
// All early logs now written to file, logging continues normally
logStr(Info, _S"Initialization complete");

Function Documentation

logDeferCreate()

LogDeferData * logDeferCreate

(

void

)

Create a deferred logging buffer

Allocates a temporary buffer for storing log messages that will be transferred to a real destination later. The buffer grows dynamically to accommodate all deferred messages.

Returns

Deferred logging handle, or NULL on allocation failure

LogDeferData *deferdata = logDeferCreate();

logDeferDest()

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

Log message callback for deferred destinations

Stores a log message in the defer buffer for later replay. Messages are stored with their original timestamps and batch IDs preserved.

Parameters

level	Log severity level
cat	Category, or NULL for default
timestamp	Wall clock timestamp
msg	Log message text
batchid	Batch identifier for grouping
userdata	LogDeferData pointer from logDeferCreate()

logDeferRegister()

LogDest * logDeferRegister	(	int	level,
		LogCategory *	catfilter,
		LogDeferData *	deferdata
	)

Register a deferred logging destination

Registers a destination that buffers log messages in memory. Messages are held until the defer destination is transferred to a real destination using logfileRegisterWithDefer(), logmembufRegisterWithDefer(), or logRegisterDestWithDefer().

Parameters

level	Maximum log level to capture
catfilter	Category filter, or NULL for all non-private categories
deferdata	Deferred buffer handle from logDeferCreate()

Returns

Destination handle for later transfer, or NULL on failure

LogDeferData *deferdata = logDeferCreate();
LogDest *deferdest = logDeferRegister(LOG_Info, NULL, deferdata);

logRegisterDestWithDefer()

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

Register a destination and transfer deferred logs atomically

Registers a new destination with custom callbacks while simultaneously flushing all deferred logs to it. The defer destination is unregistered and its buffer destroyed during this process. All deferred messages are replayed in order with their original timestamps and batch information.

This is a low-level function; prefer using destination-specific wrappers like logfileRegisterWithDefer() or logmembufRegisterWithDefer().

Parameters

maxlevel	Maximum log level for new destination
catfilter	Category filter for new destination, or NULL for all non-private categories
msgfunc	Message callback for new destination
batchfunc	Optional batch completion callback for new destination
closefunc	Optional cleanup callback for new destination
userdata	User context for new destination callbacks
deferdest	Deferred destination to transfer and destroy (becomes invalid)

Returns

New destination handle, or NULL on failure

// Custom destination with deferred log transfer
LogDest *dest = logRegisterDestWithDefer(
    LOG_Info, NULL,
    myMsgFunc, myBatchFunc, myCloseFunc, &mydata,
    deferdest
);