client.h File Reference

Per-client state management and lifecycle orchestration. More...

Go to the source code of this file.

Data Structures
struct	client_manager_t
	Global client manager structure for server-side client coordination. More...

Typedefs
typedef struct server_context_t	server_context_t

Functions
client_info_t *	add_transport_client (server_context_t *server_ctx, acip_transport_t *transport, const char *client_ip)
int	start_transport_client_threads (server_context_t *server_ctx, const char *client_id)
int	remove_client (server_context_t *server_ctx, const char *client_id)
client_info_t *	find_client_by_id (const char *client_id)
	Fast O(1) client lookup by ID using hash table.
void	cleanup_client_media_buffers (client_info_t *client)
void	cleanup_client_packet_queues (client_info_t *client)
void	initialize_client_info (client_info_t *client)

Variables
client_manager_t	g_client_manager
	Hash table entry for client packet dispatch.
rwlock_t	g_client_manager_rwlock
	Reader-writer lock protecting the global client manager.
bool	g_client_manager_rwlock_initialized

Detailed Description

Per-client state management and lifecycle orchestration.

This header provides server-specific client management functions. The client_info_t structure and network logging macros are defined in lib/network/client.h.

Definition in file src/server/client.h.

Typedef Documentation

server_context_t

typedef struct server_context_t server_context_t

Definition at line 17 of file src/server/client.h.

Function Documentation

add_transport_client()

client_info_t * add_transport_client	(	server_context_t *	server_ctx,
		acip_transport_t *	transport,
		const char *	client_ip )

Definition at line 412 of file src/server/client.c.

                                                                                                                      {
  if (!server_ctx || !transport || !client_ip) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
    return NULL;
  }
 
  rwlock_wrlock(&g_client_manager_rwlock);
 
  // Find empty slot - this is the authoritative check
  int slot = -1;
  int existing_count = 0;
  for (int i = 0; i < MAX_CLIENTS; i++) {
    if (slot == -1 && g_client_manager.clients[i].client_id[0] == '\0') {
      slot = i; // Take first available slot
    }
    // Count only active clients
    if (g_client_manager.clients[i].client_id[0] != '\0' && atomic_load_bool(&g_client_manager.clients[i].active)) {
      existing_count++;
    }
  }
 
  // Check if we've hit the configured max-clients limit (not the array size)
  if (existing_count >= GET_OPTION(max_clients)) {
    rwlock_wrunlock(&g_client_manager_rwlock);
    SET_ERRNO(ERROR_RESOURCE_EXHAUSTED, "Maximum client limit reached (%d/%d active clients)", existing_count,
              GET_OPTION(max_clients));
    log_error("Maximum client limit reached (%d/%d active clients)", existing_count, GET_OPTION(max_clients));
    return NULL;
  }
 
  if (slot == -1) {
    rwlock_wrunlock(&g_client_manager_rwlock);
    SET_ERRNO(ERROR_RESOURCE_EXHAUSTED, "No available client slots (all %d array slots are in use)", MAX_CLIENTS);
    log_error("No available client slots (all %d array slots are in use)", MAX_CLIENTS);
    return NULL;
  }
 
  // Update client_count to match actual count before adding new client
  g_client_manager.client_count = existing_count;
 
  // Generate unique client ID for transport client (noun only, without counter or port)
  char new_client_id[MAX_CLIENT_ID_LEN];
  if (generate_client_id(new_client_id, sizeof(new_client_id)) != 0) {
    rwlock_wrunlock(&g_client_manager_rwlock);
    log_error("Failed to generate unique client ID for transport client");
    return NULL;
  }
 
  // Initialize client
  client_info_t *client = &g_client_manager.clients[slot];
 
  server_client_initialize_transport_slot(server_ctx, client, transport, new_client_id, client_ip, slot);
 
  if (server_client_allocate_transport_buffers(client, new_client_id) != ASCIICHAT_OK ||
      server_client_initialize_transport_sync(client, new_client_id) != ASCIICHAT_OK) {
    goto error_cleanup_transport;
  }
 
  g_client_manager.client_count = existing_count + 1; // We just added a client
  log_debug("Client count updated: now %d clients (added transport client_id=%s to slot %d)",
            g_client_manager.client_count, new_client_id, slot);
 
  // Add client to uthash table for O(1) lookup
  HASH_ADD_STR(g_client_manager.clients_by_id, client_id, client);
  log_debug("Added transport client %s to uthash table", new_client_id);
 
  // Release the write lock IMMEDIATELY after adding to hash table
  // The client is fully initialized before other threads can look it up.
  rwlock_wrunlock(&g_client_manager_rwlock);
 
  // Register client with session_host (for discovery mode support)
  // transport clients use INVALID_SOCKET_VALUE since they don't have a TCP socket
  if (server_ctx->session_host) {
    client->session_client_id =
        session_host_add_client(server_ctx->session_host, NULL, ACIP_TRANSPORT_BORROWED, client_ip, 0);
    if (client->session_client_id == 0) {
      log_warn("Failed to register transport client %s with session_host", new_client_id);
    } else {
      log_debug("transport client %s registered with session_host as %u", new_client_id, client->session_client_id);
    }
  }
 
  // Broadcast server state to ALL clients AFTER the new client is fully set up
  // This notifies all clients (including the new one) about the updated grid
  broadcast_server_state_to_all_clients();
 
  return client;
 
