lib/logger.x

Owned structured event delivery.

Primary API

Logger

Logger.new

Logger Logger.new(Symbol min_level)

Creates a Logger in the active Scope, filtering below min_level. The Logger borrows the active canonical pool for any memory sinks and owns a private Scope for sink state. An invalid level returns NULL.

Raises: <alloc-fail> when the Logger or its private Scope cannot be allocated.

Source: lib/logger.x:656

Advanced and interop API

Functions

log_debug

void log_debug(Symbol category, List fields)

Logs borrowed fields globally at debug level under category. Delivery and failure behavior follow log_event.

Source: lib/logger.x:786

log_error

void log_error(Symbol category, List fields)

Logs borrowed fields globally at error level under category. Delivery and failure behavior follow log_event.

Source: lib/logger.x:789

log_event

void log_event(Symbol level, Symbol category, List fields)

Delivers one event synchronously through the current global Logger. With no global Logger this is a no-op; otherwise delivery and failures are those of Logger.log.

Source: lib/logger.x:772

log_fatal

void log_fatal(Symbol category, List fields)

Logs borrowed fields globally at fatal level under category. Delivery and failure behavior follow log_event.

Source: lib/logger.x:790

log_get_global_logger

Logger log_get_global_logger(void)

Returns the borrowed current global Logger, or NULL when none is set.

Source: lib/logger.x:764

log_info

void log_info(Symbol category, List fields)

Logs borrowed fields globally at info level under category. Delivery and failure behavior follow log_event.

Source: lib/logger.x:787

log_set_global_logger

Logger log_set_global_logger(Logger logger)

Installs a borrowed global Logger and returns the previous borrowed value. Neither Logger is flushed, freed, or otherwise retained by this call; the installed Logger must remain live until it is replaced or shutdown runs.

Source: lib/logger.x:756

log_should_log

int log_should_log(Symbol level, Symbol category)

Reports whether the current global Logger would deliver this event.

Source: lib/logger.x:218

log_trace

void log_trace(Symbol category, List fields)

Logs borrowed fields globally at trace level under category. Delivery and failure behavior follow log_event.

Source: lib/logger.x:785

log_warn

void log_warn(Symbol category, List fields)

Logs borrowed fields globally at warn level under category. Delivery and failure behavior follow log_event.

Source: lib/logger.x:788

Logger

Logger.add_file_sink

LogSink Logger.add_file_sink(Logger logger, File file)

Adds a plain-text sink for borrowed file and returns its handle. The caller must keep file open until the sink is removed or the Logger is freed. Removing the sink flushes but never closes the File. A NULL argument returns NULL.

Raises: <alloc-fail> or <bad-enc> when sink state cannot be represented.

Source: lib/logger.x:532

Logger.add_memory_sink

LogSink Logger.add_memory_sink(Logger logger, List *destination)

Adds a sink that prepends captured events to destination. The destination pointer is borrowed until the sink is retired. Entry Lists, Strings, and Lisp symbols are interned through the pool captured by Logger.new; a canonical hit may retain an ancestor pool’s lifetime. Wide values move to the Logger’s owning Scope on retirement, while other pointer-bearing values remain borrowed. Newest events appear first. A NULL Logger or destination returns NULL. Registration may raise <alloc-fail> or <bad-enc> while constructing sink state. Later event delivery may raise <alloc-fail>, <size-limit>, or <bad-enc> while retaining values.

Source: lib/logger.x:629

Logger.add_sink

LogSink Logger.add_sink( Logger logger, LogEmitter emit, LogFlusher flush, Var data)

Appends a callback sink and returns its Logger-owned handle. A NULL Logger returns NULL; a quiescent Logger also returns NULL for a NULL emitter. The Logger borrows data and both callbacks until the sink is removed, cleared, or the Logger is freed, so anything they reference must remain live. Emitters run synchronously in registration order.

