Logging Subsystem

Classes
struct	BaseLogEvent
	A structured event containing all metadata for a single log message. More...

Typedefs
typedef enum BaseLogLevel	BaseLogLevel
	The severity level of a log message.
typedef struct BaseLogEvent	BaseLogEvent
	A structured event containing all metadata for a single log message.
typedef void(*	BaseLogFn) (BaseLogEvent *ev, void *user_data)
	Signature for custom logging destination callbacks.
typedef void(*	BaseLogLockFn) (void *user_data, b32 lock)
	Signature for the thread-synchronization callback.

Enumerations
enum	BaseLogLevel {   BASE_LOG_LEVEL_TRACE , BASE_LOG_LEVEL_DEBUG , BASE_LOG_LEVEL_INFO , BASE_LOG_LEVEL_WARN ,   BASE_LOG_LEVEL_ERROR , BASE_LOG_LEVEL_FATAL , BASE_LOG_LEVEL_COUNT }
	The severity level of a log message. More...

Functions
void	base_log_set_level (BaseLogLevel level)
	Configures the active logging level. Messages below this level are ignored.
void	base_log_set_quiet (b32 enable)
	Mutes or unmutes all console (stdout/stderr) output.
void	base_log_set_lock (BaseLogLockFn fn, void *user_data)
	Configures thread-safety by providing a custom locking mechanism.
b32	base_log_add_fp (FILE *fp, BaseLogLevel min_level)
	Adds a standard C FILE* pointer as a logging destination.
b32	base_log_add_callback (BaseLogFn fn, void *user_data, BaseLogLevel min_level)
	Adds a custom callback function as a logging destination.
b32	base_log_remove_callback (BaseLogFn fn)
	Removes a previously registered callback from the logger.
void	base_log_message (BaseLogLevel level, const char *file, int line, const char *fmt,...)
	Internal function that actually processes the log. DO NOT call directly.

Detailed Description

Typedef Documentation

BaseLogFn

typedef void(* BaseLogFn) (BaseLogEvent *ev, void *user_data)

Signature for custom logging destination callbacks.

Definition at line 89 of file base_log.h.

BaseLogLockFn

typedef void(* BaseLogLockFn) (void *user_data, b32 lock)

Signature for the thread-synchronization callback.

Definition at line 92 of file base_log.h.

Enumeration Type Documentation

BaseLogLevel

enum BaseLogLevel

The severity level of a log message.

Enumerator
BASE_LOG_LEVEL_TRACE	Fine-grained, step-by-step debug information.
BASE_LOG_LEVEL_DEBUG	Diagnostic information useful for developers.
BASE_LOG_LEVEL_INFO	General application flow events.
BASE_LOG_LEVEL_WARN	Abnormal but non-fatal events.
BASE_LOG_LEVEL_ERROR	Recoverable errors that impact a specific operation.
BASE_LOG_LEVEL_FATAL	Critical errors causing an application crash or shutdown.

Definition at line 69 of file base_log.h.

Function Documentation

base_log_add_callback()

b32 base_log_add_callback	(	BaseLogFn	fn,
		void *	user_data,
		BaseLogLevel	min_level )

Adds a custom callback function as a logging destination.

The callback receives a BaseLogEvent with the format string and va_list. Use vsnprintf(buf, sizeof(buf), ev->fmt, ev->ap) to format the message. Up to 4 callbacks can be registered simultaneously.

Example:

void my_callback(BaseLogEvent *ev, void *user_data) {
    char buf[256];
    vsnprintf(buf, sizeof(buf), ev->fmt, ev->ap);
    send_to_telemetry(ev->level, buf);
}
 
base_log_add_callback(my_callback, NULL, BASE_LOG_LEVEL_WARN);

Parameters

fn	The function pointer to invoke for every matching event.
user_data	Opaque pointer passed to the callback.
min_level	The minimum severity level to send to this callback.

Returns

1 on success, 0 if no callback slot is available.

