state.h File Reference

Ring consensus state machine. More...

Go to the source code of this file.

Typedefs
typedef struct consensus_state	consensus_state_t
	Opaque consensus state machine handle.

Enumerations
enum	consensus_state_machine_t {   CONSENSUS_STATE_IDLE = 0 , CONSENSUS_STATE_COLLECTION_START = 1 , CONSENSUS_STATE_COLLECTING = 2 , CONSENSUS_STATE_COLLECTION_COMPLETE = 3 ,   CONSENSUS_STATE_ELECTION_START = 4 , CONSENSUS_STATE_ELECTING = 5 , CONSENSUS_STATE_ELECTION_COMPLETE = 6 , CONSENSUS_STATE_FAILED = 7 }
	State machine lifecycle states. More...

Functions
asciichat_error_t	consensus_state_create (const uint8_t my_id[16], const consensus_topology_t *topology, consensus_state_t **out_state)
	Initialize state machine with topology.
void	consensus_state_destroy (consensus_state_t *state)
	Destroy state machine and free resources.
asciichat_error_t	consensus_state_start_collection (consensus_state_t *state)
	Transition to COLLECTION_START state.
asciichat_error_t	consensus_state_add_metrics (consensus_state_t *state, const participant_metrics_t *metrics)
	Add collected metrics from a participant.
asciichat_error_t	consensus_state_collection_complete (consensus_state_t *state)
	Transition to COLLECTION_COMPLETE state.
asciichat_error_t	consensus_state_compute_election (consensus_state_t *state)
	Run election algorithm and transition to ELECTION_COMPLETE.
asciichat_error_t	consensus_state_reset_to_idle (consensus_state_t *state)
	Transition back to IDLE from ELECTION_COMPLETE.
consensus_state_machine_t	consensus_state_get_current_state (const consensus_state_t *state)
	Get current state machine state.
asciichat_error_t	consensus_state_get_elected_host (const consensus_state_t *state, uint8_t out_host_id[16])
	Get elected host ID from last election.
asciichat_error_t	consensus_state_get_elected_backup (const consensus_state_t *state, uint8_t out_backup_id[16])
	Get elected backup host ID from last election.
bool	consensus_state_is_leader (const consensus_state_t *state)
	Check if we are the elected leader for this round.
int	consensus_state_get_metrics_count (const consensus_state_t *state)
	Get count of metrics collected in current round.
asciichat_error_t	consensus_state_get_metric_at (const consensus_state_t *state, int index, participant_metrics_t *out_metrics)
	Get collected metrics at index.

Detailed Description

Ring consensus state machine.

Definition in file state.h.

Typedef Documentation

consensus_state_t

typedef struct consensus_state consensus_state_t

Opaque consensus state machine handle.

Definition at line 32 of file state.h.

Enumeration Type Documentation

consensus_state_machine_t

enum consensus_state_machine_t

State machine lifecycle states.

Enumerator
CONSENSUS_STATE_IDLE	Waiting for round to start
CONSENSUS_STATE_COLLECTION_START	Round started, prepare collection
CONSENSUS_STATE_COLLECTING	Collecting metrics
CONSENSUS_STATE_COLLECTION_COMPLETE	All metrics received
CONSENSUS_STATE_ELECTION_START	Preparing election (leader only)
CONSENSUS_STATE_ELECTING	Running election algorithm
CONSENSUS_STATE_ELECTION_COMPLETE	Election result computed
CONSENSUS_STATE_FAILED	Error state

Definition at line 18 of file state.h.

             {
  CONSENSUS_STATE_IDLE = 0,                
  CONSENSUS_STATE_COLLECTION_START = 1,    
  CONSENSUS_STATE_COLLECTING = 2,          
  CONSENSUS_STATE_COLLECTION_COMPLETE = 3, 
  CONSENSUS_STATE_ELECTION_START = 4,      
  CONSENSUS_STATE_ELECTING = 5,            
  CONSENSUS_STATE_ELECTION_COMPLETE = 6,   
  CONSENSUS_STATE_FAILED = 7               
} consensus_state_machine_t;

Function Documentation

consensus_state_add_metrics()

asciichat_error_t consensus_state_add_metrics	(	consensus_state_t *	state,
		const participant_metrics_t *	metrics
	)

Add collected metrics from a participant.

Valid in: COLLECTING state Stores metrics in dynamic array (grows as needed, initial capacity 10)

Parameters

state	State machine handle
metrics	Participant metrics to store

Returns

ASCIICHAT_OK on success, ERROR_INVALID_STATE if not in COLLECTING state

