Server performance statistics tracking. More...

Data Structures
struct	server_stats_t
	Server performance statistics structure. More...

Functions
void *	stats_logger_thread (void *arg)
	Main statistics collection and reporting thread function.

int	stats_init (void)
	Initialize the stats mutex.

void	stats_cleanup (void)
	Cleanup the stats mutex.

void	update_server_stats (void)
	Update global server statistics (placeholder)

void	log_server_stats (void)
	Log comprehensive server statistics summary.

Variables
server_stats_t	g_stats
	Global server statistics structure.

mutex_t	g_stats_mutex
	Mutex protecting global server statistics.

Detailed Description

Server performance statistics tracking.

This header provides server-side performance statistics tracking including frame capture/send rates, bandwidth metrics, and performance counters.

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

Date: September 2025

Definition in file stats.h.

Function Documentation

◆ log_server_stats()

void log_server_stats ( void )

Log comprehensive server statistics summary.

Outputs a formatted summary of server performance statistics including frame processing rates, throughput metrics, and system health indicators. This function provides operational visibility into server performance.

STATISTICS REPORTED:

FRAME PROCESSING METRICS:

frames_captured: Total frames received from all clients
frames_sent: Total ASCII frames delivered to all clients
frames_dropped: Frames lost due to overload or errors

PERFORMANCE INDICATORS:

avg_capture_fps: Moving average of frame capture rate
avg_send_fps: Moving average of frame delivery rate

THREAD SAFETY:

Acquires g_stats_mutex for atomic statistics snapshot
Prevents inconsistent reporting during concurrent updates
Minimal lock hold time (only during data copy)

USAGE SCENARIOS:

Periodic performance reporting
Debug information during troubleshooting
System health monitoring
Performance trend analysis

OUTPUT FORMAT:

Human-readable format suitable for log analysis
Structured data for automated monitoring
Consistent formatting for operational visibility

Note: Function provides thread-safe access to global statistics; Statistics snapshot is atomic to ensure consistency

See also: update_server_stats() For statistics update implementation

Definition at line 559 of file stats.c.

                            {
  // Check if stats mutex is initialized before trying to lock it
  // In debug builds, stats_init() may not be called (it's guarded by #ifdef NDEBUG)
  // Skip logging if mutex is not initialized to avoid crashing
  if (!g_stats_mutex_initialized) {
    return; // Mutex not initialized, skip logging
  }
  mutex_lock(&g_stats_mutex);
  log_info("Server Statistics:\n"
           "  frames_captured=%llu\n"
           "  frames_sent=%llu\n"
           "  frames_dropped=%llu\n"
           "  Average FPS: capture=%.2f, send=%.2f",
           (unsigned long long)g_stats.frames_captured, (unsigned long long)g_stats.frames_sent,
           (unsigned long long)g_stats.frames_dropped, g_stats.avg_capture_fps, g_stats.avg_send_fps);
  mutex_unlock(&g_stats_mutex);
}

References server_stats_t::avg_capture_fps, server_stats_t::avg_send_fps, server_stats_t::frames_captured, server_stats_t::frames_dropped, server_stats_t::frames_sent, g_stats, g_stats_mutex, log_info, mutex_lock, and mutex_unlock.

Referenced by stats_logger_thread().

◆ stats_cleanup()

void stats_cleanup ( void )

Cleanup the stats mutex.

Definition at line 195 of file stats.c.

                         {
  if (g_stats_mutex_initialized) {
    mutex_destroy(&g_stats_mutex);
    g_stats_mutex_initialized = false;
  }
}

References g_stats_mutex, and mutex_destroy().

Referenced by server_main().

◆ stats_init()

int stats_init ( void )

Initialize the stats mutex.

Returns: 0 on success, -1 on failure

Definition at line 184 of file stats.c.

                     {
  int ret = mutex_init(&g_stats_mutex);
  if (ret == 0) {
    g_stats_mutex_initialized = true;
  }
  return ret;
}

References g_stats_mutex, and mutex_init().

Referenced by server_main().

◆ stats_logger_thread()

void * stats_logger_thread ( void * arg )

Main statistics collection and reporting thread function.

This background thread performs continuous monitoring of server performance and logs comprehensive statistics reports at regular intervals. It operates independently of the main server processing threads to avoid performance impact.