error_cleanup_transport:
  // Clean up all partially allocated resources for transport client
  // NOTE: This label is reached when allocation or initialization fails BEFORE
  // the client is added to the hash table. Don't call remove_client() here.
  cleanup_client_all_buffers(client);
  memset(client, 0, sizeof(*client));
  rwlock_wrunlock(&g_client_manager_rwlock);
  return NULL;
}

References ACIP_TRANSPORT_BORROWED, ASCIICHAT_OK, broadcast_server_state_to_all_clients(), ERROR_INVALID_PARAM, ERROR_RESOURCE_EXHAUSTED, g_client_manager, g_client_manager_rwlock, generate_client_id(), GET_OPTION, log_debug, log_error, log_warn, MAX_CLIENT_ID_LEN, MAX_CLIENTS, rwlock_wrlock, rwlock_wrunlock, client_info::session_client_id, server_context_t::session_host, session_host_add_client(), and SET_ERRNO.

cleanup_client_media_buffers()

void cleanup_client_media_buffers

(

client_info_t *

client

)

Definition at line 804 of file src/server/client.c.

                                                         {
  if (!client) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Client is NULL");
    return;
  }
 
  if (client->digital_rain) {
    digital_rain_destroy(client->digital_rain);
    client->digital_rain = NULL;
  }
 
  if (client->incoming_video_buffer) {
    video_frame_buffer_destroy(client->incoming_video_buffer);
    client->incoming_video_buffer = NULL;
  }
 
  if (client->incoming_audio_buffer) {
    audio_ring_buffer_destroy(client->incoming_audio_buffer);
    client->incoming_audio_buffer = NULL;
  }
 
  // Clean up Opus decoder
  if (client->opus_decoder) {
    opus_codec_destroy((opus_codec_t *)client->opus_decoder);
    client->opus_decoder = NULL;
  }
 
  // Clean up video decoder (persistent per-client decoder)
  if (client->video_decoder_ctx) {
    avcodec_free_context((AVCodecContext **)&client->video_decoder_ctx);
    client->video_decoder_ctx = NULL;
  }
  if (client->video_decode_frame) {
    av_frame_free((AVFrame **)&client->video_decode_frame);
    client->video_decode_frame = NULL;
  }
  if (client->video_rgb_frame) {
    av_frame_free((AVFrame **)&client->video_rgb_frame);
    client->video_rgb_frame = NULL;
  }
  if (client->video_sws_ctx) {
    sws_freeContext(client->video_sws_ctx);
    client->video_sws_ctx = NULL;
  }
}

References audio_ring_buffer_destroy(), client_info::digital_rain, digital_rain_destroy(), ERROR_INVALID_PARAM, client_info::incoming_audio_buffer, client_info::incoming_video_buffer, opus_codec_destroy(), client_info::opus_decoder, SET_ERRNO, client_info::video_decode_frame, client_info::video_decoder_ctx, video_frame_buffer_destroy(), client_info::video_rgb_frame, and client_info::video_sws_ctx.

cleanup_client_packet_queues()

void cleanup_client_packet_queues

(

client_info_t *

client

)

Definition at line 850 of file src/server/client.c.

                                                         {
  if (!client)
    return;
 
  // Async dispatch: clean up received packet queue
 
  // Video now uses double buffer, cleaned up in cleanup_client_media_buffers
}

find_client_by_id()

client_info_t * find_client_by_id

(

const char *

client_id

)

Fast O(1) client lookup by ID using hash table.

This is the primary method for locating clients throughout the server. It uses a hash table for constant-time lookups regardless of client count, making it suitable for high-performance operations like rendering and stats.

PERFORMANCE CHARACTERISTICS:

• Time Complexity: O(1) average case, O(n) worst case (hash collision)
• Space Complexity: O(1)
• Thread Safety: Hash table is internally thread-safe for lookups

