parallel_connect.h File Reference

Parallel IPv4/IPv6 connection with race-to-connect semantics. More...

Go to the source code of this file.

Data Structures
struct	parallel_connect_config_t

Typedefs
typedef bool(*	parallel_connect_should_exit_fn) (void *user_data)
	When code needs to work with parallel connect config, it keeps hostname, port, timeout_ms, should_exit_callback here instead of scattering it across globals. Initialization establishes the handles and sizes; teardown must release any allocation, lock, thread, or callback context recorded in those fields.

Functions
asciichat_error_t	parallel_connect (const parallel_connect_config_t *config, socket_t *out_socket)

Detailed Description

Parallel IPv4/IPv6 connection with race-to-connect semantics.

Attempts IPv4 and IPv6 connections in parallel and returns the first successful socket, closing the loser. Handles unreachable addresses gracefully without blocking on timeouts.

Definition in file parallel_connect.h.

Typedef Documentation

parallel_connect_should_exit_fn

typedef bool(* parallel_connect_should_exit_fn) (void *user_data)

When code needs to work with parallel connect config, it keeps hostname, port, timeout_ms, should_exit_callback here instead of scattering it across globals. Initialization establishes the handles and sizes; teardown must release any allocation, lock, thread, or callback context recorded in those fields.

Callback type to check if connection should be abandoned

Called periodically by connection threads to allow graceful shutdown. Should return true if connection attempts should stop immediately.

Parameters

user_data

Opaque pointer provided by caller

Returns

true to abandon connection attempts, false to continue

Definition at line 27 of file parallel_connect.h.

Function Documentation

parallel_connect()

asciichat_error_t parallel_connect	(	const parallel_connect_config_t *	config,
		socket_t *	out_socket )

Connect to hostname with parallel IPv4/IPv6 attempts

Resolves hostname and attempts IPv4 and IPv6 connections in parallel. Returns the first successful socket; the losing connection is closed. Each connection attempt is non-blocking with select() timeout.

Parameters

config	Connection configuration
out_socket	Pointer to receive winning socket

Returns

ASCIICHAT_OK on success, ERROR_* on failure

Note

Caller is responsible for closing the returned socket

Timeout applies to each connection attempt independently

