log_async.c File Reference

Opt-in background writer for log lines (cwist_log_async_start()). More...

#include "log_async.h"
#include <cwist/sys/app/logger.h>
#include <cwist/core/mem/alloc.h>
#include <errno.h>
#include <pthread.h>
#include <stdbool.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <cwist/sys/platform.h>

Include dependency graph for log_async.c:

Go to the source code of this file.

Macros
#define	_POSIX_C_SOURCE   200809L
#define	LOG_ASYNC_DEFAULT_BYTES   ((size_t)256 * 1024)
#define	LOG_ASYNC_STREAMS   2 /* [0] = stdout, [1] = stderr */

Functions
bool	cwist_log_async_start (size_t buffer_bytes)
	Start writing log lines from a background thread.
void	cwist_log_async_flush (void)
	Block until every line queued so far has been written. No-op when inactive.
void	cwist_log_async_stop (void)
	Write out every queued line, stop the writer and go back to synchronous logging. Safe to call when async logging is not active, and more than once.
bool	cwist_log_async_active (void)
	Report whether async logging is active.
bool	cwist_log_async_submit (int fd, const char *line, size_t len)
	Queue one complete line for fd (STDOUT_FILENO or STDERR_FILENO).

Detailed Description

Opt-in background writer for log lines (cwist_log_async_start()).

Each output fd (stdout, stderr) has one byte ring. A caller formats its line on its own stack, copies it into the ring under one mutex and returns; a single writer thread write()s the rings to their fds. Callers never make a syscall on the request path, and lines stay whole and in submission order per fd.

A full ring makes the caller wait for space, so no line is dropped. A line larger than the ring, or any line while the writer is not running, is refused and the caller writes it synchronously as before.

fork(): the child keeps the rings' memory but not the writer thread. Its copy of the parent's queued bytes is discarded (the parent writes them) and a writer is started on the child's first line.

Definition in file log_async.c.

Macro Definition Documentation

_POSIX_C_SOURCE

#define _POSIX_C_SOURCE   200809L

Definition at line 18 of file log_async.c.

LOG_ASYNC_DEFAULT_BYTES

#define LOG_ASYNC_DEFAULT_BYTES   ((size_t)256 * 1024)

Definition at line 51 of file log_async.c.

LOG_ASYNC_STREAMS

#define LOG_ASYNC_STREAMS   2 /* [0] = stdout, [1] = stderr */

Definition at line 52 of file log_async.c.

Function Documentation

cwist_log_async_active()

bool cwist_log_async_active

(

void

)

Report whether async logging is active.

Whether the background log writer is active.

Returns

true between a successful cwist_log_async_start() and cwist_log_async_stop().

Definition at line 256 of file log_async.c.

References cap.

cwist_log_async_flush()

void cwist_log_async_flush

(

void

)

Block until every line queued so far has been written. No-op when inactive.

Block until every line queued so far has been written.

Definition at line 221 of file log_async.c.

References cap.

cwist_log_async_start()

bool cwist_log_async_start

(

size_t

buffer_bytes

)

Start writing log lines from a background thread.

Start the background log writer.

Parameters

buffer_bytes

Ring size per stream (stdout and stderr); 0 selects 256 KiB.

Returns

true when async logging is active (also when it already was), false when memory or the thread could not be had; logging then stays synchronous.

Note

Covers cwist_logger_* and the built-in access-log middleware. Lines queued at exit() are written by an atexit hook; call cwist_log_async_stop() or cwist_log_async_flush() before _exit() or a crash-prone section if the last lines matter.

Definition at line 176 of file log_async.c.

References cap, cwist_alloc(), cwist_free(), LOG_ASYNC_DEFAULT_BYTES, and LOG_ASYNC_STREAMS.

cwist_log_async_stop()

void cwist_log_async_stop

(

void

)

Write out every queued line, stop the writer and go back to synchronous logging. Safe to call when async logging is not active, and more than once.

Write out queued lines, stop the writer and return to synchronous output.

Definition at line 229 of file log_async.c.

References cap, cwist_free(), and LOG_ASYNC_STREAMS.

cwist_log_async_submit()

bool cwist_log_async_submit	(	int	fd,
		const char *	line,
		size_t	len
	)

Queue one complete line for fd (STDOUT_FILENO or STDERR_FILENO).

Returns

true when queued; false when async logging is off, fd is not stdout/stderr, or the line is larger than the ring. The caller then writes the line synchronously itself.

Definition at line 263 of file log_async.c.

References cap.