Definition at line 100 of file state.c.

                                                                                                              {
  if (!state || !metrics) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  if (state->current_state != CONSENSUS_STATE_COLLECTING) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Invalid state for adding metrics: %d", state->current_state);
  }
 
  /* Grow array if needed */
  if (state->metrics_count >= state->metrics_capacity) {
    int new_capacity = state->metrics_capacity * 2;
    participant_metrics_t *new_metrics =
        SAFE_REALLOC(state->metrics, new_capacity * sizeof(participant_metrics_t), participant_metrics_t *);
    state->metrics = new_metrics;
    state->metrics_capacity = new_capacity;
  }
 
  /* Copy metrics into array */
  memcpy(&state->metrics[state->metrics_count], metrics, sizeof(participant_metrics_t));
  state->metrics_count++;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, CONSENSUS_STATE_COLLECTING, consensus_state::current_state, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, consensus_state::metrics, consensus_state::metrics_capacity, consensus_state::metrics_count, SAFE_REALLOC, and SET_ERRNO.

Referenced by consensus_coordinator_on_stats_update().

consensus_state_collection_complete()

asciichat_error_t consensus_state_collection_complete

(

consensus_state_t *

state

)

Transition to COLLECTION_COMPLETE state.

Valid from: COLLECTING Transitions to: ELECTION_START (if leader) or IDLE (if not leader)

Parameters

state

State machine handle

Returns

ASCIICHAT_OK on success, ERROR_INVALID_STATE if transition invalid

Definition at line 125 of file state.c.

                                                                                {
  if (!state) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "State is NULL");
  }
 
  if (state->current_state != CONSENSUS_STATE_COLLECTING) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Invalid transition from state %d", state->current_state);
  }
 
  /* Transition: if we're leader, go to ELECTION_START; otherwise go to IDLE */
  if (consensus_topology_am_leader(state->topology)) {
    state->current_state = CONSENSUS_STATE_ELECTION_START;
  } else {
    state->current_state = CONSENSUS_STATE_IDLE;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, CONSENSUS_STATE_COLLECTING, CONSENSUS_STATE_ELECTION_START, CONSENSUS_STATE_IDLE, consensus_topology_am_leader(), consensus_state::current_state, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, SET_ERRNO, and consensus_state::topology.

consensus_state_compute_election()

asciichat_error_t consensus_state_compute_election

(

consensus_state_t *

state

)

Run election algorithm and transition to ELECTION_COMPLETE.

Valid from: ELECTION_START or ELECTION_COMPLETE Processes collected metrics to select best host and backup. Election selects host as participant with best score, backup as second-best. Score is computed from metrics: lower RTT + higher bandwidth = better score. Only leader should call this.

Parameters

state

State machine handle

Returns

ASCIICHAT_OK on success, ERROR_INVALID_STATE if not in ELECTION_START state

Definition at line 144 of file state.c.

                                                                             {
  if (!state) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "State is NULL");
  }
 
  if (state->current_state != CONSENSUS_STATE_ELECTION_START) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Invalid transition from state %d", state->current_state);
  }
 
  if (state->metrics_count < 2) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Need at least 2 metrics for election, have %d", state->metrics_count);
  }
 
  /* Find best and second-best metrics */
  int best_idx = 0;
  int backup_idx = 1;
 
  double best_score = compute_metric_score(&state->metrics[0]);
  double backup_score = compute_metric_score(&state->metrics[1]);
 
  /* Ensure best_idx has lower score */
  if (best_score > backup_score) {
    int tmp = best_idx;
    best_idx = backup_idx;
    backup_idx = tmp;
    double tmp_score = best_score;
    best_score = backup_score;
    backup_score = tmp_score;
  }
 
  /* Find best and second-best */
  for (int i = 2; i < state->metrics_count; i++) {
    double score = compute_metric_score(&state->metrics[i]);
    if (score < best_score) {
      backup_idx = best_idx;
      backup_score = best_score;
      best_idx = i;
      best_score = score;
    } else if (score < backup_score) {
      backup_idx = i;
      backup_score = score;
    }
  }
 
  /* Store election result */
  memcpy(state->election_result.host_id, state->metrics[best_idx].participant_id, 16);
  memcpy(state->election_result.backup_id, state->metrics[backup_idx].participant_id, 16);
  state->election_result.timestamp_ns = time_get_realtime_ns();
 
  state->current_state = CONSENSUS_STATE_ELECTION_COMPLETE;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, election_result_t::backup_id, CONSENSUS_STATE_ELECTION_COMPLETE, CONSENSUS_STATE_ELECTION_START, consensus_state::current_state, consensus_state::election_result, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, election_result_t::host_id, consensus_state::metrics, consensus_state::metrics_count, SET_ERRNO, time_get_realtime_ns(), and election_result_t::timestamp_ns.

consensus_state_create()