Definition at line 182 of file parallel_connect.c.

                                                                                                  {
  ASCII_OTEL_SCOPE(PARALLEL_CONNECT);
  if (!config || !out_socket) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "config or out_socket is NULL");
  }
 
  *out_socket = INVALID_SOCKET_VALUE;
 
  char ascii_hostname[HOSTNAME_BUFFER_SIZE];
  asciichat_error_t normalized = hostname_to_ascii(config->hostname, ascii_hostname, sizeof(ascii_hostname));
  if (normalized != ASCIICHAT_OK)
    return normalized;
 
  // Resolve hostname
  log_debug("PCONN: Resolving %s:%d", config->hostname, config->port);
 
  struct addrinfo hints;
  struct addrinfo *result = NULL;
  memset(&hints, 0, sizeof(hints));
  hints.ai_family = AF_UNSPEC;
  hints.ai_socktype = SOCK_STREAM;
 
  char port_str[NETWORK_PARALLEL_CONNECT_PORT_BUFFER_SIZE];
  safe_snprintf(port_str, sizeof(port_str), "%d", config->port);
 
  int gai_result;
  {
    ASCII_OTEL_SCOPE(DNS_RESOLVE);
    if (otel_scope.retained)
      gotel_attr_string(&otel_scope.scope, "dns.question.name", config->hostname);
    gai_result = getaddrinfo(ascii_hostname, port_str, &hints, &result);
    if (gai_result && otel_scope.retained)
      gotel_error(&otel_scope.scope, "dns.error", "DNS lookup failed");
  }
  if (gai_result != 0) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to resolve %s: %s", config->hostname, gai_strerror(gai_result));
  }
 
  // Find first IPv4 and IPv6 addresses
  struct addrinfo *ipv4_addr = NULL;
  struct addrinfo *ipv6_addr = NULL;
 
  for (struct addrinfo *rp = result; rp != NULL; rp = rp->ai_next) {
    if (rp->ai_family == AF_INET && !ipv4_addr) {
      ipv4_addr = rp;
      log_debug("PCONN: Found IPv4 address");
    } else if (rp->ai_family == AF_INET6 && !ipv6_addr) {
      ipv6_addr = rp;
      log_debug("PCONN: Found IPv6 address");
    }
    if (ipv4_addr && ipv6_addr)
      break;
  }
 
  // Need at least one address
  if (!ipv4_addr && !ipv6_addr) {
    freeaddrinfo(result);
    return SET_ERRNO(ERROR_NETWORK, "No IPv4 or IPv6 addresses found for %s", config->hostname);
  }
 
  // Shared state
  mutex_t lock;
  cond_t signal;
  mutex_init(&lock, "parallel_connect");
  cond_init(&signal, "parallel_connect");
 
  volatile socket_t winner_socket = INVALID_SOCKET_VALUE;
  volatile bool winner_found = false;
 
  // An unavailable address family never starts a worker. Its cleanup must not
  // close descriptor zero, which can subsequently be reused by the event loop.
  connection_attempt_t ipv4_attempt = {.socket = INVALID_SOCKET_VALUE};
  connection_attempt_t ipv6_attempt = {.socket = INVALID_SOCKET_VALUE};
  platform_thread_t ipv4_thread;
  platform_thread_t ipv6_thread;
 
  thread_init(&ipv4_thread);
  thread_init(&ipv6_thread);
 
  // Start IPv4 attempt if available
  if (ipv4_addr) {
    ipv4_attempt.family = AF_INET;
    ipv4_attempt.family_name = "IPv4";
    ipv4_attempt.timeout_ms = config->timeout_ms;
    ipv4_attempt.winner_socket = &winner_socket;
    ipv4_attempt.winner_found = &winner_found;
    ipv4_attempt.lock = &lock;
    ipv4_attempt.signal = &signal;
    ipv4_attempt.should_exit_callback = config->should_exit_callback;
    ipv4_attempt.callback_data = config->callback_data;
    memcpy(&ipv4_attempt.addr, ipv4_addr->ai_addr, ipv4_addr->ai_addrlen);
    ipv4_attempt.addr_len = ipv4_addr->ai_addrlen;
 
    platform_thread_create(&ipv4_thread, "connect_ipv4", attempt_connection_thread, &ipv4_attempt);
  }
 
  // Start IPv6 attempt if available
  if (ipv6_addr) {
    ipv6_attempt.family = AF_INET6;
    ipv6_attempt.family_name = "IPv6";
    ipv6_attempt.timeout_ms = config->timeout_ms;
    ipv6_attempt.winner_socket = &winner_socket;
    ipv6_attempt.winner_found = &winner_found;
    ipv6_attempt.lock = &lock;
    ipv6_attempt.signal = &signal;
    ipv6_attempt.should_exit_callback = config->should_exit_callback;
    ipv6_attempt.callback_data = config->callback_data;
    memcpy(&ipv6_attempt.addr, ipv6_addr->ai_addr, ipv6_addr->ai_addrlen);
    ipv6_attempt.addr_len = ipv6_addr->ai_addrlen;
 
    platform_thread_create(&ipv6_thread, "connect_ipv6", attempt_connection_thread, &ipv6_attempt);
  }
 
  // Wait for winner or both to finish
  uint32_t max_wait_ms = config->timeout_ms + 1000;
  uint32_t elapsed_ms = 0;
 
  mutex_lock(&lock);
  while (!winner_found && elapsed_ms < max_wait_ms) {
    cond_timedwait(&signal, &lock, 100 * NS_PER_MS_INT);
    elapsed_ms += 100;
 
    // Check if both are done
    if (ipv4_addr && ipv6_addr) {
      if (ipv4_attempt.done && ipv6_attempt.done) {
        break;
      }
    } else if ((ipv4_addr && ipv4_attempt.done) || (ipv6_addr && ipv6_attempt.done)) {
      break;
    }
  }
  mutex_unlock(&lock);
 
  // Join threads (must wait for both to complete before returning)
  // The threads access shared state on our stack, so we cannot return until they're done
  if (thread_is_initialized(&ipv4_thread)) {
    thread_join(&ipv4_thread, NULL);
  }
  if (thread_is_initialized(&ipv6_thread)) {
    thread_join(&ipv6_thread, NULL);
  }
 
  // Close any remaining sockets
  if (ipv4_attempt.socket != INVALID_SOCKET_VALUE) {
    socket_close(ipv4_attempt.socket);
  }
  if (ipv6_attempt.socket != INVALID_SOCKET_VALUE) {
    socket_close(ipv6_attempt.socket);
  }
 
  // Cleanup
  mutex_destroy(&lock);
  cond_destroy(&signal);
  freeaddrinfo(result);
 
  // Check result
  if (winner_socket == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_NETWORK, "Failed to connect to %s:%d (both IPv4 and IPv6 failed)", config->hostname,
                     config->port);
  }
 
  *out_socket = (socket_t)winner_socket;
  log_info("PCONN: Successfully connected to %s:%d", config->hostname, config->port);
  return ASCIICHAT_OK;
}

References connection_attempt_t::addr, connection_attempt_t::addr_len, ASCII_OTEL_SCOPE, ASCIICHAT_OK, connection_attempt_t::callback_data, parallel_connect_config_t::callback_data, connection_attempt_t::done, ERROR_INVALID_PARAM, ERROR_NETWORK, connection_attempt_t::family, connection_attempt_t::family_name, parallel_connect_config_t::hostname, HOSTNAME_BUFFER_SIZE, hostname_to_ascii(), connection_attempt_t::lock, log_debug, log_info, NETWORK_PARALLEL_CONNECT_PORT_BUFFER_SIZE, NS_PER_MS_INT, parallel_connect_config_t::port, safe_snprintf(), SET_ERRNO, connection_attempt_t::should_exit_callback, parallel_connect_config_t::should_exit_callback, connection_attempt_t::signal, connection_attempt_t::socket, connection_attempt_t::timeout_ms, parallel_connect_config_t::timeout_ms, connection_attempt_t::winner_found, and connection_attempt_t::winner_socket.