ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
state.c File Reference

Ring consensus state machine implementation. More...

Go to the source code of this file.

Data Structures

struct  election_result_t
 Election result storage. More...
struct  consensus_state
 State machine instance. More...

Typedefs

typedef struct consensus_state consensus_state_t
 State machine instance.

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_store_election (consensus_state_t *state, int best_idx, int backup_idx)
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.

Detailed Description

Ring consensus state machine implementation.

Definition in file state.c.

Typedef Documentation

◆ consensus_state_t

State machine instance.

Opaque consensus state machine handle.

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
stateState machine handle
metricsParticipant metrics to store
Returns
ASCIICHAT_OK on success, ERROR_INVALID_STATE if not in COLLECTING state

Definition at line 92 of file state.c.

92 {
93 if (!state || !metrics) {
94 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
95 }
96
98 return SET_ERRNO(ERROR_INVALID_STATE, "Invalid state for adding metrics: %d", state->current_state);
99 }
100
101 /* Grow array if needed */
102 if (state->metrics_count >= state->metrics_capacity) {
103 int new_capacity = state->metrics_capacity * 2;
104 participant_metrics_t *new_metrics = SAFE_REALLOC(state->metrics, new_capacity * sizeof(participant_metrics_t), participant_metrics_t *);
105 state->metrics = new_metrics;
106 state->metrics_capacity = new_capacity;
107 }
108
109 /* Copy metrics into array */
110 memcpy(&state->metrics[state->metrics_count], metrics, sizeof(participant_metrics_t));
111 state->metrics_count++;
112
113 return ASCIICHAT_OK;
114}
#define SET_ERRNO(code,...)
#define SAFE_REALLOC(ptr, size, cast)
@ ERROR_INVALID_STATE
@ ASCIICHAT_OK
Definition error_codes.h:50
@ ERROR_INVALID_PARAM
@ CONSENSUS_STATE_COLLECTING
Definition state.h:26
int metrics_capacity
Definition state.c:37
int metrics_count
Definition state.c:36
participant_metrics_t * metrics
Definition state.c:35
consensus_state_machine_t current_state
Definition state.c:30

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
stateState machine handle
Returns
ASCIICHAT_OK on success, ERROR_INVALID_STATE if transition invalid

Definition at line 116 of file state.c.

116 {
117 if (!state) {
118 return SET_ERRNO(ERROR_INVALID_PARAM, "State is NULL");
119 }
120
122 return SET_ERRNO(ERROR_INVALID_STATE, "Invalid transition from state %d", state->current_state);
123 }
124
125 /* Transition: if we're leader, go to ELECTION_START; otherwise go to IDLE */
128 } else {
130 }
131
132 return ASCIICHAT_OK;
133}
@ CONSENSUS_STATE_ELECTION_START
Definition state.h:28
@ CONSENSUS_STATE_IDLE
Definition state.h:24
consensus_topology_t * topology
Definition state.c:31
bool consensus_topology_am_leader(const consensus_topology_t *topology)
Check if I am the ring leader (last position).
Definition topology.c:82

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
stateState machine handle
Returns
ASCIICHAT_OK on success, ERROR_INVALID_STATE if not in ELECTION_START state

Definition at line 135 of file state.c.

135 {
136 if (!state) {
137 return SET_ERRNO(ERROR_INVALID_PARAM, "State is NULL");
138 }
139
141 return SET_ERRNO(ERROR_INVALID_STATE, "Invalid transition from state %d", state->current_state);
142 }
143
144 int best_idx = -1, backup_idx = -1;
145 asciichat_error_t result = consensus_election_choose_hosts(state->metrics, state->metrics_count, &best_idx, &backup_idx);
146 if (result != ASCIICHAT_OK)
147 return result;
148 return consensus_state_store_election(state, best_idx, backup_idx);
149}
asciichat_error_t consensus_election_choose_hosts(const participant_metrics_t *metrics, int num_metrics, int *out_best_index, int *out_backup_index)
Elect best and backup host from metrics.
Definition election.c:78
asciichat_error_t
Error and exit codes - unified status values (0-255).
Definition error_codes.h:48
asciichat_error_t consensus_state_store_election(consensus_state_t *state, int best_idx, int backup_idx)
Definition state.c:151