asciichat_error_t consensus_state_create	(	const uint8_t	my_id[16],
		const consensus_topology_t *	topology,
		consensus_state_t **	out_state
	)

Initialize state machine with topology.

Creates a new state machine for managing consensus rounds. Initial state is CONSENSUS_STATE_IDLE.

Parameters

my_id	My 16-byte UUID
topology	Topology handle (not owned by state machine)
out_state	Output state machine handle (caller must destroy)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 50 of file state.c.

                                                                        {
  if (!my_id || !topology || !out_state) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid state creation parameters");
  }
 
  consensus_state_t *state = SAFE_MALLOC(sizeof(*state), consensus_state_t *);
  memset(state, 0, sizeof(*state));
 
  state->current_state = CONSENSUS_STATE_IDLE;
  state->topology = (consensus_topology_t *)topology; /* Cast away const for storage */
  memcpy(state->my_id, my_id, 16);
 
  /* Initialize metrics array with initial capacity of 10 */
  state->metrics_capacity = 10;
  state->metrics_count = 0;
  state->metrics = SAFE_MALLOC(state->metrics_capacity * sizeof(participant_metrics_t), participant_metrics_t *);
 
  memset(&state->election_result, 0, sizeof(election_result_t));
 
  *out_state = state;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, CONSENSUS_STATE_IDLE, consensus_state::current_state, consensus_state::election_result, ERROR_INVALID_PARAM, consensus_state::metrics, consensus_state::metrics_capacity, consensus_state::metrics_count, consensus_state::my_id, SAFE_MALLOC, SET_ERRNO, and consensus_state::topology.

Referenced by consensus_coordinator_create(), and consensus_coordinator_on_ring_members().

consensus_state_destroy()

void consensus_state_destroy

(

consensus_state_t *

state

)

Destroy state machine and free resources.

Parameters

state

State machine handle (safe to pass NULL)

Definition at line 74 of file state.c.

                                                       {
  if (state) {
    if (state->metrics) {
      SAFE_FREE(state->metrics);
    }
    SAFE_FREE(state);
  }
}

References consensus_state::metrics, and SAFE_FREE.

Referenced by consensus_coordinator_destroy(), and consensus_coordinator_on_ring_members().

consensus_state_get_current_state()

consensus_state_machine_t consensus_state_get_current_state

(

const consensus_state_t *

state

)

Get current state machine state.

Parameters

state

State machine handle

Returns

Current state (FAILED if state is NULL)

Definition at line 210 of file state.c.

                                                                                            {
  if (!state) {
    return CONSENSUS_STATE_FAILED;
  }
  return state->current_state;
}

References CONSENSUS_STATE_FAILED, and consensus_state::current_state.

Referenced by consensus_coordinator_get_current_host(), consensus_coordinator_get_state(), consensus_coordinator_on_collection_start(), consensus_coordinator_on_election_result(), consensus_coordinator_on_ring_members(), consensus_coordinator_on_stats_update(), and consensus_coordinator_process().

consensus_state_get_elected_backup()

asciichat_error_t consensus_state_get_elected_backup	(	const consensus_state_t *	state,
		uint8_t	out_backup_id[16]
	)

Get elected backup host ID from last election.

Valid from: ELECTION_COMPLETE state

Parameters

state	State machine handle
out_backup_id	Output 16-byte backup UUID (caller provides buffer)

Returns

ASCIICHAT_OK on success, ERROR_INVALID_STATE if election not complete

Definition at line 230 of file state.c.

                                                                                                                {
  if (!state || !out_backup_id) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  if (state->current_state != CONSENSUS_STATE_ELECTION_COMPLETE) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Election not complete, current state: %d", state->current_state);
  }
 
  memcpy(out_backup_id, state->election_result.backup_id, 16);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, election_result_t::backup_id, CONSENSUS_STATE_ELECTION_COMPLETE, consensus_state::current_state, consensus_state::election_result, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, and SET_ERRNO.

Referenced by consensus_coordinator_get_current_host().

consensus_state_get_elected_host()

asciichat_error_t consensus_state_get_elected_host	(	const consensus_state_t *	state,
		uint8_t	out_host_id[16]
	)

Get elected host ID from last election.

Valid from: ELECTION_COMPLETE state

Parameters

state	State machine handle
out_host_id	Output 16-byte host UUID (caller provides buffer)

Returns

ASCIICHAT_OK on success, ERROR_INVALID_STATE if election not complete

Definition at line 217 of file state.c.

                                                                                                            {
  if (!state || !out_host_id) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  if (state->current_state != CONSENSUS_STATE_ELECTION_COMPLETE) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Election not complete, current state: %d", state->current_state);
  }
 
  memcpy(out_host_id, state->election_result.host_id, 16);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, CONSENSUS_STATE_ELECTION_COMPLETE, consensus_state::current_state, consensus_state::election_result, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, election_result_t::host_id, and SET_ERRNO.

