Connection Keepalive

💓 Ping/pong keepalive and timeout detection More...

Files
file	keepalive.c
	💓 Client keepalive: periodic ping/pong exchange for reliable connection failure detection
file	keepalive.h
	ascii-chat Client Connection Keepalive Management Interface

Functions
	__attribute__ ((unused))
	Ping/keepalive thread handle.
int	keepalive_start_thread ()
	Start keepalive/ping thread.
void	keepalive_stop_thread ()
	Stop keepalive/ping thread.
bool	keepalive_thread_exited ()
	Check if keepalive thread has exited.

Detailed Description

💓 Ping/pong keepalive and timeout detection

Connection Keepalive

Overview

The keepalive subsystem manages connection liveness by sending periodic ping packets and detecting pong timeouts to identify dead connections.

Implementation: src/client/keepalive.c, src/client/keepalive.h

Configuration

Timing Parameters:

• Ping interval: 5 seconds
• Pong timeout: 30 seconds
• Timeout triggers reconnection

Keepalive Thread

static void *keepalive_thread_func(void *arg)
{
  (void)arg;
 
  time_t last_pong_time = time(NULL);
 
  while (!should_exit() && server_connection_is_active()) {
    // Send ping packet
    send_packet_to_server(PACKET_TYPE_PING, NULL, 0,
                         server_connection_get_client_id());
 
    // Wait for ping interval
    for (int i = 0; i < PING_INTERVAL_SEC * 10; i++) {
      if (!should_exit() && !server_connection_is_active()) break;
      platform_sleep_usec(100000);  // 100ms
    }
 
    // Check pong timeout
    time_t now = time(NULL);
    if (now - last_pong_time > PONG_TIMEOUT_SEC) {
      log_warn("Pong timeout (%d seconds) - connection may be dead", PONG_TIMEOUT_SEC);
      server_connection_lost();
      break;
    }
  }
 
  atomic_store(&g_keepalive_thread_exited, true);
  return NULL;
}

Pong Recording

void keepalive_record_pong(void)
{
  // Update last pong time (called by protocol handler)
  g_last_pong_time = time(NULL);
}

See also

src/client/keepalive.c

src/client/keepalive.h

Client Overview

Function Documentation

__attribute__()

__attribute__

(

(unused)

)

#include <keepalive.c>

Ping/keepalive thread handle.

Thread handle for the background thread that sends periodic PING packets to detect connection health. Created during connection establishment, joined during shutdown. Ping interval in seconds (must be less than server timeout) Sleep interval for ping timing loop (1 second) Main ping/keepalive thread function

Implements periodic ping transmission to maintain connection health. Monitors connection state and coordinates with global shutdown logic.

Ping Loop Operation:

1. Check global shutdown flags and connection status
2. Validate socket file descriptor before transmission
3. Send ping packet to server via connection module
4. Handle transmission errors and connection loss detection
5. Sleep with interruptible timing for responsive shutdown
6. Repeat until connection loss or shutdown requested

Error Handling:

• Socket validation failures trigger clean thread exit
• Ping transmission failures signal connection loss
• Network errors handled gracefully without panic
• Thread coordination respects shutdown timing

Parameters

arg	Unused thread argument

Returns

NULL on thread exit