References ASCIICHAT_OK, consensus_election_choose_hosts(), CONSENSUS_STATE_ELECTION_START, consensus_state_store_election(), consensus_state::current_state, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, consensus_state::metrics, consensus_state::metrics_count, 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_idMy 16-byte UUID
topologyTopology handle (not owned by state machine)
out_stateOutput state machine handle (caller must destroy)
Returns
ASCIICHAT_OK on success, error code otherwise

Definition at line 43 of file state.c.

43 {
44 if (!my_id || !topology || !out_state) {
45 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid state creation parameters");
46 }
47
48 consensus_state_t *state = SAFE_MALLOC(sizeof(*state), consensus_state_t *);
49 memset(state, 0, sizeof(*state));
50
52 state->topology = (consensus_topology_t *)topology; /* Cast away const for storage */
53 memcpy(state->my_id, my_id, SESSION_ID_SIZE);
54
55 /* Initialize metrics array with initial capacity of 10 */
56 state->metrics_capacity = 10;
57 state->metrics_count = 0;
58 state->metrics = SAFE_MALLOC(state->metrics_capacity * sizeof(participant_metrics_t), participant_metrics_t *);
59
60 memset(&state->election_result, 0, sizeof(election_result_t));
61
62 *out_state = state;
63 return ASCIICHAT_OK;
64}
#define SAFE_MALLOC(size, cast)
#define SESSION_ID_SIZE
struct consensus_state consensus_state_t
State machine instance.
election_result_t election_result
Definition state.c:40
uint8_t my_id[SESSION_ID_SIZE]
Definition state.c:32
Election result storage.
Definition state.c:20
struct consensus_topology consensus_topology_t
Ring topology for consensus participants.

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, SESSION_ID_SIZE, 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
stateState machine handle (safe to pass NULL)

Definition at line 66 of file state.c.

66 {
67 if (state) {
68 if (state->metrics) {
69 SAFE_FREE(state->metrics);
70 }
71 SAFE_FREE(state);
72 }
73}
#define SAFE_FREE(ptr)

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
stateState machine handle
Returns
Current state (FAILED if state is NULL)

Definition at line 177 of file state.c.

177 {
178 if (!state) {
180 }
181 return state->current_state;
182}
@ CONSENSUS_STATE_FAILED
Definition state.h:31

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

Get elected backup host ID from last election.

Valid from: ELECTION_COMPLETE state

Parameters
stateState machine handle
out_backup_idOutput 16-byte backup UUID (caller provides buffer)
Returns
ASCIICHAT_OK on success, ERROR_INVALID_STATE if election not complete

Definition at line 197 of file state.c.

197 {
198 if (!state || !out_backup_id) {
199 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
200 }
201
203 return SET_ERRNO(ERROR_INVALID_STATE, "Election not complete, current state: %d", state->current_state);
204 }
205
206 memcpy(out_backup_id, state->election_result.backup_id, SESSION_ID_SIZE);
207 return ASCIICHAT_OK;
208}
@ CONSENSUS_STATE_ELECTION_COMPLETE
Definition state.h:30
uint8_t backup_id[SESSION_ID_SIZE]
Definition state.c:22

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, 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
stateState machine handle
out_host_idOutput 16-byte host UUID (caller provides buffer)
Returns
ASCIICHAT_OK on success, ERROR_INVALID_STATE if election not complete

Definition at line 184 of file state.c.