Referenced by consensus_coordinator_get_current_host().

consensus_state_get_metric_at()

asciichat_error_t consensus_state_get_metric_at	(	const consensus_state_t *	state,
		int	index,
		participant_metrics_t *	out_metrics
	)

Get collected metrics at index.

Valid from: COLLECTING, COLLECTION_COMPLETE, or ELECTION states

Parameters

state	State machine handle
index	Index of metric to retrieve (0-based)
out_metrics	Output metrics structure

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 257 of file state.c.

                                                                                    {
  if (!state || !out_metrics || index < 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  if (index >= state->metrics_count) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Index %d out of bounds (count: %d)", index, state->metrics_count);
  }
 
  /* Valid to retrieve metrics in COLLECTING, COLLECTION_COMPLETE, or ELECTION states */
  if (state->current_state != CONSENSUS_STATE_COLLECTING &&
      state->current_state != CONSENSUS_STATE_COLLECTION_COMPLETE &&
      state->current_state != CONSENSUS_STATE_ELECTION_START && state->current_state != CONSENSUS_STATE_ELECTING &&
      state->current_state != CONSENSUS_STATE_ELECTION_COMPLETE) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Cannot retrieve metrics in state %d", state->current_state);
  }
 
  memcpy(out_metrics, &state->metrics[index], sizeof(participant_metrics_t));
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, CONSENSUS_STATE_COLLECTING, CONSENSUS_STATE_COLLECTION_COMPLETE, CONSENSUS_STATE_ELECTING, CONSENSUS_STATE_ELECTION_COMPLETE, CONSENSUS_STATE_ELECTION_START, consensus_state::current_state, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, consensus_state::metrics, consensus_state::metrics_count, and SET_ERRNO.

consensus_state_get_metrics_count()

int consensus_state_get_metrics_count

(

const consensus_state_t *

state

)

Get count of metrics collected in current round.

Parameters

state

State machine handle

Returns

Number of metrics collected, or -1 if invalid

Definition at line 250 of file state.c.

                                                                      {
  if (!state) {
    return -1;
  }
  return state->metrics_count;
}

References consensus_state::metrics_count.

Referenced by consensus_coordinator_get_metrics_count().

consensus_state_is_leader()

bool consensus_state_is_leader

(

const consensus_state_t *

state

)

Check if we are the elected leader for this round.

Parameters

state

State machine handle

Returns

true if we are the ring leader, false otherwise

Definition at line 243 of file state.c.

                                                               {
  if (!state) {
    return false;
  }
  return consensus_topology_am_leader(state->topology);
}

References consensus_topology_am_leader(), and consensus_state::topology.

consensus_state_reset_to_idle()

asciichat_error_t consensus_state_reset_to_idle

(

consensus_state_t *

state

)

Transition back to IDLE from ELECTION_COMPLETE.

Valid from: ELECTION_COMPLETE Transitions to: IDLE

Parameters

state

State machine handle

Returns

ASCIICHAT_OK on success, ERROR_INVALID_STATE if transition invalid

Definition at line 197 of file state.c.

                                                                          {
  if (!state) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "State is NULL");
  }
 
  if (state->current_state != CONSENSUS_STATE_ELECTION_COMPLETE) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Invalid transition from state %d", state->current_state);
  }
 
  state->current_state = CONSENSUS_STATE_IDLE;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, CONSENSUS_STATE_ELECTION_COMPLETE, CONSENSUS_STATE_IDLE, consensus_state::current_state, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, and SET_ERRNO.

Referenced by consensus_coordinator_on_election_result().

consensus_state_start_collection()

asciichat_error_t consensus_state_start_collection

(

consensus_state_t *

state

)

Transition to COLLECTION_START state.

Valid from: IDLE Transitions to: COLLECTING

Parameters

state

State machine handle

Returns

ASCIICHAT_OK on success, ERROR_INVALID_STATE if transition invalid

Definition at line 83 of file state.c.

                                                                             {
  if (!state) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "State is NULL");
  }
 
  if (state->current_state != CONSENSUS_STATE_IDLE) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Invalid transition from state %d", state->current_state);
  }
 
  /* Reset metrics from previous round */
  state->metrics_count = 0;
  memset(&state->election_result, 0, sizeof(election_result_t));
 
  state->current_state = CONSENSUS_STATE_COLLECTING;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, CONSENSUS_STATE_COLLECTING, CONSENSUS_STATE_IDLE, consensus_state::current_state, consensus_state::election_result, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, consensus_state::metrics_count, and SET_ERRNO.

Referenced by consensus_coordinator_on_collection_start().