Raises: <bad-state> during active sink delivery, or <alloc-fail> when the sink cannot be allocated.

Source: lib/logger.x:285

Logger.add_stderr_sink

LogSink Logger.add_stderr_sink(Logger logger)

Adds a text sink for borrowed stderr and returns its Logger-owned handle. The sink selects color from terminal state at registration and flushes after every event. A NULL Logger returns NULL.

Raises: <alloc-fail> or <bad-enc> when sink state cannot be represented.

Source: lib/logger.x:519

Logger.clear_sinks

void Logger.clear_sinks(Logger logger)

Removes and invalidates every sink from logger. A NULL Logger does nothing.

Raises: <bad-state> during active sink delivery.

Source: lib/logger.x:310

Logger.debug

void Logger.debug( Logger logger, Symbol category, List fields)

Logs borrowed fields synchronously at debug level under category. Delivery and failure behavior follow Logger.log.

Source: lib/logger.x:744

Logger.error

void Logger.error( Logger logger, Symbol category, List fields)

Logs borrowed fields synchronously at error level under category. Delivery and failure behavior follow Logger.log.

Source: lib/logger.x:747

Logger.fatal

void Logger.fatal( Logger logger, Symbol category, List fields)

Logs borrowed fields synchronously at fatal level under category. Delivery and failure behavior follow Logger.log.

Source: lib/logger.x:748

Logger.flush

void Logger.flush(Logger logger)

Calls configured flushers synchronously in registration order. A NULL Logger does nothing. A cause raised by a flusher transfers immediately, so later sinks are not flushed. A flusher must not mutate the sink list or free its Logger.

Source: lib/logger.x:328

Logger.free

void Logger.free(Logger logger)

Flushes and retires every sink, then releases logger and its storage. Borrowed Files and callback data are not released. The global and default slots are cleared when they refer to this Logger. A NULL Logger does nothing.

Raises: <bad-state> during sink delivery, or any cause from a flusher. Either failure leaves the Logger and all sinks live; earlier flushers may already have run.

Source: lib/logger.x:675

Logger.info

void Logger.info( Logger logger, Symbol category, List fields)

Logs borrowed fields synchronously at info level under category. Delivery and failure behavior follow Logger.log.

Source: lib/logger.x:745

Logger.initialize

void Logger.initialize(void)

Installs the process-wide info-level Logger and stderr sink. Error initializes first, then this function records its handler watermark and installs an observing Error handler. Runtime initialization calls this once and later shutdown hooks invoke Logger.shutdown before Error shuts down.

Raises: any cause from Error or Logger initialization.

Source: lib/logger.x:859

Logger.level_priority

int Logger.level_priority(Symbol level)

Returns the ordering priority of a built-in level, or -1 when invalid. Priorities run from <trace> at zero through <off> at six.

Source: lib/logger.x:175

Logger.log

void Logger.log(Logger logger, Symbol level, Symbol category, List fields)

Delivers one event synchronously to eligible sinks in registration order. fields is borrowed for the call. All sinks observe one immutable event, sequence numbers increase per Logger, and elapsed time starts with its first delivered event. NULL, filtered, invalid, sinkless, or category-less events do nothing. Fatal delivery flushes all sinks afterward.

Raises: any cause from an emitter or fatal-event flusher; later callbacks are then skipped.

Source: lib/logger.x:696

Logger.min_level

Symbol Logger.min_level(Logger logger)

Returns logger’s minimum enabled level, or the null Symbol for NULL.

Source: lib/logger.x:179

Logger.remove_sink

int Logger.remove_sink(Logger logger, LogSink sink)

Removes and invalidates sink, returning one when it belonged to logger. When quiescent, a NULL argument, foreign sink, or already retired sink returns zero.

Raises: <bad-state> during active sink delivery.

Source: lib/logger.x:297

Logger.set_min_level

int Logger.set_min_level(Logger logger, Symbol level)

