mmap.h File Reference

Lock-free memory-mapped text logging with crash safety. More...

Go to the source code of this file.

Data Structures
struct	log_mmap_config
	Configuration for mmap logging. More...

Macros
#define	LOG_MMAP_DEFAULT_SIZE   (4 * 1024 * 1024)
	Default mmap log file size (4MB)

Typedefs
typedef struct log_mmap_config	log_mmap_config_t
	Configuration for mmap logging.

Functions
asciichat_error_t	log_mmap_init (const log_mmap_config_t *config)
	Initialize mmap-based text logging.
asciichat_error_t	log_mmap_init_simple (const char *log_path, size_t max_size)
	Initialize mmap logging with simple parameters.
void	log_mmap_destroy (void)
	Shutdown mmap logging.
void	log_mmap_write (int level, const char *file, int line, const char *func, const char *fmt,...)
	Write a log entry directly to the mmap'd file (lock-free)
bool	log_mmap_is_active (void)
	Check if mmap logging is active.
void	log_mmap_sync (void)
	Force sync the mmap'd file to disk.
void	log_mmap_install_crash_handlers (void)
	Install signal handlers for crash safety.
void	log_mmap_get_stats (uint64_t *bytes_written, uint64_t *wrap_count)
	Get statistics about the mmap log.
bool	log_mmap_get_usage (size_t *used, size_t *capacity)
	Get current mmap log usage.
void	log_mmap_rotate (void)
	Rotate the mmap log (tail-keeping rotation)

Detailed Description

Lock-free memory-mapped text logging with crash safety.

This module provides crash-safe logging by writing human-readable text directly to a memory-mapped log file. Key features:

• Lock-free logging: Uses atomic fetch_add for position claiming
• Crash-safe: Text is written directly to mmap'd file, readable after crash
• No flusher needed: Logs are human-readable in the file immediately
• Pure text: No binary header, works with grep/rg/cat without special flags
• Simple design: Just mmap the .log file and write text to it

Usage:

// Initialize mmap logging (call once at startup)
log_mmap_init("/tmp/myapp.log", 4 * 1024 * 1024);  // 4MB log file
 
// Use normal log_* macros - they automatically use mmap backend
log_debug("This uses atomic operations, no mutex!");
 
// Cleanup on shutdown
log_mmap_destroy();

Definition in file log/mmap.h.

Macro Definition Documentation

LOG_MMAP_DEFAULT_SIZE

#define LOG_MMAP_DEFAULT_SIZE   (4 * 1024 * 1024)

Default mmap log file size (4MB)

Definition at line 46 of file log/mmap.h.

Typedef Documentation

log_mmap_config_t

typedef struct log_mmap_config log_mmap_config_t

Configuration for mmap logging.

Function Documentation

log_mmap_destroy()

void log_mmap_destroy

(

void

)

Shutdown mmap logging.

Syncs and unmaps the log file.

Definition at line 257 of file mmap.c.

                            {
  if (!g_mmap_log.initialized) {
    return;
  }
 
  /* Write shutdown marker */
  log_mmap_write(1 /* LOG_INFO */, NULL, 0, NULL, "=== Log ended ===");
 
  /* Sync to disk */
  platform_mmap_sync(&g_mmap_log.mmap, true);
 
  /* Truncate file to actual content size to save space
   * This converts the large mmap file (4MB with newlines) to just the actual log content */
  uint64_t final_pos = atomic_load(&g_mmap_log.write_pos);
  if (final_pos < g_mmap_log.text_capacity && strlen(g_mmap_log.file_path) > 0) {
#ifdef _WIN32
    /* Windows: Close mmap first, then truncate file, then reopen for truncation */
    platform_mmap_close(&g_mmap_log.mmap);
    HANDLE hFile =
        CreateFileA(g_mmap_log.file_path, GENERIC_WRITE, 0, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);
    if (hFile != INVALID_HANDLE_VALUE) {
      LARGE_INTEGER size;
      size.QuadPart = (LONGLONG)final_pos;
      if (SetFilePointerEx(hFile, size, NULL, FILE_BEGIN)) {
        SetEndOfFile(hFile);
      }
      CloseHandle(hFile);
      log_info("mmap log: truncated %s to %zu bytes (was %zu MB)", g_mmap_log.file_path, (size_t)final_pos,
               g_mmap_log.text_capacity / 1024 / 1024);
    }
#else
    /* POSIX: Use ftruncate() on the file descriptor */
    if (g_mmap_log.mmap.fd >= 0) {
      if (ftruncate(g_mmap_log.mmap.fd, (off_t)final_pos) == 0) {
        log_info("mmap log: truncated %s to %zu bytes (was %zu MB)", g_mmap_log.file_path, (size_t)final_pos,
                 g_mmap_log.text_capacity / 1024 / 1024);
      }
    }
    platform_mmap_close(&g_mmap_log.mmap);
#endif
  } else {
    /* No truncation needed or path not set */
    platform_mmap_close(&g_mmap_log.mmap);
  }
 
  g_mmap_log.text_region = NULL;
  g_mmap_log.file_path[0] = '\0';
 
  g_mmap_log.initialized = false;
  log_info("mmap log: destroyed");
}

