session_log_buffer.h File Reference

Thread-safe circular log buffer for session screens (status, splash). More...

Go to the source code of this file.

Data Structures
struct	session_log_entry_t
	One formatted session log line and its monotonic history sequence. More...

Macros
#define	SESSION_LOG_BUFFER_SIZE   16384
#define	SESSION_LOG_LINE_MAX   1024

Functions
session_log_buffer_t *	session_log_buffer_create (void)
	Create a new session log buffer instance.
void	session_log_buffer_destroy (session_log_buffer_t *buf)
	Cleanup session log buffer instance.
void	session_log_buffer_clear (session_log_buffer_t *buf)
	Clear all log entries from buffer.
void	session_log_buffer_append (session_log_buffer_t *buf, const char *message)
	Append a log message to the buffer.
size_t	session_log_buffer_get_recent (session_log_buffer_t *buf, session_log_entry_t *out_entries, size_t max_count)
	Get recent log entries from buffer.

Detailed Description

Thread-safe circular log buffer for session screens (status, splash).

Provides a reusable log capture mechanism for session screens that need to display logs alongside fixed header content without terminal scrolling.

Thread-safe for concurrent append operations. Designed for use by:

• Server status screen (live log feed under status header)
• Splash screen (logs under animated ASCII art)

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

February 2026

Definition in file session_log_buffer.h.

Macro Definition Documentation

SESSION_LOG_BUFFER_SIZE

#define SESSION_LOG_BUFFER_SIZE   16384

Definition at line 30 of file session_log_buffer.h.

Referenced by log_search_filter_buffer(), session_log_buffer_append(), session_log_buffer_clear(), session_log_buffer_get_recent(), and terminal_screen_compose().

SESSION_LOG_LINE_MAX

#define SESSION_LOG_LINE_MAX   1024

Definition at line 31 of file session_log_buffer.h.

Referenced by log_search_filter_buffer(), and session_log_buffer_append().

Function Documentation

session_log_buffer_append()

void session_log_buffer_append	(	session_log_buffer_t *	buf,
		const char *	message )

Append a log message to the buffer.

Thread-safe. Called from logging system to capture messages. Message is copied into circular buffer (oldest entry overwritten if full).

Parameters

buf	Buffer instance (must not be NULL)
message	Log message text (already formatted with colors)

Definition at line 73 of file session_log_buffer.c.

                                                                               {
  if (!buf || !message) {
    // Fail silently - this is called FROM the logging system
    // Using SET_ERRNO here would cause infinite recursion
    return;
  }
 
  mutex_lock(&buf->mutex);
 
  // Keep every line of multiline notices and split long lines at UTF-8 boundaries.
  // Hold the lock for the entire message so concurrent producers cannot interleave it.
  do {
    const char *newline = strchr(message, '\n');
    size_t length = newline ? (size_t)(newline - message) : strlen(message);
    if (length >= SESSION_LOG_LINE_MAX) {
      length = SESSION_LOG_LINE_MAX - 1;
      while (length && ((unsigned char)message[length] & 0xc0) == 0x80)
        --length;
      if (!length)
        length = SESSION_LOG_LINE_MAX - 1; // Malformed UTF-8 must still make progress.
    }
    size_t pos = atomic_load_u64(&buf->write_pos);
    memcpy(buf->entries[pos].message, message, length);
    buf->entries[pos].message[length] = '\0';
    buf->entries[pos].sequence = atomic_fetch_add_u64(&buf->sequence, 1) + 1;
    atomic_store_u64(&buf->write_pos, (pos + 1) % SESSION_LOG_BUFFER_SIZE);
    message += length;
    if (*message == '\n')
      ++message;
  } while (*message);
 
  mutex_unlock(&buf->mutex);
}

References session_log_buffer::entries, session_log_entry_t::message, session_log_buffer::mutex, session_log_buffer::sequence, session_log_entry_t::sequence, SESSION_LOG_BUFFER_SIZE, SESSION_LOG_LINE_MAX, and session_log_buffer::write_pos.

Referenced by log_file_msg(), log_msg(), log_plain_msg(), and ui_session_log().

session_log_buffer_clear()

void session_log_buffer_clear

(

session_log_buffer_t *

buf

)

Clear all log entries from buffer.

Thread-safe. Resets buffer to empty state, discarding all captured logs. Useful for clearing initialization logs before screen starts rendering.

Parameters

buf	Buffer instance (must not be NULL)

