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

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

Go to the source code of this file.

Data Structures

struct  session_consensus
 When code needs to work with session consensus, it keeps topology, coordinator, send_packet, on_election here instead of scattering it across globals. Initialization establishes the handles and sizes; teardown must release any allocation, lock, thread, or callback context recorded in those fields. More...

Typedefs

typedef struct session_consensus session_consensus_t
 When code needs to work with session consensus, it keeps topology, coordinator, send_packet, on_election here instead of scattering it across globals. Initialization establishes the handles and sizes; teardown must release any allocation, lock, thread, or callback context recorded in those fields.

Functions

asciichat_error_t session_consensus_create (const uint8_t my_id[SESSION_ID_SIZE], bool is_leader, const uint8_t participant_ids[MAX_SESSION_PARTICIPANTS][SESSION_ID_SIZE], int num_participants, const session_consensus_callbacks_t *callbacks, session_consensus_t **out_consensus)
 Create a new session consensus instance.
void session_consensus_destroy (session_consensus_t *consensus)
 Destroy consensus instance and free all resources.
asciichat_error_t session_consensus_process (session_consensus_t *consensus, uint32_t timeout_ms)
 Main consensus processing loop - call periodically.
asciichat_error_t session_consensus_set_topology (session_consensus_t *consensus, const uint8_t participant_ids[MAX_SESSION_PARTICIPANTS][SESSION_ID_SIZE], int num_participants)
 Update ring topology when participants change.
asciichat_error_t session_consensus_on_collection_start (session_consensus_t *consensus, uint32_t round_id, uint64_t deadline_ns)
 Handle incoming STATS_COLLECTION_START packet.
asciichat_error_t session_consensus_on_stats_update (session_consensus_t *consensus, const uint8_t sender_id[SESSION_ID_SIZE], const participant_metrics_t *metrics, uint8_t num_metrics)
 Handle incoming STATS_UPDATE packet (metrics relayed around ring).
asciichat_error_t session_consensus_on_election_result (session_consensus_t *consensus, const uint8_t host_id[SESSION_ID_SIZE], const char host_address[ACIP_ADDRESS_SIZE], uint16_t host_port, const uint8_t backup_id[SESSION_ID_SIZE], const char backup_address[ACIP_ADDRESS_SIZE], uint16_t backup_port)
 Handle incoming ELECTION_RESULT packet from leader.
asciichat_error_t session_consensus_get_elected_host (session_consensus_t *consensus, uint8_t out_host_id[SESSION_ID_SIZE], char out_host_address[ACIP_ADDRESS_SIZE], uint16_t *out_host_port, uint8_t out_backup_id[SESSION_ID_SIZE], char out_backup_address[ACIP_ADDRESS_SIZE], uint16_t *out_backup_port)
 Get the currently elected host.
bool session_consensus_is_ready (session_consensus_t *consensus)
 Check if consensus has completed at least one round.
int session_consensus_get_state (session_consensus_t *consensus)
 Get current consensus state.
uint64_t session_consensus_time_until_next_round (session_consensus_t *consensus)
 Get time until next consensus round in nanoseconds.
int session_consensus_get_metrics_count (session_consensus_t *consensus)
 Get count of metrics collected in current round.

Detailed Description

Mode-agnostic ring consensus abstraction implementation.

Definition in file consensus.c.

Typedef Documentation

◆ session_consensus_t

When code needs to work with session consensus, it keeps topology, coordinator, send_packet, on_election here instead of scattering it across globals. Initialization establishes the handles and sizes; teardown must release any allocation, lock, thread, or callback context recorded in those fields.

Mode-specific hooks used by the session consensus adapter.

Session adapter that owns consensus topology, coordination, and election state.

The handle connects the generic consensus modules to mode-specific callbacks, retains the local participant identity and leadership role, and forwards packet, metrics, and election events through the caller's context.

Opaque session consensus handle

Function Documentation

◆ session_consensus_create()

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

Create a new session consensus instance.

Initializes consensus for a participant in a session. The consensus will manage ring topology, metrics collection, and host election according to the configured ring parameters.

Parameters
my_id16-byte UUID of this participant
is_leaderWhether this participant should run elections (typically last in ring)
participant_idsArray of participant UUIDs (up to 128)
num_participantsCount of participants
callbacksCallback functions for mode integration
out_consensusOutput consensus handle (caller must destroy)
Returns
ASCIICHAT_OK on success, error code otherwise

Definition at line 117 of file consensus.c.

