sapi_channel.h File Reference

A single redundant "channel": an opaque transport handle plus send/receive callbacks, with basic health bookkeeping. More...

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

Include dependency graph for sapi_channel.h:

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

Go to the source code of this file.

Data Structures
struct	sapi_channel_health_t
	Health statistics for one vital channel. More...
struct	sapi_channel_config_t
	Configuration for sapi_channel_init(). More...
struct	sapi_channel_storage_t
	Storage for one vital channel instance (opaque to caller). More...

Typedefs
typedef sapi_status_t(*)	sapi_channel_send_fn(void *channel_handle, const void *data, size_t data_size)
	Backend send callback: transmits on this channel's underlying transport.
typedef sapi_status_t(*)	sapi_channel_recv_fn(void *channel_handle, void *data, size_t data_size, uint32_t timeout_ms)
	Backend receive callback: reads from this channel's underlying transport.
typedef sapi_channel_storage_t	sapi_channel_t
	Opaque handle to a vital channel instance.

Functions
sapi_status_t	sapi_channel_init (sapi_channel_storage_t *storage, const sapi_channel_config_t *config)
	Initializes one vital channel over a caller-supplied transport.
sapi_status_t	sapi_channel_send (sapi_channel_t *handle, const void *data, size_t data_size)
	Sends data on this channel via its backend send callback.
sapi_status_t	sapi_channel_receive (sapi_channel_t *handle, void *data, size_t data_size, uint32_t timeout_ms)
	Receives data on this channel via its backend receive callback.
sapi_status_t	sapi_channel_get_health (const sapi_channel_t *handle, sapi_channel_health_t *out_health)
	Queries this channel's health statistics.
const char *	sapi_channel_get_name (const sapi_channel_t *handle)
	Returns this channel's name, as given in sapi_channel_config_t::name at sapi_channel_init() time.
sapi_status_t	sapi_channel_set_healthy (sapi_channel_t *handle, bool is_healthy)
	Marks this channel healthy/unhealthy.
sapi_status_t	sapi_channel_destroy (sapi_channel_t *handle)
	Destroys a vital channel instance.

Detailed Description

A single redundant "channel": an opaque transport handle plus send/receive callbacks, with basic health bookkeeping.

REDESIGNED (ADR-025): prior to this, sapi_channel_t wrapped N redundant channels and did 2oo2/2oo3/NMR voting between them in one type. That voting engine has moved to sapi_voter (register N sapi_channel_t instances into a sapi_voter_t); a new sapi_cross_comparator does the same for exactly 2 channels. This type is now the unit both of those register: one link, validated dispatch to its backend, nothing more - the same "validate then dispatch to a backend callback" shape as sapi_timer/sapi_nvm elsewhere in this codebase, just with the backend supplied directly in the config (no separate register_backend() call, since a channel has exactly one backend for its whole lifetime, unlike a process-global OAL service).

Definition in file sapi_channel.h.