Definition at line 178 of file base_log.c.

Here is the caller graph for this function:

base_log_add_fp()

b32 base_log_add_fp	(	FILE *	fp,
		BaseLogLevel	min_level )

Adds a standard C FILE* pointer as a logging destination.

Log entries written to files include a full timestamp (YYYY-MM-DD HH:MM:SS) and no ANSI color codes. The file is flushed after every write.

Example:

FILE *f = fopen("errors.log", "a");
base_log_add_fp(f, BASE_LOG_LEVEL_ERROR); // only ERROR and FATAL
 
LOG_INFO("Not written to file");
LOG_ERROR("Written to file and console");
 
// Always remove before closing:
base_log_remove_callback(NULL); // TODO: expose file_callback symbol
fclose(f);

Parameters

fp	The file pointer (must be opened in "a" or "w" mode).
min_level	The minimum severity level to write to this file.

Returns

1 on success, 0 if the callback slot table is full (max 4 sinks).

Definition at line 172 of file base_log.c.

Here is the call graph for this function:

base_log_message()

void base_log_message	(	BaseLogLevel	level,
		const char *	file,
		int	line,
		const char *	fmt,
			... )

Internal function that actually processes the log. DO NOT call directly.

Note

Use the LOG_* macros instead.

Definition at line 206 of file base_log.c.

Here is the call graph for this function:

base_log_remove_callback()

b32 base_log_remove_callback

(

BaseLogFn

fn

)

Removes a previously registered callback from the logger.

Must be called before closing a FILE* sink registered via base_log_add_fp() to prevent the logger from writing to a dangling pointer.

Example:

base_log_add_callback(my_callback, NULL, BASE_LOG_LEVEL_TRACE);
// ... use logger ...
base_log_remove_callback(my_callback); // free the slot

Parameters

fn	The function pointer that was passed to base_log_add_callback().

Returns

1 if the callback was found and removed, 0 if it was not registered.

Definition at line 192 of file base_log.c.

base_log_set_level()

void base_log_set_level

(

BaseLogLevel

level

)

Configures the active logging level. Messages below this level are ignored.

The level check happens before any locking, so filtered messages have virtually zero overhead — no lock acquire, no callback dispatch.

Example:

// In production builds, only log warnings and above:
base_log_set_level(BASE_LOG_LEVEL_WARN);
LOG_DEBUG("This is now silently ignored");
LOG_WARN("This goes through");

Parameters

level

The minimum level to output (e.g., BASE_LOG_LEVEL_INFO).

Definition at line 153 of file base_log.c.

base_log_set_lock()

void base_log_set_lock	(	BaseLogLockFn	fn,
		void *	user_data )

Configures thread-safety by providing a custom locking mechanism.

The lock callback is called with lock=1 before dispatching a message and lock=0 after. Pass NULL to disable locking (default, not thread-safe).

Example:

static CRITICAL_SECTION cs;
InitializeCriticalSection(&cs);
 
void win32_lock(void *ctx, b32 lock) {
    if (lock) EnterCriticalSection((CRITICAL_SECTION *)ctx);
    else      LeaveCriticalSection((CRITICAL_SECTION *)ctx);
}
 
base_log_set_lock(win32_lock, &cs);

Parameters

fn	The callback to invoke when a lock/unlock is required.
user_data	Opaque pointer passed to the locking callback.

Definition at line 165 of file base_log.c.

base_log_set_quiet()

void base_log_set_quiet

(

b32

enable

)

Mutes or unmutes all console (stdout/stderr) output.

Callbacks registered via base_log_add_callback() are NOT affected — they still fire. Only the built-in console sink is silenced.

Example:

// During tests, suppress console noise but keep callback active:
base_log_set_quiet(1);
LOG_INFO("Hello %s", "World"); // captured by callback, not printed
base_log_set_quiet(0);         // restore console output

Parameters

enable

1 (true) to mute console output, 0 (false) to enable it.

Definition at line 159 of file base_log.c.