consensus.c File Reference

Mode-agnostic ring consensus abstraction implementation. More...

Go to the source code of this file.

Data Structures
struct	session_consensus
	Session consensus handle - wraps all consensus modules. More...

Typedefs
typedef struct session_consensus	session_consensus_t
	Session consensus handle - wraps all consensus modules.

Functions
asciichat_error_t	session_consensus_create (const uint8_t my_id[16], bool is_leader, const uint8_t participant_ids[64][16], int num_participants, const session_consensus_callbacks_t *callbacks, session_consensus_t **out_consensus)
void	session_consensus_destroy (session_consensus_t *consensus)
asciichat_error_t	session_consensus_process (session_consensus_t *consensus, uint32_t timeout_ms)
asciichat_error_t	session_consensus_set_topology (session_consensus_t *consensus, const uint8_t participant_ids[64][16], int num_participants)
asciichat_error_t	session_consensus_on_collection_start (session_consensus_t *consensus, uint32_t round_id, uint64_t deadline_ns)
asciichat_error_t	session_consensus_on_stats_update (session_consensus_t *consensus, const uint8_t sender_id[16], const participant_metrics_t *metrics, uint8_t num_metrics)
asciichat_error_t	session_consensus_on_election_result (session_consensus_t *consensus, const uint8_t host_id[16], const char host_address[64], uint16_t host_port, const uint8_t backup_id[16], const char backup_address[64], uint16_t backup_port)
asciichat_error_t	session_consensus_get_elected_host (session_consensus_t *consensus, uint8_t out_host_id[16], char out_host_address[64], uint16_t *out_host_port, uint8_t out_backup_id[16], char out_backup_address[64], uint16_t *out_backup_port)
bool	session_consensus_is_ready (session_consensus_t *consensus)
int	session_consensus_get_state (session_consensus_t *consensus)
uint64_t	session_consensus_time_until_next_round (session_consensus_t *consensus)
int	session_consensus_get_metrics_count (session_consensus_t *consensus)

Detailed Description

Mode-agnostic ring consensus abstraction implementation.

Definition in file consensus.c.

Typedef Documentation

session_consensus_t

typedef struct session_consensus session_consensus_t

Session consensus handle - wraps all consensus modules.

Function Documentation

session_consensus_create()

asciichat_error_t session_consensus_create	(	const uint8_t	my_id[16],
		bool	is_leader,
		const uint8_t	participant_ids[64][16],
		int	num_participants,
		const session_consensus_callbacks_t *	callbacks,
		session_consensus_t **	out_consensus
	)

Definition at line 108 of file consensus.c.

                                                                                {
  if (!my_id || !callbacks || !out_consensus) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: my_id=%p, callbacks=%p, out_consensus=%p", my_id,
                     callbacks, out_consensus);
  }
 
  if (!callbacks->send_packet || !callbacks->on_election || !callbacks->get_metrics) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Required callbacks missing: send_packet=%p, on_election=%p, get_metrics=%p",
                     callbacks->send_packet, callbacks->on_election, callbacks->get_metrics);
  }
 
  if (num_participants < 1 || num_participants > 64) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid participant count: %d", num_participants);
  }
 
  // Allocate consensus handle
  session_consensus_t *consensus = SAFE_CALLOC(1, sizeof(session_consensus_t), session_consensus_t *);
  if (!consensus) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate session consensus");
  }
 
  // Copy identity
  memcpy(consensus->my_id, my_id, 16);
  consensus->is_leader = is_leader;
 
  // Copy callbacks
  consensus->send_packet = callbacks->send_packet;
  consensus->on_election = callbacks->on_election;
  consensus->get_metrics = callbacks->get_metrics;
  consensus->election = callbacks->election; // May be NULL
  consensus->context = callbacks->context;
 
  // Create topology
  asciichat_error_t err = consensus_topology_create(participant_ids, num_participants, my_id, &consensus->topology);
  if (err != ASCIICHAT_OK) {
    SAFE_FREE(consensus);
    return err;
  }
 
  // Create coordinator
  err = consensus_coordinator_create(my_id, consensus->topology, session_consensus_election_bridge, consensus,
                                     &consensus->coordinator);
  if (err != ASCIICHAT_OK) {
    consensus_topology_destroy(consensus->topology);
    SAFE_FREE(consensus);
    return err;
  }
 
  log_debug("Session consensus created: my_id=%.*s, is_leader=%d, participants=%d", 16, my_id, is_leader,
            num_participants);
 
  *out_consensus = consensus;
  return ASCIICHAT_OK;
}