184 {
185 if (!state || !out_host_id) {
186 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
187 }
188
190 return SET_ERRNO(ERROR_INVALID_STATE, "Election not complete, current state: %d", state->current_state);
191 }
192
193 memcpy(out_host_id, state->election_result.host_id, SESSION_ID_SIZE);
194 return ASCIICHAT_OK;
195}
uint8_t host_id[SESSION_ID_SIZE]
Definition state.c:21

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, 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
stateState machine handle
indexIndex of metric to retrieve (0-based)
out_metricsOutput metrics structure
Returns
ASCIICHAT_OK on success, error code otherwise

Definition at line 224 of file state.c.

224 {
225 if (!state || !out_metrics || index < 0) {
226 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
227 }
228
229 if (index >= state->metrics_count) {
230 return SET_ERRNO(ERROR_INVALID_PARAM, "Index %d out of bounds (count: %d)", index, state->metrics_count);
231 }
232
233 /* Valid to retrieve metrics in COLLECTING, COLLECTION_COMPLETE, or ELECTION states */
236 return SET_ERRNO(ERROR_INVALID_STATE, "Cannot retrieve metrics in state %d", state->current_state);
237 }
238
239 memcpy(out_metrics, &state->metrics[index], sizeof(participant_metrics_t));
240 return ASCIICHAT_OK;
241}
static bool size_t index
Definition queries.h:8
@ CONSENSUS_STATE_COLLECTION_COMPLETE
Definition state.h:27
@ CONSENSUS_STATE_ELECTING
Definition state.h:29

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, index, 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
stateState machine handle
Returns
Number of metrics collected, or -1 if invalid

Definition at line 217 of file state.c.

217 {
218 if (!state) {
219 return -1;
220 }
221 return state->metrics_count;
222}

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
stateState machine handle
Returns
true if we are the ring leader, false otherwise

Definition at line 210 of file state.c.

210 {
211 if (!state) {
212 return false;
213 }
215}

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
stateState machine handle
Returns
ASCIICHAT_OK on success, ERROR_INVALID_STATE if transition invalid

Definition at line 164 of file state.c.

164 {
165 if (!state) {
166 return SET_ERRNO(ERROR_INVALID_PARAM, "State is NULL");
167 }
168
170 return SET_ERRNO(ERROR_INVALID_STATE, "Invalid transition from state %d", state->current_state);
171 }
172
174 return ASCIICHAT_OK;
175}

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
stateState machine handle
Returns
ASCIICHAT_OK on success, ERROR_INVALID_STATE if transition invalid

Definition at line 75 of file state.c.

75 {
76 if (!state) {
77 return SET_ERRNO(ERROR_INVALID_PARAM, "State is NULL");
78 }
79
80 if (state->current_state != CONSENSUS_STATE_IDLE) {
81 return SET_ERRNO(ERROR_INVALID_STATE, "Invalid transition from state %d", state->current_state);
82 }
83
84 /* Reset metrics from previous round */
85 state->metrics_count = 0;
86 memset(&state->election_result, 0, sizeof(election_result_t));
87
89 return ASCIICHAT_OK;
90}

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().

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

151 {
152 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 ||
153 backup_idx == best_idx)
154 return SET_ERRNO(ERROR_INVALID_STATE, "Invalid election result");
155 memcpy(state->election_result.host_id, state->metrics[best_idx].participant_id, SESSION_ID_SIZE);
156 memset(state->election_result.backup_id, 0, SESSION_ID_SIZE);
157 if (backup_idx >= 0)
158 memcpy(state->election_result.backup_id, state->metrics[backup_idx].participant_id, SESSION_ID_SIZE);
159 state->election_result.timestamp_ns = time_get_realtime_ns();
161 return ASCIICHAT_OK;
162}
uint64_t timestamp_ns
Definition state.c:23

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_STATE, election_result_t::host_id, consensus_state::metrics, consensus_state::metrics_count, SESSION_ID_SIZE, SET_ERRNO, and election_result_t::timestamp_ns.

Referenced by consensus_state_compute_election().