118 {
119 if (!my_id || !callbacks || !out_consensus) {
120 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: my_id=%p, callbacks=%p, out_consensus=%p", my_id, callbacks, out_consensus);
121 }
122
123 if (!callbacks->send_packet || !callbacks->on_election || !callbacks->get_metrics) {
124 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);
125 }
126
127 if (num_participants < 1 || num_participants > MAX_SESSION_PARTICIPANTS) {
128 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid participant count: %d", num_participants);
129 }
130
131 // Allocate consensus handle
133 if (!consensus) {
134 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate session consensus");
135 }
136
137 // Copy identity
138 memcpy(consensus->my_id, my_id, SESSION_ID_SIZE);
139 consensus->is_leader = is_leader;
140
141 // Copy callbacks
142 consensus->send_packet = callbacks->send_packet;
143 consensus->on_election = callbacks->on_election;
144 consensus->get_metrics = callbacks->get_metrics;
145 consensus->election = callbacks->election; // May be NULL
146 consensus->context = callbacks->context;
147
148 // Create topology
149 asciichat_error_t err = consensus_topology_create(participant_ids, num_participants, my_id, &consensus->topology);
150 if (err != ASCIICHAT_OK) {
151 SAFE_FREE(consensus);
152 return err;
153 }
154
155 // Create coordinator
156 err = consensus_coordinator_create(my_id, consensus->topology, session_consensus_election_bridge, consensus, &consensus->coordinator);
157 if (err != ASCIICHAT_OK) {
159 SAFE_FREE(consensus);
160 return err;
161 }
162
164
165 log_debug("Session consensus created: my_id=%.*s, is_leader=%d, participants=%d", 16, my_id, is_leader, num_participants);
166
167 *out_consensus = consensus;
168 return ASCIICHAT_OK;
169}
#define SET_ERRNO(code,...)
struct session_consensus session_consensus_t
When code needs to work with session consensus, it keeps topology, coordinator, send_packet,...
asciichat_error_t consensus_coordinator_create(const uint8_t my_id[SESSION_ID_SIZE], const consensus_topology_t *topology, consensus_election_func_t election_func, void *election_context, consensus_coordinator_t **out_coordinator)
Initialize coordinator with given parameters.
Definition coordinator.c:56
void consensus_coordinator_set_metrics_provider(consensus_coordinator_t *coordinator, consensus_metrics_provider_fn provider, void *context)
#define SAFE_FREE(ptr)
#define SAFE_CALLOC(count, size, cast)
asciichat_error_t
Error and exit codes - unified status values (0-255).
Definition error_codes.h:48
@ ERROR_MEMORY
Definition error_codes.h:55
@ ASCIICHAT_OK
Definition error_codes.h:50
@ ERROR_INVALID_PARAM
#define MAX_SESSION_PARTICIPANTS
#define SESSION_ID_SIZE
#define log_debug(...)
Log a DEBUG message.
Definition log/log.h:589
void * context
Opaque context passed to all callbacks.
Definition consensus.h:127
session_consensus_election_fn election
Custom election callback (optional, NULL = use default).
Definition consensus.h:126
session_consensus_on_election_fn on_election
Election result callback.
Definition consensus.h:124
session_consensus_get_metrics_fn get_metrics
Measure metrics callback.
Definition consensus.h:125
session_consensus_send_packet_fn send_packet
Send packet callback.
Definition consensus.h:123
consensus_topology_t * topology
Definition consensus.c:38
session_consensus_get_metrics_fn get_metrics
Definition consensus.c:44
session_consensus_on_election_fn on_election
Definition consensus.c:43
consensus_coordinator_t * coordinator
Definition consensus.c:39
session_consensus_send_packet_fn send_packet
Definition consensus.c:42
session_consensus_election_fn election
Definition consensus.c:45
uint8_t my_id[SESSION_ID_SIZE]
Definition consensus.c:49
void consensus_topology_destroy(consensus_topology_t *topology)
Destroy topology.
Definition topology.c:70
asciichat_error_t consensus_topology_create(const uint8_t participant_ids[MAX_SESSION_PARTICIPANTS][SESSION_ID_SIZE], int num_participants, const uint8_t my_id[SESSION_ID_SIZE], consensus_topology_t **out_topology)
Create new ring topology from participant list.
Definition topology.c:43