References consensus_coordinator_create(), consensus_topology_create(), consensus_topology_destroy(), session_consensus::context, session_consensus::coordinator, session_consensus::election, session_consensus::get_metrics, session_consensus::is_leader, session_consensus::my_id, session_consensus::on_election, session_consensus::send_packet, and session_consensus::topology.

Referenced by consensus_create_for_discovery().

session_consensus_destroy()

void session_consensus_destroy

(

session_consensus_t *

consensus

)

Definition at line 166 of file consensus.c.

                                                               {
  if (!consensus) {
    return;
  }
 
  if (consensus->coordinator) {
    consensus_coordinator_destroy(consensus->coordinator);
  }
 
  if (consensus->topology) {
    consensus_topology_destroy(consensus->topology);
  }
 
  SAFE_FREE(consensus);
}

References consensus_coordinator_destroy(), consensus_topology_destroy(), session_consensus::coordinator, and session_consensus::topology.

session_consensus_get_elected_host()

asciichat_error_t session_consensus_get_elected_host	(	session_consensus_t *	consensus,
		uint8_t	out_host_id[16],
		char	out_host_address[64],
		uint16_t *	out_host_port,
		uint8_t	out_backup_id[16],
		char	out_backup_address[64],
		uint16_t *	out_backup_port
	)

Definition at line 259 of file consensus.c.

                                                                                {
  if (!consensus || !out_host_id || !out_host_address || !out_host_port || !out_backup_id || !out_backup_address ||
      !out_backup_port) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  // Get from coordinator
  asciichat_error_t err = consensus_coordinator_get_current_host(consensus->coordinator, out_host_id, out_backup_id);
  if (err != ASCIICHAT_OK) {
    return err;
  }
 
  // NOTE: The current API doesn't return addresses/ports. This is a limitation
  // of the coordinator that should be addressed in a future enhancement.
  // For now, return zeros and indicate this is a placeholder.
  memset(out_host_address, 0, 64);
  *out_host_port = 0;
  memset(out_backup_address, 0, 64);
  *out_backup_port = 0;
 
  return ASCIICHAT_OK;
}

References consensus_coordinator_get_current_host(), and session_consensus::coordinator.

session_consensus_get_metrics_count()

int session_consensus_get_metrics_count

(

session_consensus_t *

consensus

)

Definition at line 314 of file consensus.c.

                                                                        {
  if (!consensus) {
    return -1;
  }
 
  return consensus_coordinator_get_metrics_count(consensus->coordinator);
}

References consensus_coordinator_get_metrics_count(), and session_consensus::coordinator.

session_consensus_get_state()

int session_consensus_get_state

(

session_consensus_t *

consensus

)

Definition at line 298 of file consensus.c.

                                                                {
  if (!consensus) {
    return -1;
  }
 
  return (int)consensus_coordinator_get_state(consensus->coordinator);
}

References consensus_coordinator_get_state(), and session_consensus::coordinator.

session_consensus_is_ready()

bool session_consensus_is_ready

(

session_consensus_t *

consensus

)

Definition at line 285 of file consensus.c.

                                                                {
  if (!consensus) {
    return false;
  }
 
  // Check if we have a valid elected host
  uint8_t host_id[16];
  uint8_t backup_id[16];
  asciichat_error_t err = consensus_coordinator_get_current_host(consensus->coordinator, host_id, backup_id);
 
  return err == ASCIICHAT_OK;
}

References consensus_coordinator_get_current_host(), and session_consensus::coordinator.

session_consensus_on_collection_start()