References log_info, log_mmap_write(), platform_mmap_close(), and platform_mmap_sync().

Referenced by log_destroy(), log_disable_mmap(), and log_mmap_init().

log_mmap_get_stats()

void log_mmap_get_stats	(	uint64_t *	bytes_written,
		uint64_t *	wrap_count
	)

Get statistics about the mmap log.

Parameters

[out]	bytes_written	Total bytes written since init
[out]	wrap_count	Number of times log has wrapped

Definition at line 385 of file mmap.c.

                                                                       {
  if (bytes_written) {
    *bytes_written = atomic_load(&g_mmap_log.bytes_written);
  }
  if (wrap_count) {
    *wrap_count = atomic_load(&g_mmap_log.wrap_count);
  }
}

References bytes_written, and wrap_count.

log_mmap_get_usage()

bool log_mmap_get_usage	(	size_t *	used,
		size_t *	capacity
	)

Get current mmap log usage.

Parameters

[out]	used	Current bytes used in the log
[out]	capacity	Total capacity of the log

Returns

true if mmap is active and values are valid

Definition at line 394 of file mmap.c.

                                                        {
  if (!g_mmap_log.initialized) {
    return false;
  }
 
  if (used) {
    *used = (size_t)atomic_load(&g_mmap_log.write_pos);
  }
  if (capacity) {
    *capacity = g_mmap_log.text_capacity;
  }
  return true;
}

log_mmap_init()

asciichat_error_t log_mmap_init

(

const log_mmap_config_t *

config

)

Initialize mmap-based text logging.

Creates or opens a memory-mapped log file. Text is written directly to the file, so it's readable even after a crash.

Parameters

config

Configuration options

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 188 of file mmap.c.

                                                                 {
  if (!config || !config->log_path) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "mmap log: config or log_path is NULL");
  }
 
  if (g_mmap_log.initialized) {
    log_warn("mmap log: already initialized, destroying first");
    log_mmap_destroy();
  }
 
  /* Determine file size */
  size_t file_size = config->max_size > 0 ? config->max_size : LOG_MMAP_DEFAULT_SIZE;
  if (file_size < 1024) {
    file_size = 1024; /* Minimum reasonable size */
  }
 
  /* Store file path for later truncation */
  SAFE_STRNCPY(g_mmap_log.file_path, config->log_path, sizeof(g_mmap_log.file_path) - 1);
 
  /* Open mmap file */
  platform_mmap_init(&g_mmap_log.mmap);
  asciichat_error_t result = platform_mmap_open(config->log_path, file_size, &g_mmap_log.mmap);
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  /* Entire file is text - no header */
  g_mmap_log.text_region = (char *)g_mmap_log.mmap.addr;
  g_mmap_log.text_capacity = file_size;
 
  /* Find where existing content ends (scan for last newline before spaces/nulls) */
  size_t existing_pos = find_content_end(g_mmap_log.text_region, file_size);
  atomic_store(&g_mmap_log.write_pos, existing_pos);
 
  /* Clear unused portion with newlines (grep-friendly without needing -a flag)
   * We truncate the file on clean shutdown to save space */
  if (existing_pos < file_size) {
    memset(g_mmap_log.text_region + existing_pos, '\n', file_size - existing_pos);
  }
 
  if (existing_pos > 0) {
    log_info("mmap log: resumed existing log at position %zu", existing_pos);
  } else {
    log_info("mmap log: created new log file %s (%zu bytes)", config->log_path, file_size);
  }
 
  /* Reset statistics */
  atomic_store(&g_mmap_log.bytes_written, 0);
  atomic_store(&g_mmap_log.wrap_count, 0);
 
  /* Install crash handlers */
  log_mmap_install_crash_handlers();
 
  g_mmap_log.initialized = true;
 
  /* Write startup marker */
  log_mmap_write(1 /* LOG_INFO */, NULL, 0, NULL, "=== Log started (mmap text mode, %zu bytes) ===", file_size);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, log_info, LOG_MMAP_DEFAULT_SIZE, log_mmap_destroy(), log_mmap_install_crash_handlers(), log_mmap_write(), log_mmap_config::log_path, log_warn, log_mmap_config::max_size, platform_mmap_init(), platform_mmap_open(), SAFE_STRNCPY, and SET_ERRNO.

