topology.h File Reference

Ring topology management. More...

Go to the source code of this file.

Functions
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.
void	consensus_topology_destroy (consensus_topology_t *topology)
	Destroy topology.
int	consensus_topology_get_position (const consensus_topology_t *topology)
	Get my position in ring (0 = first).
bool	consensus_topology_am_leader (const consensus_topology_t *topology)
	Check if I am the ring leader (last position).
asciichat_error_t	consensus_topology_get_next (const consensus_topology_t *topology, uint8_t out_id[SESSION_ID_SIZE])
	Get next participant ID in ring.
asciichat_error_t	consensus_topology_get_prev (const consensus_topology_t *topology, uint8_t out_id[SESSION_ID_SIZE])
	Get previous participant ID in ring.
asciichat_error_t	consensus_topology_get_leader (const consensus_topology_t *topology, uint8_t out_id[SESSION_ID_SIZE])
	Get ring leader ID (last participant).
asciichat_error_t	consensus_topology_get_all (const consensus_topology_t *topology, uint8_t out_ids[MAX_SESSION_PARTICIPANTS][SESSION_ID_SIZE], int *out_count)
	Get all participant IDs in ring order.

Detailed Description

Ring topology management.

Definition in file topology.h.

Function Documentation

consensus_topology_am_leader()

bool consensus_topology_am_leader

(

const consensus_topology_t *

topology

)

Check if I am the ring leader (last position).

Parameters

topology

Topology handle

Returns

true if I am the leader, false otherwise

Definition at line 85 of file topology.c.

                                                                        {
  if (!topology)
    return false;
  return topology->my_position == (topology->num_participants - 1);
}

References consensus_topology::my_position, and consensus_topology::num_participants.

Referenced by consensus_coordinator_process(), consensus_state_collection_complete(), and consensus_state_is_leader().

consensus_topology_create()

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.

Sorts participants lexicographically and computes ring positions. Returns error if my_id not in participant list.

Parameters

participant_ids	Array of 16-byte UUIDs (up to 128 participants)
num_participants	Number of participants (1-128)
my_id	My 16-byte UUID (must be in participant_ids)
out_topology	Output topology handle (caller must destroy)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 44 of file topology.c.

                                                                                 {
  if (!participant_ids || !my_id || !out_topology || num_participants <= 0 ||
      num_participants > MAX_SESSION_PARTICIPANTS) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid topology creation parameters");
  }
 
  consensus_topology_t *topology = SAFE_MALLOC(sizeof(*topology), consensus_topology_t *);
  defer_named(release_topology, SAFE_FREE(topology));
  memset(topology, 0, sizeof(*topology));
 
  // Copy and sort participant IDs lexicographically
  memcpy(topology->participant_ids, participant_ids, num_participants * 16);
  topology->num_participants = num_participants;
 
  qsort(topology->participant_ids, num_participants, 16, qsort_uuid_compare);
 
  // Find my position
  topology->my_position = find_uuid_position(topology->participant_ids, num_participants, my_id);
  if (topology->my_position < 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "My UUID not found in participant list");
  }
 
  *out_topology = topology;
  defer_cancel(release_topology);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, MAX_SESSION_PARTICIPANTS, consensus_topology::my_position, consensus_topology::num_participants, consensus_topology::participant_ids, SAFE_FREE, SAFE_MALLOC, SESSION_ID_SIZE, and SET_ERRNO.

Referenced by session_consensus_create(), and session_consensus_set_topology().

consensus_topology_destroy()

void consensus_topology_destroy

(

consensus_topology_t *

topology

)

Destroy topology.

Parameters

topology

Topology handle (safe to pass NULL)

Definition at line 73 of file topology.c.

                                                                {
  if (topology) {
    SAFE_FREE(topology);
  }
}

References SAFE_FREE.

Referenced by session_consensus_create(), session_consensus_destroy(), and session_consensus_set_topology().

consensus_topology_get_all()

asciichat_error_t consensus_topology_get_all	(	const consensus_topology_t *	topology,
		uint8_t	out_ids[MAX_SESSION_PARTICIPANTS][SESSION_ID_SIZE],
		int *	out_count )

Get all participant IDs in ring order.

Parameters

topology	Topology handle
out_ids	Array to fill with 16-byte UUIDs (must hold 64*16 bytes)
out_count	Output number of participants

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 120 of file topology.c.

                                                             {
  if (!topology || !out_ids || !out_count) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  memcpy(out_ids, topology->participant_ids, topology->num_participants * 16);
  *out_count = topology->num_participants;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, MAX_SESSION_PARTICIPANTS, consensus_topology::num_participants, consensus_topology::participant_ids, SESSION_ID_SIZE, and SET_ERRNO.

consensus_topology_get_leader()

asciichat_error_t consensus_topology_get_leader	(	const consensus_topology_t *	topology,
		uint8_t	out_id[SESSION_ID_SIZE] )

Get ring leader ID (last participant).

Parameters

topology	Topology handle
out_id	Output 16-byte UUID of ring leader

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 111 of file topology.c.

                                                                                                                       {
  if (!topology || !out_id) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  memcpy(out_id, topology->participant_ids[topology->num_participants - 1], SESSION_ID_SIZE);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, consensus_topology::num_participants, consensus_topology::participant_ids, SESSION_ID_SIZE, and SET_ERRNO.

consensus_topology_get_next()

asciichat_error_t consensus_topology_get_next	(	const consensus_topology_t *	topology,
		uint8_t	out_id[SESSION_ID_SIZE] )

Get next participant ID in ring.

Wraps around from last position to first.

Parameters

topology	Topology handle
out_id	Output 16-byte UUID of next participant

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 91 of file topology.c.

                                                                                                                     {
  if (!topology || !out_id) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  int next_pos = (topology->my_position + 1) % topology->num_participants;
  memcpy(out_id, topology->participant_ids[next_pos], SESSION_ID_SIZE);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, consensus_topology::my_position, consensus_topology::num_participants, consensus_topology::participant_ids, SESSION_ID_SIZE, and SET_ERRNO.

consensus_topology_get_position()

int consensus_topology_get_position

(

const consensus_topology_t *

topology

)

Get my position in ring (0 = first).

Parameters

topology

Topology handle

Returns

My position in ring order, or -1 if invalid

Definition at line 79 of file topology.c.

                                                                          {
  if (!topology)
    return -1;
  return topology->my_position;
}

References consensus_topology::my_position.

consensus_topology_get_prev()

asciichat_error_t consensus_topology_get_prev	(	const consensus_topology_t *	topology,
		uint8_t	out_id[SESSION_ID_SIZE] )

Get previous participant ID in ring.

Wraps around from first position to last.

Parameters

topology	Topology handle
out_id	Output 16-byte UUID of previous participant

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 101 of file topology.c.

                                                                                                                     {
  if (!topology || !out_id) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  int prev_pos = (topology->my_position - 1 + topology->num_participants) % topology->num_participants;
  memcpy(out_id, topology->participant_ids[prev_pos], SESSION_ID_SIZE);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, consensus_topology::my_position, consensus_topology::num_participants, consensus_topology::participant_ids, SESSION_ID_SIZE, and SET_ERRNO.