Sets the minimum enabled level and returns one. A NULL Logger or invalid level returns zero without changing anything.

Source: lib/logger.x:185

Logger.should_log

int Logger.should_log(Logger logger, Symbol level, Symbol category)

Reports whether an event would reach at least one sink. A category names an event rather than filtering it. A NULL Logger or category, no sinks, <off>, an invalid level, or a filtered level returns zero.

Source: lib/logger.x:213

Logger.shutdown

void Logger.shutdown(void)

Shuts down process-wide Logger integration. Pending root Errors are offered to the active Logger before the observing handler is removed. The global slot is then cleared; a custom active Logger is flushed but remains caller-owned, while the default Logger is flushed, retired, and freed. A repeated call after shutdown is a no-op.

Raises: <alloc-fail> while opening the temporary canonical pool, <bad-state> when default-Logger delivery is active, or any cause from event delivery or a sink flusher. The failure may interrupt the remaining cleanup.

Source: lib/logger.x:830

Logger.sink_count

int Logger.sink_count(Logger logger)

Returns the number of configured sinks, or zero for a NULL Logger.

Source: lib/logger.x:193

Logger.trace

void Logger.trace( Logger logger, Symbol category, List fields)

Logs borrowed fields synchronously at trace level under category. Delivery and failure behavior follow Logger.log.

Source: lib/logger.x:743

Logger.warn

void Logger.warn( Logger logger, Symbol category, List fields)

Logs borrowed fields synchronously at warn level under category. Delivery and failure behavior follow Logger.log.

Source: lib/logger.x:746

Runtime-internal callables

These callables connect runtime translation units. They are documented for source readers but are not supported as user API.

Logger

Logger.error_handler

Symbol Logger.error_handler(List errors, Var data)

Offers the newest Error to the current global Logger. A well-formed entry with <abort> or <log> policy is rendered as an <err-report> event; missing, malformed, <collect>, and <ignore> input produces no event. The borrowed input is never consumed, data is ignored, and the handler always returns <declined>, leaving transfer to Error or another handler.

Raises: any cause from Logger delivery.

Source: lib/logger.x:801

Public types

LogEmitter

typedef void (*LogEmitter)(Logger logger, const LogEvent *event, Var data)

Receives one borrowed event and the data supplied at registration. The callback may log recursively, but it must not retain event, mutate the active sink list, or free logger during delivery.

Source: lib/logger.x:46

LogEvent

typedef struct LogEvent { unsigned long sequence; long long wall_time_us; long long elapsed_us; Symbol level, category, List fields; } LogEvent

Describes one immutable event during synchronous sink delivery. The event pointer is valid only for the callback. fields is borrowed with its caller-provided lifetime, and every sink receives the same value.

Source: lib/logger.x:35

LogFlusher

typedef void (*LogFlusher)(Logger logger, Var data)

Flushes one sink with its borrowed registration data. The callback must not mutate the active sink list or free logger.

Source: lib/logger.x:51

LogSink

typedef struct LogSink *LogSink

A borrowed handle to one Logger-owned sink registration. Removal, clearing, or freeing its Logger invalidates the handle; callers never free it directly.

Source: lib/logger.x:29

Logger

typedef struct Logger *Logger

An ordered, reentrant sink dispatcher allocated in the active Scope. Logger.free must run before that Scope is released. Memory sinks also require the canonical pool captured by Logger.new to remain live.

Source: lib/logger.x:23

Design notes

Logger owns filtering, event timestamps, sink ordering, and sink lifetime. It is reentrant and serializes configuration, sequencing, and delivery. Expensive callers may query Logger.should_log before constructing canonical field Lists.

Events carry one wall-clock timestamp and one monotonic elapsed timestamp. Every sink for an event observes the same immutable LogEvent. Built-in text sinks render through Buffer and Var.write_repr without constructing canonical presentation Strings.

Tests and examples

make verify (unittest/test-logger.x).