THREAD EXECUTION FLOW:

INITIALIZATION:
- Log thread startup (with debug instrumentation)
- Initialize loop counters for debugging
- Set up monitoring infrastructure
MAIN MONITORING LOOP:
- Check shutdown flag frequently (every 10ms)
- Sleep in small intervals to maintain responsiveness
- Collect statistics from all system components every 30 seconds
- Generate comprehensive performance reports
STATISTICS COLLECTION:
- Global buffer pool utilization
- Per-client connection and activity status
- Packet queue performance metrics
- Hash table efficiency statistics
- Frame processing counters
CLEANUP AND EXIT:
- Detect shutdown signal and exit loop gracefully
- Log thread termination for debugging
- Return NULL to indicate clean exit

MONITORING METHODOLOGY:

NON-BLOCKING DATA COLLECTION:

Uses reader locks on shared data structures
Takes atomic snapshots of volatile counters
Minimal impact on operational performance
Safe concurrent access with render threads

RESPONSIVE SHUTDOWN:

Checks g_server_should_exit every 10ms during sleep periods
Exits monitoring loop immediately when shutdown detected
No hanging or delayed shutdown behavior
Clean resource cleanup

PERFORMANCE METRICS COLLECTED:

CLIENT STATISTICS:

Total active clients
Clients with audio queues active
Clients with video queues active
Per-client connection duration

BUFFER POOL METRICS:

Global allocation/deallocation rates
Peak memory usage patterns
Buffer pool efficiency
Memory fragmentation indicators

PACKET QUEUE PERFORMANCE:

Per-client enqueue/dequeue rates
Packet drop incidents
Queue depth histograms
Overflow frequency analysis

HASH TABLE EFFICIENCY:

Client lookup performance
Hash collision statistics
Load balancing effectiveness
Access pattern analysis

DEBUGGING AND TROUBLESHOOTING:

EXTENSIVE DEBUG LOGGING: The function contains detailed debug printf statements for troubleshooting threading issues. This instrumentation helps diagnose:

Thread startup/shutdown problems
Shutdown detection timing issues
Sleep/wake cycle behavior
Statistics collection reliability

DEBUG OUTPUT INCLUDES:

Function entry/exit points
Loop iteration counts
Shutdown flag state changes
Sleep cycle progression
Statistics collection timing

ERROR HANDLING:

Graceful handling of data access failures
Continued operation if individual metrics fail
No fatal errors that would crash statistics thread
Degraded reporting if subsystems unavailable

PERFORMANCE CONSIDERATIONS:

30-second reporting interval balances visibility vs overhead
10ms sleep granularity provides responsive shutdown
Read-only access minimizes lock contention
Background processing doesn't affect real-time performance

Parameters

arg	Thread argument (unused - required by thread interface)

Returns: NULL on clean thread termination

Note: This function runs continuously until server shutdown; Debug printf statements help diagnose threading issues; All statistics collection is non-blocking and read-only

Warning: Thread must be properly joined to prevent resource leaks