References ASCIICHAT_OK, consensus_coordinator_create(), consensus_coordinator_set_metrics_provider(), consensus_topology_create(), consensus_topology_destroy(), session_consensus::context, session_consensus_callbacks_t::context, session_consensus::coordinator, session_consensus::election, session_consensus_callbacks_t::election, ERROR_INVALID_PARAM, ERROR_MEMORY, session_consensus::get_metrics, session_consensus_callbacks_t::get_metrics, session_consensus::is_leader, log_debug, MAX_SESSION_PARTICIPANTS, session_consensus::my_id, session_consensus::on_election, session_consensus_callbacks_t::on_election, SAFE_CALLOC, SAFE_FREE, session_consensus::send_packet, session_consensus_callbacks_t::send_packet, SESSION_ID_SIZE, SET_ERRNO, and session_consensus::topology.

Referenced by consensus_create_for_discovery().

◆ session_consensus_destroy()

void session_consensus_destroy ( session_consensus_t * consensus)

Destroy consensus instance and free all resources.

Parameters
consensusConsensus handle (safe to pass NULL)

Definition at line 171 of file consensus.c.

171 {
172 if (!consensus) {
173 return;
174 }
175
176 if (consensus->coordinator) {
178 }
179
180 if (consensus->topology) {
182 }
183
184 SAFE_FREE(consensus);
185}
void consensus_coordinator_destroy(consensus_coordinator_t *coordinator)
Clean up coordinator resources.

References consensus_coordinator_destroy(), consensus_topology_destroy(), session_consensus::coordinator, SAFE_FREE, 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[SESSION_ID_SIZE],
char out_host_address[ACIP_ADDRESS_SIZE],
uint16_t * out_host_port,
uint8_t out_backup_id[SESSION_ID_SIZE],
char out_backup_address[ACIP_ADDRESS_SIZE],
uint16_t * out_backup_port )

Get the currently elected host.

Returns the most recently elected host and backup. If no election has completed yet, returns the previous stored result if available, or error.

Parameters
consensusConsensus handle
out_host_idOutput: 16-byte UUID of host (caller provides buffer)
out_host_addressOutput: Host address (caller provides buffer, 64 bytes)
out_host_portOutput: Host port
out_backup_idOutput: 16-byte UUID of backup (caller provides buffer)
out_backup_addressOutput: Backup address (caller provides buffer, 64 bytes)
out_backup_portOutput: Backup port
Returns
ASCIICHAT_OK on success, error code otherwise

Definition at line 257 of file consensus.c.

258 {
259 if (!consensus || !out_host_id || !out_host_address || !out_host_port || !out_backup_id || !out_backup_address || !out_backup_port) {
260 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
261 }
262
263 // Get from coordinator
264 asciichat_error_t err = consensus_coordinator_get_current_host(consensus->coordinator, out_host_id, out_backup_id);
265 if (err != ASCIICHAT_OK) {
266 return err;
267 }
268
269 // NOTE: The current API doesn't return addresses/ports. This is a limitation
270 // of the coordinator that should be addressed in a future enhancement.
271 // For now, return zeros and indicate this is a placeholder.
272 memset(out_host_address, 0, ACIP_ADDRESS_SIZE);
273 *out_host_port = 0;
274 memset(out_backup_address, 0, ACIP_ADDRESS_SIZE);
275 *out_backup_port = 0;
276
277 return ASCIICHAT_OK;
278}
#define ACIP_ADDRESS_SIZE
Definition acds_sizes.h:11
asciichat_error_t consensus_coordinator_get_current_host(const consensus_coordinator_t *coordinator, uint8_t out_host_id[SESSION_ID_SIZE], uint8_t out_backup_id[SESSION_ID_SIZE])
Get currently elected host.

References ACIP_ADDRESS_SIZE, ASCIICHAT_OK, consensus_coordinator_get_current_host(), session_consensus::coordinator, ERROR_INVALID_PARAM, SESSION_ID_SIZE, and SET_ERRNO.

◆ session_consensus_get_metrics_count()

int session_consensus_get_metrics_count ( session_consensus_t * consensus)

Get count of metrics collected in current round.

Useful for monitoring collection progress.

Parameters
consensusConsensus handle
Returns
Number of metrics collected, or -1 if invalid

Definition at line 309 of file consensus.c.

309 {
310 if (!consensus) {
311 return -1;
312 }
313
315}
int consensus_coordinator_get_metrics_count(const consensus_coordinator_t *coordinator)
Get count of metrics in current round.

References consensus_coordinator_get_metrics_count(), and session_consensus::coordinator.

◆ session_consensus_get_state()

int session_consensus_get_state ( session_consensus_t * consensus)

Get current consensus state.

Parameters
consensusConsensus handle
Returns
Current state from internal state machine

Definition at line 293 of file consensus.c.