Definition at line 89 of file keepalive.c.

                                         {
  (void)arg;
 
#ifdef DEBUG_THREADS
  log_debug("Ping thread started");
#endif
 
  // FPS tracking for keepalive thread (ping sent every 3 seconds = ~0.33 Hz)
  static fps_t fps_tracker = {0};
  static bool fps_tracker_initialized = false;
  if (!fps_tracker_initialized) {
    fps_init_with_interval(&fps_tracker, 1, "KEEPALIVE", 10000000ULL); // 1 "frame" per 3 seconds, report every 10s
    fps_tracker_initialized = true;
  }
 
  // Startup grace period: Allow connection initialization to complete before checking state
  // Prevents race condition where thread spawns before transport is fully configured
  platform_sleep_ms(100);
 
  while (!should_exit() && !server_connection_is_lost()) {
    // Check if connection is still active before sending
    if (!server_connection_is_active()) {
      log_debug("Connection inactive, exiting ping thread");
      break;
    }
 
    // Check if session rekeying should be triggered
    if (crypto_client_should_rekey()) {
      log_debug("Rekey threshold reached, initiating session rekey");
      if (crypto_client_initiate_rekey() < 0) {
        log_error("Failed to initiate rekey");
        // Don't break - continue with keepalive, rekey will be retried
      }
    }
 
    // Send ping packet every PING_INTERVAL_SECONDS to keep connection alive
    // Server timeout is 5 seconds, so 3-second pings provide safety margin
    if (threaded_send_ping_packet() < 0) {
      log_debug("Failed to send ping packet");
      // Set connection lost flag so main loop knows to reconnect
      server_connection_lost();
      break;
    }
 
    // Track ping for FPS reporting
    struct timespec current_time;
    (void)clock_gettime(CLOCK_MONOTONIC, &current_time);
    fps_frame(&fps_tracker, &current_time, "ping sent");
 
    // Sleep with early wake capability for responsive shutdown
    // Break sleep into 1-second intervals to check shutdown flags
    for (int i = 0;
         i < PING_INTERVAL_SECONDS && !should_exit() && !server_connection_is_lost() && server_connection_is_active();
         i++) {
      platform_sleep_usec(PING_SLEEP_INTERVAL_SECONDS * 1000 * 1000); // 1 second
    }
  }
 
#ifdef DEBUG_THREADS
  log_debug("Ping thread stopped");
#endif
 
  atomic_store(&g_ping_thread_exited, true);
 
  // Clean up thread-local error context before exit
  asciichat_errno_cleanup();
 
  return NULL;
}

References asciichat_errno_cleanup(), crypto_client_initiate_rekey(), crypto_client_should_rekey(), fps_frame(), fps_init_with_interval(), log_debug, log_error, PING_INTERVAL_SECONDS, PING_SLEEP_INTERVAL_SECONDS, platform_sleep_ms(), platform_sleep_usec(), server_connection_is_active(), server_connection_is_lost(), server_connection_lost(), should_exit(), and threaded_send_ping_packet().

keepalive_start_thread()

int keepalive_start_thread

(

)

#include <keepalive.c>

Start keepalive/ping thread.

Start keepalive/ping thread

Creates and starts the ping thread for connection keepalive. Must be called after successful server connection establishment.

Returns

0 on success, negative on error

0 on success, negative on error

Definition at line 234 of file keepalive.c.

                             {
  if (g_ping_thread_created) {
    log_warn("Ping thread already created");
    return 0;
  }
 
  // Start ping thread for keepalive
  atomic_store(&g_ping_thread_exited, false);
  if (thread_pool_spawn(g_client_worker_pool, ping_thread_func, NULL, 3, "keepalive_ping") != ASCIICHAT_OK) {
    log_error("Failed to spawn ping thread in worker pool");
    LOG_ERRNO_IF_SET("Ping thread creation failed");
    return -1;
  }
 
  g_ping_thread_created = true;
  return 0;
}

References ASCIICHAT_OK, g_client_worker_pool, LOG_ERRNO_IF_SET, log_error, log_warn, and thread_pool_spawn().

Referenced by protocol_start_connection().

keepalive_stop_thread()

void keepalive_stop_thread

(

)

#include <keepalive.c>

Stop keepalive/ping thread.

Stop keepalive/ping thread

Gracefully stops the ping thread and cleans up resources. Safe to call multiple times.

Definition at line 260 of file keepalive.c.

                             {
  if (!g_ping_thread_created) {
    return;
  }
 
  // Don't call signal_exit() here - that's for global shutdown only!
  // The ping thread monitors connection state and will exit when connection is lost
 
  // Wait for thread to exit gracefully
  int wait_count = 0;
  while (wait_count < 20 && !atomic_load(&g_ping_thread_exited)) {
    platform_sleep_usec(100000); // 100ms
    wait_count++;
  }
 
  if (!atomic_load(&g_ping_thread_exited)) {
    log_warn("Ping thread not responding - will be joined by thread pool");
  }
 
  // Thread will be joined by thread_pool_stop_all() in protocol_stop_connection()
  g_ping_thread_created = false;
 
  log_info("Ping thread stopped and joined");
}

References log_info, log_warn, and platform_sleep_usec().

Referenced by protocol_stop_connection().

keepalive_thread_exited()

bool keepalive_thread_exited

(

)

#include <keepalive.c>

Check if keepalive thread has exited.

Check if keepalive thread has exited

Returns

true if thread has exited, false otherwise

true if thread exited, false otherwise

Definition at line 292 of file keepalive.c.

                               {
  return atomic_load(&g_ping_thread_exited);
}