sapi_voter.h File Reference

N-way voting across registered sapi_channel_t links (2oo2/2oo3/NMR). More...

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include "safeapi/utils/status/sapi_status.h"
#include "safeapi/redundancy/channel_link/sapi_channel.h"

Include dependency graph for sapi_voter.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	sapi_voter_config_t
	Configuration for sapi_voter_init(). More...
struct	sapi_voter_storage_t
	Storage for one voter instance (opaque to caller). No dynamic memory. More...

Macros
#define	SAPI_VOTER_MAX_CHANNELS   8U
	Maximum number of channels a single voter can register.
#define	SAPI_VOTER_MAX_MESSAGE_SIZE   256U
	Maximum payload size sapi_voter_send()/_receive() supports.

Typedefs
typedef bool(*)	sapi_voter_compare_fn(const void *a, const void *b, size_t size, void *user_ctx)
	Optional custom comparison callback.
typedef sapi_voter_storage_t	sapi_voter_t
	Opaque handle to a voter instance.

Enumerations
enum	sapi_voting_strategy_t { SAPI_VOTING_2OO2 = 1 , SAPI_VOTING_2OO3 = 2 , SAPI_VOTING_NMR = 3 }
	Voting strategy: how many registered channels must agree. More...
enum	sapi_voting_result_t { SAPI_VOTING_AGREED = 0 , SAPI_VOTING_DISAGREED = 1 , SAPI_VOTING_TIMEOUT = 2 , SAPI_VOTING_INSUFFICIENT_QUORUM = 3 }
	Outcome of one sapi_voter_receive() call. More...

Functions
sapi_status_t	sapi_voter_init (sapi_voter_storage_t *storage, const sapi_voter_config_t *config)
	Initializes a voter with zero registered channels.
sapi_status_t	sapi_voter_register_channel (sapi_voter_t *voter, sapi_channel_t *channel)
	Registers one already-initialized channel with this voter.
sapi_status_t	sapi_voter_send (sapi_voter_t *voter, const void *data, size_t data_size)
	Broadcasts data to every registered, healthy channel.
sapi_status_t	sapi_voter_receive (sapi_voter_t *voter, void *data, size_t data_size, sapi_voting_result_t *result, size_t *bytes_received)
	Receives from every registered, healthy channel and votes.
sapi_status_t	sapi_voter_get_aggregated_health (const sapi_voter_t *voter, uint32_t *healthy_count, uint32_t *total_disagreements)
	Aggregated health across every registered channel.
uint32_t	sapi_voter_get_channel_count (const sapi_voter_t *voter)
	Number of channels currently registered with this voter.
sapi_channel_t *	sapi_voter_get_channel (const sapi_voter_t *voter, uint32_t index)
	Direct access to one registered channel, by index.
sapi_channel_t *	sapi_voter_get_channel_by_name (const sapi_voter_t *voter, const char *name)
	Direct access to one registered channel, by name (e.g. "ChannelAtoB") - the name each channel was given via sapi_channel_config_t::name at its own sapi_channel_init() time.
sapi_status_t	sapi_voter_destroy (sapi_voter_t *voter)
	Destroys a voter instance.

Detailed Description

N-way voting across registered sapi_channel_t links (2oo2/2oo3/NMR).

ADR-025: this is the voting engine that used to live inside sapi_channel before that type was split into a single-link primitive. Register 1..SAPI_VOTER_MAX_CHANNELS already-initialized sapi_channel_t instances, then use sapi_voter_send()/ _receive() the way sapi_channel_send()/_receive() used to work.

Definition in file sapi_voter.h.