293 {
294 if (!consensus) {
295 return -1;
296 }
297
298 return (int)consensus_coordinator_get_state(consensus->coordinator);
299}
consensus_state_machine_t consensus_coordinator_get_state(const consensus_coordinator_t *coordinator)
Get current coordinator state.

References consensus_coordinator_get_state(), and session_consensus::coordinator.

◆ session_consensus_is_ready()

bool session_consensus_is_ready ( session_consensus_t * consensus)

Check if consensus has completed at least one round.

Returns true if at least one complete consensus round has finished with a valid elected host and backup.

Parameters
consensusConsensus handle
Returns
true if consensus reached, false otherwise

Definition at line 280 of file consensus.c.

280 {
281 if (!consensus) {
282 return false;
283 }
284
285 // Check if we have a valid elected host
286 uint8_t host_id[SESSION_ID_SIZE];
287 uint8_t backup_id[SESSION_ID_SIZE];
288 asciichat_error_t err = consensus_coordinator_get_current_host(consensus->coordinator, host_id, backup_id);
289
290 return err == ASCIICHAT_OK;
291}
unsigned char uint8_t

References ASCIICHAT_OK, consensus_coordinator_get_current_host(), session_consensus::coordinator, and SESSION_ID_SIZE.

◆ 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 )

Handle incoming STATS_COLLECTION_START packet.

Consensus calls this when it receives a collection start from the previous ring participant. Should be called from packet handler in mode.

Parameters
consensusConsensus handle
round_idCollection round ID
deadline_nsUnix nanosecond deadline for collection
Returns
ASCIICHAT_OK on success, error code otherwise

Definition at line 221 of file consensus.c.

221 {
222 if (!consensus) {
223 return SET_ERRNO(ERROR_INVALID_PARAM, "consensus is NULL");
224 }
225
226 return consensus_coordinator_on_collection_start(consensus->coordinator, round_id, deadline_ns);
227}
asciichat_error_t consensus_coordinator_on_collection_start(consensus_coordinator_t *coordinator, uint32_t round_id, uint64_t deadline_ns)
Handle STATS_COLLECTION_START packet.

References consensus_coordinator_on_collection_start(), session_consensus::coordinator, ERROR_INVALID_PARAM, and SET_ERRNO.

◆ session_consensus_on_election_result()

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

Handle incoming ELECTION_RESULT packet from leader.

Consensus calls this when leader announces the elected host. Should be called from packet handler in mode.

Parameters
consensusConsensus handle
host_id16-byte UUID of elected host
host_addressAddress of elected host
host_portPort of elected host
backup_id16-byte UUID of backup host
backup_addressAddress of backup host
backup_portPort of backup host
Returns
ASCIICHAT_OK on success, error code otherwise

Definition at line 237 of file consensus.c.

238 {
239 if (!consensus || !host_id || !backup_id) {
240 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
241 }
242
243 // First acknowledge the election in coordinator
244 asciichat_error_t err = consensus_coordinator_on_election_result(consensus->coordinator, host_id, backup_id);
245 if (err != ASCIICHAT_OK) {
246 return err;
247 }
248
249 // Then call the mode's election callback
250 if (consensus->on_election) {
251 return consensus->on_election(consensus->context, host_id, host_address, host_port, backup_id, backup_address, backup_port);
252 }
253
254 return ASCIICHAT_OK;
255}
asciichat_error_t consensus_coordinator_on_election_result(consensus_coordinator_t *coordinator, const uint8_t host_id[SESSION_ID_SIZE], const uint8_t backup_id[SESSION_ID_SIZE])
Handle ELECTION_RESULT packet.

References ACIP_ADDRESS_SIZE, ASCIICHAT_OK, consensus_coordinator_on_election_result(), session_consensus::context, session_consensus::coordinator, ERROR_INVALID_PARAM, session_consensus::on_election, SESSION_ID_SIZE, and SET_ERRNO.

◆ session_consensus_on_stats_update()

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

Handle incoming STATS_UPDATE packet (metrics relayed around ring).

Consensus calls this when it receives metrics from the previous participant. Should be called from packet handler in mode.

Parameters
consensusConsensus handle
sender_id16-byte UUID of who sent this update
metricsArray of metrics in this packet
num_metricsCount of metrics
Returns
ASCIICHAT_OK on success, error code otherwise

Definition at line 229 of file consensus.c.