Referenced by log_mmap_init_simple().

log_mmap_init_simple()

asciichat_error_t log_mmap_init_simple	(	const char *	log_path,
		size_t	max_size
	)

Initialize mmap logging with simple parameters.

Convenience wrapper around log_mmap_init().

Parameters

log_path	Path to log file
max_size	Maximum file size (0 = default 4MB)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 249 of file mmap.c.

                                                                              {
  log_mmap_config_t config = {
      .log_path = log_path,
      .max_size = max_size,
  };
  return log_mmap_init(&config);
}

References log_mmap_init(), and log_mmap_config::log_path.

Referenced by log_enable_mmap_sized(), and log_init().

log_mmap_install_crash_handlers()

void log_mmap_install_crash_handlers

(

void

)

Install signal handlers for crash safety.

Registers handlers for SIGSEGV, SIGABRT, etc. that sync the mmap before the process terminates.

Note

Signal handlers are automatically installed by log_mmap_init().

Definition at line 141 of file mmap.c.

                                           {
#ifndef _WIN32
  struct sigaction sa = {0};
  sa.sa_handler = crash_signal_handler;
  sigemptyset(&sa.sa_mask);
  sa.sa_flags = (int)SA_RESETHAND; /* One-shot */
 
  sigaction(SIGSEGV, &sa, NULL);
  sigaction(SIGABRT, &sa, NULL);
  sigaction(SIGBUS, &sa, NULL);
  sigaction(SIGFPE, &sa, NULL);
  sigaction(SIGILL, &sa, NULL);
#else
  SetUnhandledExceptionFilter(windows_crash_handler);
#endif
}

Referenced by log_mmap_init().

log_mmap_is_active()

bool log_mmap_is_active

(

void

)

Check if mmap logging is active.

Returns

true if mmap logging is initialized and active

Definition at line 375 of file mmap.c.

                              {
  return g_mmap_log.initialized;
}

Referenced by log_destroy(), log_disable_mmap(), log_file_msg(), log_msg(), and log_plain_msg().

log_mmap_rotate()

void log_mmap_rotate

(

void

)

Rotate the mmap log (tail-keeping rotation)

Keeps the most recent log entries (tail) and discards old ones. This is the mmap equivalent of file-based log rotation.

Note

Caller must hold the rotation mutex from logging.c. This is called by maybe_rotate_log() which handles locking.

Definition at line 408 of file mmap.c.

                           {
  if (!g_mmap_log.initialized || !g_mmap_log.text_region) {
    return;
  }
 
  /* NOTE: Caller must hold the rotation mutex from logging.c */
 
  uint64_t current_pos = atomic_load(&g_mmap_log.write_pos);
  size_t capacity = g_mmap_log.text_capacity;
 
  /* Keep last 2/3 of the log (same ratio as file rotation) */
  size_t keep_size = capacity * 2 / 3;
  if (current_pos <= keep_size) {
    return;
  }
 
  /* Find where to start keeping (skip to beginning of current_pos - keep_size) */
  size_t skip_bytes = (size_t)current_pos - keep_size;
  char *keep_start = g_mmap_log.text_region + skip_bytes;
 
  /* Skip to next line boundary to avoid partial lines */
  size_t skipped = 0;
  while (skipped < keep_size && *keep_start != '\n') {
    keep_start++;
    skipped++;
  }
  if (skipped < keep_size && *keep_start == '\n') {
    keep_start++;
    skipped++;
  }
 
  size_t actual_keep = keep_size - skipped;
  if (actual_keep == 0) {
    /* Nothing to keep - just reset */
    atomic_store(&g_mmap_log.write_pos, 0);
    memset(g_mmap_log.text_region, '\n', capacity);
    return;
  }
 
  /* Move the tail to the beginning using memmove (handles overlap) */
  memmove(g_mmap_log.text_region, keep_start, actual_keep);
 
  /* Clear the rest with newlines (grep-friendly without needing -a flag) */
  memset(g_mmap_log.text_region + actual_keep, '\n', capacity - actual_keep);
 
  /* Update write position */
  atomic_store(&g_mmap_log.write_pos, actual_keep);
 
  /* Write rotation marker */
  const char *rotate_msg = "\n=== LOG ROTATED ===\n";
  size_t rotate_len = strlen(rotate_msg);
  if (actual_keep + rotate_len < capacity) {
    memcpy(g_mmap_log.text_region + actual_keep, rotate_msg, rotate_len);
    atomic_store(&g_mmap_log.write_pos, actual_keep + rotate_len);
  }
 
  atomic_fetch_add(&g_mmap_log.wrap_count, 1);
 
  /* Sync after rotation */
  platform_mmap_sync(&g_mmap_log.mmap, true);
}

