consensus_integration.h File Reference

Integration helpers for session consensus across modes. More...

Go to the source code of this file.

Functions
asciichat_error_t	consensus_get_discovery_callbacks (void *context, session_consensus_callbacks_t *out_callbacks)
	Get consensus callbacks configured for discovery mode.
asciichat_error_t	consensus_create_for_discovery (const uint8_t session_id[SESSION_ID_SIZE], const uint8_t my_id[SESSION_ID_SIZE], const uint8_t participant_ids[MAX_SESSION_PARTICIPANTS][SESSION_ID_SIZE], int num_participants, void *discovery_context, session_consensus_t **out_consensus)
	Create session consensus for discovery mode.
uint32_t	consensus_suggest_timeout_ms (session_consensus_t *consensus, uint32_t current_timeout_ms)
	Suggest next timeout for consensus processing.

Detailed Description

Integration helpers for session consensus across modes.

Provides example integration patterns and helpers for modes to use the ring consensus abstraction. Shows how different modes (discovery, server, client, acds) would integrate consensus with their specific transport and metrics collection mechanisms.

Definition in file consensus_integration.h.

Function Documentation

consensus_create_for_discovery()

asciichat_error_t consensus_create_for_discovery	(	const uint8_t	session_id[SESSION_ID_SIZE],
		const uint8_t	my_id[SESSION_ID_SIZE],
		const uint8_t	participant_ids[MAX_SESSION_PARTICIPANTS][SESSION_ID_SIZE],
		int	num_participants,
		void *	discovery_context,
		session_consensus_t **	out_consensus )

Create session consensus for discovery mode.

Convenience function showing the typical pattern for creating consensus in discovery mode. Calls consensus_create() with discovery-specific callback configuration.

Real usage:

• When ACDS gives us participant list -> create consensus
• Call consensus_process() in discovery_session_process() loop
• Route RING_* packets to consensus handlers
• Update host on election results

Parameters

session_id	Session identifier (16 bytes) - informational
my_id	Our participant ID (16 bytes)
participant_ids	Array of all participant IDs (up to 128)
num_participants	Count of participants
discovery_context	Discovery session context (opaque)
out_consensus	Output: Created consensus handle

Returns

ASCIICHAT_OK on success, error code otherwise

Create session consensus for discovery mode.

Shows how a mode would create the consensus abstraction. This is a standalone example - real discovery session would call this when transitioning to ACTIVE state if participants found.

Parameters

session_id	Session identifier (16 bytes)
my_id	My participant identifier (16 bytes)
participant_ids	Array of all participant IDs (up to 128)
num_participants	Count of participants
discovery_context	Mode-specific context (e.g., discovery_session_t)
out_consensus	Output: Created consensus handle

Returns

ASCIICHAT_OK on success

Definition at line 154 of file consensus_integration.c.

                                                                                                                   {
  (void)session_id; // Informational only, not needed by consensus itself
 
  if (!my_id || !participant_ids || !discovery_context || !out_consensus) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  if (num_participants < 1 || num_participants > MAX_SESSION_PARTICIPANTS) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid participant count: %d", num_participants);
  }
 
  // Determine if we're the ring leader (for now, assume not - ACDS would manage this)
  // In a real implementation, ACDS would tell us our position in the ring
  bool is_leader = false; // This would be determined by ACDS
 
  // Get callbacks configured for our mode
  session_consensus_callbacks_t callbacks = {0};
  asciichat_error_t err = consensus_get_discovery_callbacks(discovery_context, &callbacks);
  if (err != ASCIICHAT_OK) {
    return err;
  }
 
  // Create consensus with the callbacks
  return session_consensus_create(my_id, is_leader, participant_ids, num_participants, &callbacks, out_consensus);
}

References ASCIICHAT_OK, consensus_get_discovery_callbacks(), ERROR_INVALID_PARAM, MAX_SESSION_PARTICIPANTS, session_consensus_create(), session_id, SESSION_ID_SIZE, and SET_ERRNO.

consensus_get_discovery_callbacks()

asciichat_error_t consensus_get_discovery_callbacks	(	void *	context,
		session_consensus_callbacks_t *	out_callbacks )

Get consensus callbacks configured for discovery mode.

Returns a callback structure showing how discovery mode would integrate consensus:

• Send packets via ACDS relay
• Handle election by storing host info
• Measure NAT quality metrics

Parameters

context	Opaque context (typically discovery_session_t*)
out_callbacks	Output: Configured callback structure

Returns

ASCIICHAT_OK on success, error code otherwise

Get consensus callbacks configured for discovery mode.

Returns a properly configured callback structure for session consensus. The returned callbacks encapsulate the discovery session's packet sending, election handling, and metrics measurement capabilities.

Parameters

context	Discovery session pointer (void* for genericity)
out_callbacks	Output: Configured callbacks

Returns

ASCIICHAT_OK on success

Definition at line 123 of file consensus_integration.c.

                                                                                                                 {
  if (!context || !out_callbacks) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: context=%p, out_callbacks=%p", context, out_callbacks);
  }
 
  // Configure callbacks for discovery mode
  out_callbacks->send_packet = consensus_send_via_discovery;
  out_callbacks->on_election = consensus_on_election_result;
  out_callbacks->get_metrics = consensus_get_metrics;
  out_callbacks->election = NULL; // Use default election algorithm
  out_callbacks->context = context;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, session_consensus_callbacks_t::context, session_consensus_callbacks_t::election, ERROR_INVALID_PARAM, session_consensus_callbacks_t::get_metrics, session_consensus_callbacks_t::on_election, session_consensus_callbacks_t::send_packet, and SET_ERRNO.

Referenced by consensus_create_for_discovery().

consensus_suggest_timeout_ms()

uint32_t consensus_suggest_timeout_ms	(	session_consensus_t *	consensus,
		uint32_t	current_timeout_ms )

Suggest next timeout for consensus processing.

Helper for modes to schedule consensus processing appropriately. Returns the minimum of consensus deadline or current timeout.

Usage in mode's main loop:

uint32_t suggested_timeout = consensus_suggest_timeout_ms(consensus, current_timeout);
// Use suggested_timeout in event wait instead of current_timeout

Parameters

consensus	Consensus handle (NULL safe)
current_timeout_ms	Current event loop timeout in milliseconds

Returns

Suggested next timeout in milliseconds

Suggest next timeout for consensus processing.

Useful for modes to schedule when they should call consensus_process() next.

Parameters

consensus	Consensus handle
current_timeout_ms	Current event loop timeout in milliseconds

Returns

Suggested next timeout in milliseconds

Definition at line 191 of file consensus_integration.c.

                                                                                                   {
  if (!consensus) {
    return current_timeout_ms;
  }
 
  // Get time until next round in nanoseconds
  uint64_t time_to_next_ns = session_consensus_time_until_next_round(consensus);
 
  // Convert to milliseconds
  uint64_t time_to_next_ms = time_ns_to_ms(time_to_next_ns);
 
  // Return minimum of consensus deadline or current timeout
  if (time_to_next_ms == 0) {
    return 0; // Consensus needs immediate attention
  }
 
  if (time_to_next_ms < current_timeout_ms) {
    return (uint32_t)time_to_next_ms;
  }
 
  return current_timeout_ms;
}

References session_consensus_time_until_next_round().