229 {
230 if (!consensus || !sender_id || !metrics) {
231 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
232 }
233
234 return consensus_coordinator_on_stats_update(consensus->coordinator, sender_id, metrics, num_metrics);
235}
asciichat_error_t consensus_coordinator_on_stats_update(consensus_coordinator_t *coordinator, const uint8_t sender_id[SESSION_ID_SIZE], const participant_metrics_t *metrics, uint8_t num_metrics)
Handle STATS_UPDATE packet.

References consensus_coordinator_on_stats_update(), session_consensus::coordinator, ERROR_INVALID_PARAM, SESSION_ID_SIZE, and SET_ERRNO.

◆ session_consensus_process()

asciichat_error_t session_consensus_process ( session_consensus_t * consensus,
uint32_t timeout_ms )

Main consensus processing loop - call periodically.

Handles:

  • Round scheduling (every 5 minutes)
  • Collection deadline enforcement (30 seconds)
  • Metrics measurement and relay around ring
  • Election computation (leader only)
  • Result broadcasting

Non-blocking: returns immediately if no action needed. Modes should call this regularly (at least once per second) to ensure timely round scheduling and deadline enforcement.

Parameters
consensusConsensus handle
timeout_msTimeout for this call in milliseconds (0 = non-blocking)
Returns
ASCIICHAT_OK on success, error code otherwise

Definition at line 187 of file consensus.c.

187 {
188 if (!consensus) {
189 return SET_ERRNO(ERROR_INVALID_PARAM, "consensus is NULL");
190 }
191
192 // Call coordinator process
193 return consensus_coordinator_process(consensus->coordinator, timeout_ms);
194}
asciichat_error_t consensus_coordinator_process(consensus_coordinator_t *coordinator, uint32_t timeout_ms)
Main orchestration loop.

References consensus_coordinator_process(), session_consensus::coordinator, ERROR_INVALID_PARAM, and SET_ERRNO.

◆ session_consensus_set_topology()

asciichat_error_t session_consensus_set_topology ( session_consensus_t * consensus,
const uint8_t participant_ids[MAX_SESSION_PARTICIPANTS][SESSION_ID_SIZE],
int num_participants )

Update ring topology when participants change.

Called when the ring topology changes (participants join/leave). Updates the consensus topology and resets any in-progress round.

Parameters
consensusConsensus handle
participant_idsUpdated array of participant UUIDs
num_participantsNew count of participants
Returns
ASCIICHAT_OK on success, error code otherwise

Definition at line 196 of file consensus.c.

196 {
197 if (!consensus || !participant_ids) {
198 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
199 }
200
201 if (num_participants < 1 || num_participants > MAX_SESSION_PARTICIPANTS) {
202 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid participant count: %d", num_participants);
203 }
204
205 // Validate the candidate before releasing the ring still borrowed by the
206 // coordinator. A rejected membership update must preserve the active round.
207 consensus_topology_t *replacement = NULL;
208 asciichat_error_t err = consensus_topology_create(participant_ids, num_participants, consensus->my_id, &replacement);
209 if (err != ASCIICHAT_OK)
210 return err;
211 err = consensus_coordinator_on_ring_members(consensus->coordinator, replacement);
212 if (err != ASCIICHAT_OK) {
213 consensus_topology_destroy(replacement);
214 return err;
215 }
217 consensus->topology = replacement;
218 return ASCIICHAT_OK;
219}
asciichat_error_t consensus_coordinator_on_ring_members(consensus_coordinator_t *coordinator, const consensus_topology_t *new_topology)
Update ring topology when participants change.
struct consensus_topology consensus_topology_t
Ring topology for consensus participants.

References ASCIICHAT_OK, consensus_coordinator_on_ring_members(), consensus_topology_create(), consensus_topology_destroy(), session_consensus::coordinator, ERROR_INVALID_PARAM, MAX_SESSION_PARTICIPANTS, session_consensus::my_id, SESSION_ID_SIZE, SET_ERRNO, and session_consensus::topology.

◆ session_consensus_time_until_next_round()

uint64_t session_consensus_time_until_next_round ( session_consensus_t * consensus)

Get time until next consensus round in nanoseconds.

Useful for scheduling when to call process() next.

Parameters
consensusConsensus handle
Returns
Nanoseconds until next round, or 0 if round is due now

Definition at line 301 of file consensus.c.

301 {
302 if (!consensus) {
303 return 0;
304 }
305
307}
uint64_t consensus_coordinator_time_until_next_round(const consensus_coordinator_t *coordinator)
Get time until next round.

References consensus_coordinator_time_until_next_round(), and session_consensus::coordinator.

Referenced by consensus_suggest_timeout_ms().