Rate-Limited Log Macros

Macros
#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__)

Detailed Description

Variants that emit only some of the times their call site is reached. The state lives in the call site's own LogSite, so no registry, allocation, or key derivation is involved and two call sites never share a budget – not even two identical messages in the same function.

The level check happens first. A gate is only consumed when something is actually listening at that level on that channel, so a logStrOnce() in startup code does not spend its single emission on a message logged before any destination was registered.

The counters are not serialized. Two threads reaching a logStrEveryN() site at once can both pass; making a rate limit exact needs a lock per call site, which costs more than the handful of messages it saves. Treat the counts as approximate.

Macro Definition Documentation

logFmtEveryN

#define logFmtEveryN	(		level,
			n,
			fmt,
			...
	)		_logFmtArgs(level, LOG_CHANNEL, LOG_SiteEveryN, (n), fmt, __VA_ARGS__)

void logFmtEveryN(level, n, fmt, ...)

Log a formatted message every Nth time this call site is reached

Parameters

level	Log level without LOG_ prefix
n	Emit on every Nth arrival; values below 1 are treated as 1
fmt	Format string
...	Format arguments wrapped in stvar() logFmtEveryN(Warn, 1000, _SL("dropped ${int} frames"), stvar(int32, ndropped));

Definition at line 732 of file log.h.

logFmtEveryT

#define logFmtEveryT	(		level,
			interval,
			fmt,
			...
	)		_logFmtArgs(level, LOG_CHANNEL, LOG_SiteEveryT, (interval), fmt, __VA_ARGS__)

void logFmtEveryT(level, interval, fmt, ...)

Log a formatted message at most once per interval

Parameters

level	Log level without LOG_ prefix
interval	Minimum time between emissions, in cx time units (e.g. timeS(10))
fmt	Format string
...	Format arguments wrapped in stvar() logFmtEveryT(Warn, timeS(5), _SL("queue depth ${int}"), stvar(int32, depth));

Definition at line 745 of file log.h.

logFmtOnce

#define logFmtOnce	(		level,
			fmt,
			...
	)		_logFmtArgs(level, LOG_CHANNEL, LOG_SiteOnce, 0, fmt, __VA_ARGS__)

void logFmtOnce(level, fmt, ...)

Log a formatted message the first time this call site is reached, and never again

Parameters

level	Log level without LOG_ prefix
fmt	Format string
...	Format arguments wrapped in stvar() logFmtOnce(Warn, _SL("falling back to ${string}"), stvar(string, name));

Definition at line 719 of file log.h.

logStrEveryN

#define logStrEveryN	(		level,
			n,
			str
	)		_logStr_##level(LOG_##level, LOG_CHANNEL, LOG_SiteEveryN, (n), str)

void logStrEveryN(level, n, str)

Log a string message every Nth time this call site is reached, starting with the first

Parameters

level	Log level without LOG_ prefix
n	Emit on every Nth arrival; values below 1 are treated as 1
str	String or string reference to log logStrEveryN(Warn, 1000, _SL("packet checksum mismatch"));

Definition at line 695 of file log.h.

logStrEveryT

#define logStrEveryT	(		level,
			interval,
			str
	)		_logStr_##level(LOG_##level, LOG_CHANNEL, LOG_SiteEveryT, (interval), str)

void logStrEveryT(level, interval, str)

Log a string message at most once per interval, starting with the first arrival

Parameters

level	Log level without LOG_ prefix
interval	Minimum time between emissions, in cx time units (e.g. timeS(10))
str	String or string reference to log logStrEveryT(Warn, timeS(10), _SL("send queue is still over the high-water mark"));

Definition at line 707 of file log.h.

logStrOnce

#define logStrOnce	(		level,
			str
	)		_logStr_##level(LOG_##level, LOG_CHANNEL, LOG_SiteOnce, 0, str)

void logStrOnce(level, str)

Log a string message the first time this call site is reached, and never again

Parameters

level	Log level without LOG_ prefix
str	String or string reference to log logStrOnce(Warn, _SL("hardware clock is not monotonic; using fallback"));

Definition at line 684 of file log.h.