Definition at line 332 of file stats.c.

                                     {
  (void)arg;
 
  while (!atomic_load(&g_server_should_exit)) {
    // Log buffer pool statistics every 10 seconds with fast exit checking (10ms intervals)
    for (int i = 0; i < 1000 && !atomic_load(&g_server_should_exit); i++) {
      platform_sleep_usec(10000); // 10ms sleep
    }
 
    // Check exit condition before proceeding with statistics logging
    // CRITICAL: Check multiple times to avoid accessing freed resources during shutdown
    if (atomic_load(&g_server_should_exit)) {
      break;
    }
 
    // Collect all statistics data first
#ifndef NDEBUG
    char lock_debug_info[512] = {0};
    // CRITICAL: Check exit condition again before accessing lock_debug
    // lock_debug might be destroyed during shutdown
    if (!atomic_load(&g_server_should_exit) && lock_debug_is_initialized()) {
      uint64_t total_acquired = 0, total_released = 0;
      uint32_t currently_held = 0;
      lock_debug_get_stats(&total_acquired, &total_released, &currently_held);
 
      safe_snprintf(lock_debug_info, sizeof(lock_debug_info),
                    "Historical Mutex/RWLock Statistics:\n"
                    "  Total locks acquired: %llu\n"
                    "  Total locks released: %llu\n"
                    "  Currently held: %u\n"
                    "  Net locks (acquired - released): %lld",
                    (unsigned long long)total_acquired, (unsigned long long)total_released, currently_held,
                    (long long)total_acquired - (long long)total_released);
    }
#endif
 
    // Collect client statistics
    // CRITICAL: Check exit condition again before accessing rwlock
    // rwlock might be destroyed during shutdown
    if (atomic_load(&g_server_should_exit)) {
      break;
    }
 
    rwlock_rdlock(&g_client_manager_rwlock);
    int active_clients = 0;
    int clients_with_audio = 0;
    int clients_with_video = 0;
    char client_details[2048] = {0};
    int client_details_len = 0;
 
    for (int i = 0; i < MAX_CLIENTS; i++) {
      if (atomic_load(&g_client_manager.clients[i].active)) {
        active_clients++;
        if (g_client_manager.clients[i].audio_queue) {
          clients_with_audio++;
        }
        if (g_client_manager.clients[i].outgoing_video_buffer) {
          clients_with_video++;
        }
      }
    }
 
    // Collect per-client details
    for (int i = 0; i < MAX_CLIENTS; i++) {
      client_info_t *client = &g_client_manager.clients[i];
      bool is_active = atomic_load(&client->active);
      uint32_t client_id_snapshot = atomic_load(&client->client_id);
 
      if (is_active && client_id_snapshot != 0) {
        // Check audio queue stats
        if (client->audio_queue) {
          uint64_t enqueued, dequeued, dropped;
          packet_queue_get_stats(client->audio_queue, &enqueued, &dequeued, &dropped);
          if (enqueued > 0 || dequeued > 0 || dropped > 0) {
            int len =
                snprintf(client_details + client_details_len, sizeof(client_details) - client_details_len,
                         "  Client %u audio queue: %llu enqueued, %llu dequeued, %llu dropped", client_id_snapshot,
                         (unsigned long long)enqueued, (unsigned long long)dequeued, (unsigned long long)dropped);
            if (len > 0 && client_details_len + len < (int)sizeof(client_details)) {
              client_details_len += len;
            }
          }
        }
        // Check video buffer stats
        if (client->outgoing_video_buffer) {
          video_frame_stats_t stats;
          video_frame_get_stats(client->outgoing_video_buffer, &stats);
          if (stats.total_frames > 0) {
            int len = snprintf(client_details + client_details_len, sizeof(client_details) - client_details_len,
                               "  Client %u video buffer: %llu frames, %llu dropped (%.1f%% drop rate)",
                               client_id_snapshot, (unsigned long long)stats.total_frames,
                               (unsigned long long)stats.dropped_frames, stats.drop_rate * 100.0f);
            if (len > 0 && client_details_len + len < (int)sizeof(client_details)) {
              client_details_len += len;
            }
          }
        }
      }
    }
    rwlock_rdunlock(&g_client_manager_rwlock);
 
    // Single comprehensive log statement
    if (client_details_len > 0) {
      log_info("Stats: Clients: %d, Audio: %d, Video: %d\n%s", active_clients, clients_with_audio, clients_with_video,
               client_details);
    }
  }
 
  log_server_stats();
 
  asciichat_error_stats_print();
 
  // Clean up thread-local error context before exit
  asciichat_errno_cleanup();
 
  return NULL;
}

References client_info::active, asciichat_errno_cleanup(), asciichat_error_stats_print(), client_info::audio_queue, client_info::client_id, client_manager_t::clients, video_frame_stats_t::drop_rate, video_frame_stats_t::dropped_frames, g_client_manager, g_client_manager_rwlock, g_server_should_exit, lock_debug_is_initialized(), log_info, log_server_stats(), MAX_CLIENTS, client_info::outgoing_video_buffer, packet_queue_get_stats(), platform_sleep_usec(), rwlock_rdlock, rwlock_rdunlock, safe_snprintf(), video_frame_stats_t::total_frames, and video_frame_get_stats().

Referenced by server_main().

◆ update_server_stats()

void update_server_stats ( void )

Update global server statistics (placeholder)

This function is intended to update the global server statistics structure with current performance metrics. Currently unimplemented but provides the framework for centralized statistics updates.

PLANNED FUNCTIONALITY:

Aggregate per-client frame counts into global totals
Calculate moving averages for FPS metrics
Update system health indicators
Compute performance trend data

IMPLEMENTATION STRATEGY:

Thread-safe updates using g_stats_mutex
Atomic operations for frequently updated counters
Efficient aggregation algorithms
Minimal performance impact

INTEGRATION POINTS:

Called by render threads when updating frame counts
Invoked by client management code for connection metrics
Used by packet queue systems for throughput tracking

Todo:
Implement comprehensive statistics aggregation

Note
Function currently serves as placeholder for future development

Definition at line 478 of file stats.c.

                               {
  // Aggregate statistics from all active clients
  uint64_t total_frames_sent = 0;
  uint64_t total_frames_dropped = 0;
 
  // Read-lock to safely iterate over all clients
  rwlock_rdlock(&g_client_manager_rwlock);
 
  for (int i = 0; i < MAX_CLIENTS; i++) {
    client_info_t *client = &g_client_manager.clients[i];
    if (atomic_load(&client->client_id) != 0 && atomic_load(&client->active)) {
      // Aggregate frames sent to all clients
      total_frames_sent += client->frames_sent;
 
      // Get dropped frame statistics from outgoing video buffer
      if (client->outgoing_video_buffer) {
        video_frame_stats_t stats;
        video_frame_get_stats(client->outgoing_video_buffer, &stats);
        total_frames_dropped += stats.dropped_frames;
      }
    }
  }
 
  rwlock_rdunlock(&g_client_manager_rwlock);
 
  // Update global statistics atomically
  mutex_lock(&g_stats_mutex);
  g_stats.frames_sent = total_frames_sent;
  g_stats.frames_dropped = total_frames_dropped;
 
  // Calculate frames_captured from frames_sent and frames_dropped
  // frames_captured = frames_sent + frames_dropped (total output frames)
  if (total_frames_sent > 0 || total_frames_dropped > 0) {
    g_stats.frames_captured = total_frames_sent + total_frames_dropped;
  }
 
  mutex_unlock(&g_stats_mutex);
}

References client_info::active, client_info::client_id, client_manager_t::clients, video_frame_stats_t::dropped_frames, server_stats_t::frames_captured, server_stats_t::frames_dropped, client_info::frames_sent, server_stats_t::frames_sent, g_client_manager, g_client_manager_rwlock, g_stats, g_stats_mutex, MAX_CLIENTS, mutex_lock, mutex_unlock, client_info::outgoing_video_buffer, rwlock_rdlock, rwlock_rdunlock, and video_frame_get_stats().

Variable Documentation

◆ g_stats

server_stats_t g_stats

extern

Global server statistics structure.

Maintains aggregated performance metrics for the entire server including frame processing rates, client counts, and system health indicators. All access to this structure must be protected by g_stats_mutex.

CONTENTS:

frames_captured: Total frames received from all clients
frames_sent: Total ASCII frames delivered to all clients
frames_dropped: Frames lost due to buffer overflows or processing delays
avg_capture_fps: Moving average of frame capture rate
avg_send_fps: Moving average of frame delivery rate

Definition at line 159 of file stats.c.

159{0};

Referenced by log_server_stats(), server_main(), and update_server_stats().

◆ g_stats_mutex

mutex_t g_stats_mutex

extern

Mutex protecting global server statistics.

Ensures thread-safe access to g_stats structure from both the statistics collection thread and any operational threads that update counters. Uses standard mutex (not reader-writer) due to relatively infrequent access.

Definition at line 168 of file stats.c.

168{0};

Referenced by log_server_stats(), server_main(), stats_cleanup(), stats_init(), and update_server_stats().

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ log_server_stats()

STATISTICS REPORTED:

THREAD SAFETY:

USAGE SCENARIOS:

OUTPUT FORMAT:

◆ stats_cleanup()

◆ stats_init()

◆ stats_logger_thread()

THREAD EXECUTION FLOW:

MONITORING METHODOLOGY:

PERFORMANCE METRICS COLLECTED:

DEBUGGING AND TROUBLESHOOTING:

ERROR HANDLING:

PERFORMANCE CONSIDERATIONS:

◆ update_server_stats()

PLANNED FUNCTIONALITY:

Variable Documentation

◆ g_stats

◆ g_stats_mutex