Definition at line 53 of file session_log_buffer.c.

                                                         {
  if (!buf) {
    return;
  }
 
  mutex_lock(&buf->mutex);
 
  // Reset write position and sequence
  atomic_store_u64(&buf->write_pos, 0);
  atomic_store_u64(&buf->sequence, 0);
 
  // Clear all entries
  for (size_t i = 0; i < SESSION_LOG_BUFFER_SIZE; i++) {
    buf->entries[i].message[0] = '\0';
    buf->entries[i].sequence = 0;
  }
 
  mutex_unlock(&buf->mutex);
}

References session_log_buffer::entries, session_log_entry_t::message, session_log_buffer::mutex, session_log_buffer::sequence, session_log_entry_t::sequence, SESSION_LOG_BUFFER_SIZE, and session_log_buffer::write_pos.

Referenced by terminal_screen_log_clear().

session_log_buffer_create()

session_log_buffer_t * session_log_buffer_create

(

void

)

Create a new session log buffer instance.

Allocates and initializes a circular buffer for log capture. Caller is responsible for calling session_log_buffer_destroy() when done.

Returns

Pointer to new buffer instance, or NULL on allocation failure

Definition at line 31 of file session_log_buffer.c.

                                                      {
  session_log_buffer_t *buf = SAFE_CALLOC(1, sizeof(session_log_buffer_t), session_log_buffer_t *);
  if (!buf) {
    return NULL;
  }
 
  atomic_store_u64(&buf->write_pos, 0);
  atomic_store_u64(&buf->sequence, 0);
  mutex_init(&buf->mutex, "log_buffer");
 
  return buf;
}

References session_log_buffer::mutex, SAFE_CALLOC, session_log_buffer::sequence, and session_log_buffer::write_pos.

Referenced by log_init(), terminal_screen_log_init(), and ui_session_create().

session_log_buffer_destroy()

void session_log_buffer_destroy

(

session_log_buffer_t *

buf

)

Cleanup session log buffer instance.

Frees the buffer and all internal resources. Safe to call with NULL.

Parameters

buf	Buffer instance to destroy (can be NULL)

Definition at line 44 of file session_log_buffer.c.

                                                           {
  if (!buf) {
    return;
  }
 
  mutex_destroy(&buf->mutex);
  SAFE_FREE(buf);
}

References session_log_buffer::mutex, and SAFE_FREE.

Referenced by log_system_destroy(), terminal_screen_log_destroy(), and ui_session_destroy().

session_log_buffer_get_recent()

size_t session_log_buffer_get_recent	(	session_log_buffer_t *	buf,
		session_log_entry_t *	out_entries,
		size_t	max_count )

Get recent log entries from buffer.

Thread-safe. Copies up to max_count recent entries into out_entries. Entries are returned in chronological order (oldest first).

Parameters

buf	Buffer instance (must not be NULL)
out_entries	Output array to fill with log entries
max_count	Maximum number of entries to return

Returns

Number of entries actually copied (may be less than max_count)

Definition at line 107 of file session_log_buffer.c.

                                                                                                                    {
  if (!buf || !out_entries || max_count == 0) {
    // Fail silently - called from display code that handles 0 gracefully
    // Using SET_ERRNO here could cause recursion if error logging is enabled
    return 0;
  }
 
  mutex_lock(&buf->mutex);
 
  size_t write_pos = atomic_load_u64(&buf->write_pos);
  uint64_t total_entries = atomic_load_u64(&buf->sequence);
 
  size_t entries_to_check = total_entries < SESSION_LOG_BUFFER_SIZE ? (size_t)total_entries : SESSION_LOG_BUFFER_SIZE;
  if (entries_to_check > max_count)
    entries_to_check = max_count;
  size_t start_pos = (write_pos + SESSION_LOG_BUFFER_SIZE - entries_to_check) % SESSION_LOG_BUFFER_SIZE;
 
  size_t count = 0;
  for (size_t i = 0; i < entries_to_check && count < max_count; i++) {
    size_t idx = (start_pos + i) % SESSION_LOG_BUFFER_SIZE;
    if (buf->entries[idx].sequence > 0) {
      memcpy(&out_entries[count], &buf->entries[idx], sizeof(session_log_entry_t));
      count++;
    }
  }
 
  mutex_unlock(&buf->mutex);
  return count;
}

References session_log_buffer::entries, session_log_buffer::mutex, session_log_buffer::sequence, session_log_entry_t::sequence, SESSION_LOG_BUFFER_SIZE, session_log_buffer::write_pos, and write_pos.

Referenced by log_search_filter_buffer(), and terminal_screen_compose().