asciichat_error_t session_consensus_on_collection_start	(	session_consensus_t *	consensus,
		uint32_t	round_id,
		uint64_t	deadline_ns
	)

Definition at line 218 of file consensus.c.

                                                                              {
  if (!consensus) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "consensus is NULL");
  }
 
  return consensus_coordinator_on_collection_start(consensus->coordinator, round_id, deadline_ns);
}

References consensus_coordinator_on_collection_start(), and session_consensus::coordinator.

session_consensus_on_election_result()

asciichat_error_t session_consensus_on_election_result	(	session_consensus_t *	consensus,
		const uint8_t	host_id[16],
		const char	host_address[64],
		uint16_t	host_port,
		const uint8_t	backup_id[16],
		const char	backup_address[64],
		uint16_t	backup_port
	)

Definition at line 236 of file consensus.c.

                                                                             {
  if (!consensus || !host_id || !backup_id) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  // First acknowledge the election in coordinator
  asciichat_error_t err = consensus_coordinator_on_election_result(consensus->coordinator, host_id, backup_id);
  if (err != ASCIICHAT_OK) {
    return err;
  }
 
  // Then call the mode's election callback
  if (consensus->on_election) {
    return consensus->on_election(consensus->context, host_id, host_address, host_port, backup_id, backup_address,
                                  backup_port);
  }
 
  return ASCIICHAT_OK;
}

References consensus_coordinator_on_election_result(), session_consensus::context, session_consensus::coordinator, and session_consensus::on_election.

session_consensus_on_stats_update()

asciichat_error_t session_consensus_on_stats_update	(	session_consensus_t *	consensus,
		const uint8_t	sender_id[16],
		const participant_metrics_t *	metrics,
		uint8_t	num_metrics
	)

Definition at line 227 of file consensus.c.

                                                                                                               {
  if (!consensus || !sender_id || !metrics) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  return consensus_coordinator_on_stats_update(consensus->coordinator, sender_id, metrics, num_metrics);
}

References consensus_coordinator_on_stats_update(), and session_consensus::coordinator.

session_consensus_process()

asciichat_error_t session_consensus_process	(	session_consensus_t *	consensus,
		uint32_t	timeout_ms
	)

Definition at line 182 of file consensus.c.

                                                                                                 {
  if (!consensus) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "consensus is NULL");
  }
 
  // Call coordinator process
  return consensus_coordinator_process(consensus->coordinator, timeout_ms);
}

References consensus_coordinator_process(), and session_consensus::coordinator.

session_consensus_set_topology()

asciichat_error_t session_consensus_set_topology	(	session_consensus_t *	consensus,
		const uint8_t	participant_ids[64][16],
		int	num_participants
	)

Definition at line 191 of file consensus.c.

                                                                       {
  if (!consensus || !participant_ids) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  if (num_participants < 1 || num_participants > 64) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid participant count: %d", num_participants);
  }
 
  // Destroy old topology
  if (consensus->topology) {
    consensus_topology_destroy(consensus->topology);
  }
 
  // Create new topology
  asciichat_error_t err =
      consensus_topology_create(participant_ids, num_participants, consensus->my_id, &consensus->topology);
  if (err != ASCIICHAT_OK) {
    consensus->topology = NULL;
    return err;
  }
 
  // Update coordinator with new topology
  return consensus_coordinator_on_ring_members(consensus->coordinator, consensus->topology);
}

References consensus_coordinator_on_ring_members(), consensus_topology_create(), consensus_topology_destroy(), session_consensus::coordinator, session_consensus::my_id, and session_consensus::topology.

session_consensus_time_until_next_round()

uint64_t session_consensus_time_until_next_round

(

session_consensus_t *

consensus

)

Definition at line 306 of file consensus.c.

                                                                                 {
  if (!consensus) {
    return 0;
  }
 
  return consensus_coordinator_time_until_next_round(consensus->coordinator);
}

References consensus_coordinator_time_until_next_round(), and session_consensus::coordinator.

Referenced by consensus_suggest_timeout_ms().