USAGE PATTERNS:

• Called by render threads to find target clients for frame generation
• Used by protocol handlers to locate clients for packet processing
• Stats collection for per-client performance monitoring

Parameters

client_id

Unique identifier for the client (0 is invalid)

Returns

Pointer to client_info_t if found, NULL if not found or invalid ID

Note

Does not require external locking - hash table provides thread safety

Returns direct pointer to client struct - caller should use snapshot pattern

Definition at line 272 of file src/server/client.c.

                                                        {
  if (!client_id || client_id[0] == '\0') {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid client ID");
    return NULL;
  }
 
  // Protect uthash lookup with read lock to prevent concurrent access issues
  rwlock_rdlock(&g_client_manager_rwlock);
 
  client_info_t *result = NULL;
  HASH_FIND_STR(g_client_manager.clients_by_id, client_id, result);
 
  rwlock_rdunlock(&g_client_manager_rwlock);
 
  if (!result) {
    log_warn("Client not found for ID %s", client_id);
  }
 
  return result;
}

References ERROR_INVALID_PARAM, g_client_manager, g_client_manager_rwlock, log_warn, rwlock_rdlock, rwlock_rdunlock, and SET_ERRNO.

Referenced by start_transport_client_threads().

initialize_client_info()

void initialize_client_info

(

client_info_t *

client

)

remove_client()

int remove_client	(	server_context_t *	server_ctx,
		const char *	client_id )

Definition at line 708 of file src/server/client.c.

                                                                       {
  if (!server_ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Cannot remove client %s: NULL server_ctx", client_id);
    return -1;
  }
 
  server_client_removal_t removal = {0};
  if (server_client_begin_removal(server_ctx, client_id, &removal) != ASCIICHAT_OK) {
    return -1;
  }
  if (!removal.client) {
    return 0; // Another thread is already removing this client.
  }
 
  if (stop_client_render_threads(removal.client) != ASCIICHAT_OK)
    return -1;
  if (!server_client_finish_removal(client_id, &removal)) {
    return 0;
  }
 
  broadcast_server_state_to_all_clients();
  return 0;
}

References ASCIICHAT_OK, broadcast_server_state_to_all_clients(), server_client_removal_t::client, ERROR_INVALID_PARAM, SET_ERRNO, and stop_client_render_threads().

start_transport_client_threads()

int start_transport_client_threads	(	server_context_t *	server_ctx,
		const char *	client_id )

Definition at line 788 of file src/server/client.c.

                                                                                        {
  if (!server_ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Server context is NULL");
    return -1;
  }
 
  client_info_t *client = find_client_by_id(client_id);
  if (!client) {
    SET_ERRNO(ERROR_NOT_FOUND, "Client %s not found", client_id);
    return -1;
  }
 
  log_debug("Starting application workers for client %s...", client_id);
  return start_client_threads(server_ctx, client);
}

References ERROR_INVALID_PARAM, ERROR_NOT_FOUND, find_client_by_id(), log_debug, and SET_ERRNO.

Variable Documentation

g_client_manager

client_manager_t g_client_manager

extern

Hash table entry for client packet dispatch.

Global client manager singleton - central coordination point

This is the primary data structure for managing all connected clients. It serves as the bridge between main.c's connection accept loop and the per-client threading architecture.

STRUCTURE COMPONENTS:

• clients[]: Array backing storage for client_info_t structs
• client_hashtable: O(1) lookup table for client_id -> client_info_t*
• client_count: Current number of active clients
• mutex: Legacy mutex (mostly replaced by rwlock)
• next_client_id: Monotonic counter for unique client identification

THREAD SAFETY: Protected by g_client_manager_rwlock for concurrent access

Definition at line 193 of file src/server/client.c.

g_client_manager_rwlock

rwlock_t g_client_manager_rwlock

extern

Reader-writer lock protecting the global client manager.

This lock enables high-performance concurrent access patterns:

• Multiple threads can read client data simultaneously (stats, rendering)
• Only one thread can modify client data at a time (add/remove operations)
• Eliminates contention between read-heavy operations

USAGE PATTERN:

• Read operations: rwlock_rdlock() for client lookups, stats gathering
• Write operations: rwlock_wrlock() for add_transport_client(), remove_client()
• Always acquire THIS lock before per-client mutexes (lock ordering)

Definition at line 208 of file src/server/client.c.

{0};

g_client_manager_rwlock_initialized

bool g_client_manager_rwlock_initialized

extern

Track whether g_client_manager_rwlock was successfully initialized.

Definition at line 211 of file src/server/client.c.

Referenced by broadcast_server_state_to_all_clients().