state.h File Reference

Ring consensus state machine. More...

Go to the source code of this file.

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[SESSION_ID_SIZE], 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[SESSION_ID_SIZE])
	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[SESSION_ID_SIZE])
	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.
asciichat_error_t	consensus_state_store_election (consensus_state_t *state, int best, int backup)

Detailed Description

Ring consensus state machine.

Definition in 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 19 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 93 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, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, 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 118 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(), ERROR_INVALID_PARAM, ERROR_INVALID_STATE, and SET_ERRNO.

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 137 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);
  }
 
  int best_idx = -1, backup_idx = -1;
  asciichat_error_t result =
      consensus_election_choose_hosts(state->metrics, state->metrics_count, &best_idx, &backup_idx);
  if (result != ASCIICHAT_OK)
    return result;
  return consensus_state_store_election(state, best_idx, backup_idx);
}

References ASCIICHAT_OK, consensus_election_choose_hosts(), CONSENSUS_STATE_ELECTION_START, consensus_state_store_election(), ERROR_INVALID_PARAM, ERROR_INVALID_STATE, and SET_ERRNO.

consensus_state_create()

asciichat_error_t consensus_state_create	(	const uint8_t	my_id[SESSION_ID_SIZE],
		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 43 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, SESSION_ID_SIZE);
 
  /* 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, ERROR_INVALID_PARAM, SAFE_MALLOC, SESSION_ID_SIZE, and SET_ERRNO.

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 67 of file state.c.

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

References 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 181 of file state.c.

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

References CONSENSUS_STATE_FAILED.

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[SESSION_ID_SIZE] )

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 202 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, SESSION_ID_SIZE);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, CONSENSUS_STATE_ELECTION_COMPLETE, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, SESSION_ID_SIZE, 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[SESSION_ID_SIZE] )

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 188 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, SESSION_ID_SIZE);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, CONSENSUS_STATE_ELECTION_COMPLETE, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, SESSION_ID_SIZE, 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 230 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, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, index, 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 223 of file state.c.

                                                                      {
  if (!state) {
    return -1;
  }
  return 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 216 of file state.c.

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

References consensus_topology_am_leader().

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 168 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, 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 76 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, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, and SET_ERRNO.

Referenced by consensus_coordinator_on_collection_start().

consensus_state_store_election()

asciichat_error_t consensus_state_store_election	(	consensus_state_t *	state,
		int	best,
		int	backup )

Store a selector result while completing the current election.

Definition at line 154 of file state.c.

                                                                                                         {
  if (!state || state->current_state != CONSENSUS_STATE_ELECTION_START || best_idx < 0 ||
      best_idx >= state->metrics_count || backup_idx < -1 || backup_idx >= state->metrics_count ||
      backup_idx == best_idx)
    return SET_ERRNO(ERROR_INVALID_STATE, "Invalid election result");
  memcpy(state->election_result.host_id, state->metrics[best_idx].participant_id, SESSION_ID_SIZE);
  memset(state->election_result.backup_id, 0, SESSION_ID_SIZE);
  if (backup_idx >= 0)
    memcpy(state->election_result.backup_id, state->metrics[backup_idx].participant_id, SESSION_ID_SIZE);
  state->election_result.timestamp_ns = time_get_realtime_ns();
  state->current_state = CONSENSUS_STATE_ELECTION_COMPLETE;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, CONSENSUS_STATE_ELECTION_COMPLETE, CONSENSUS_STATE_ELECTION_START, ERROR_INVALID_STATE, SESSION_ID_SIZE, and SET_ERRNO.

Referenced by consensus_state_compute_election().