References platform_mmap_sync().

log_mmap_sync()

void log_mmap_sync

(

void

)

Force sync the mmap'd file to disk.

Ensures all written data is flushed to the underlying file. Called automatically for ERROR/FATAL levels and on shutdown.

Definition at line 379 of file mmap.c.

                         {
  if (g_mmap_log.initialized) {
    platform_mmap_sync(&g_mmap_log.mmap, true);
  }
}

References platform_mmap_sync().

log_mmap_write()

void log_mmap_write	(	int	level,
		const char *	file,
		int	line,
		const char *	func,
		const char *	fmt,
			...
	)

Write a log entry directly to the mmap'd file (lock-free)

Formats the log message and writes it directly as human-readable text. Uses atomic operations only, no mutex.

Parameters

level	Log level
file	Source file (can be NULL)
line	Source line
func	Function name (can be NULL)
fmt	Format string
...	Format arguments

Definition at line 309 of file mmap.c.

                                                                                                   {
  if (!g_mmap_log.initialized || !g_mmap_log.text_region) {
    return;
  }
 
  static const char *level_names[] = {"DEV", "DEBUG", "INFO", "WARN", "ERROR", "FATAL"};
  const char *level_name = (level >= 0 && level < 6) ? level_names[level] : "???";
 
  /* Format the complete log line into a local buffer first */
  char line_buf[LOG_MMAP_MSG_BUFFER_SIZE];
  char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
  format_timestamp(time_buf, sizeof(time_buf));
 
  int prefix_len;
  if (file && func) {
    prefix_len =
        snprintf(line_buf, sizeof(line_buf), "[%s] [%s] %s:%d in %s(): ", time_buf, level_name, file, line, func);
  } else {
    prefix_len = snprintf(line_buf, sizeof(line_buf), "[%s] [%s] ", time_buf, level_name);
  }
 
  if (prefix_len < 0) {
    return;
  }
 
  /* Format the message */
  va_list args;
  va_start(args, fmt);
  int msg_len = vsnprintf(line_buf + prefix_len, sizeof(line_buf) - (size_t)prefix_len - 1, fmt, args);
  va_end(args);
 
  if (msg_len < 0) {
    return;
  }
 
  /* Add newline */
  size_t total_len = (size_t)prefix_len + (size_t)msg_len;
  if (total_len >= sizeof(line_buf) - 1) {
    total_len = sizeof(line_buf) - 2; /* Truncate if too long */
  }
  line_buf[total_len] = '\n';
  total_len++;
  line_buf[total_len] = '\0';
 
  /* Atomically claim space in the mmap'd region */
  uint64_t pos = atomic_fetch_add(&g_mmap_log.write_pos, total_len);
 
  /* Check if we exceeded capacity - drop this message if so */
  /* Rotation is handled by maybe_rotate_log() called from logging.c */
  if (pos + total_len > g_mmap_log.text_capacity) {
    /* Undo our claim - we can't fit */
    atomic_fetch_sub(&g_mmap_log.write_pos, total_len);
    return;
  }
 
  /* Copy formatted text to mmap'd region */
  memcpy(g_mmap_log.text_region + pos, line_buf, total_len);
 
  atomic_fetch_add(&g_mmap_log.bytes_written, total_len);
 
  /* Sync for ERROR/FATAL to ensure visibility on crash */
  if (level >= 4 /* LOG_ERROR */) {
    platform_mmap_sync(&g_mmap_log.mmap, false);
  }
}

References LOG_MMAP_MSG_BUFFER_SIZE, LOG_TIMESTAMP_BUFFER_SIZE, and platform_mmap_sync().

Referenced by log_file_msg(), log_mmap_destroy(), log_mmap_init(), log_msg(), and log_plain_msg().