Files
file	src/redundancy/channel_link/sapi_channel.c
	One redundant channel: validates parameters, then dispatches to its configured send/recv callbacks, tracking health as a side effect (ADR-025).

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

Typedef Documentation

◆ sapi_channel_send_fn

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.

Parameters

[in]	channel_handle	Opaque transport handle (as supplied in sapi_channel_config_t::channel_handle)
[in]	data	Data to send
[in]	data_size	Size of data in bytes

Returns: SAPI_STATUS_OK on success; SAPI_STATUS_TIMEOUT if the operation times out; SAPI_STATUS_HARDWARE_FAULT on any other send error.

Definition at line 67 of file sapi_channel.h.

◆ sapi_channel_recv_fn

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.

Parameters

[in]	channel_handle	Opaque transport handle
[out]	data	Buffer to receive data
[in]	data_size	Size of data buffer
[in]	timeout_ms	Timeout in milliseconds

Returns: SAPI_STATUS_OK on success; SAPI_STATUS_TIMEOUT if the operation times out; SAPI_STATUS_HARDWARE_FAULT on any other receive error.

Definition at line 82 of file sapi_channel.h.

◆ sapi_channel_t

typedef sapi_channel_storage_t sapi_channel_t

Opaque handle to a vital channel instance.

Created by sapi_channel_init(); used directly, or registered into a sapi_voter_t (N-way voting) or sapi_cross_comparator_t (2-way comparison) for the redundancy/comparison use case.

Definition at line 127 of file sapi_channel.h.

Function Documentation

◆ sapi_channel_init()

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.

Parameters

[out]	storage	Pre-allocated storage. Must not be NULL.
[in]	config	Configuration with send/recv callbacks. Must not be NULL; config->send and config->recv must not be NULL.

Returns: SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if storage or config is NULL, or config->send/config->recv is NULL

Precondition: storage != NULL; config != NULL, config->send != NULL, config->recv != NULL

Postcondition: On success, storage is initialized with is_healthy = true and all counters at 0.

Safety:: No dynamic memory allocation. Performs no I/O itself - the underlying transport must already be operational.

REQ-CHANNEL-001: No dynamic allocation; caller supplies storage. REQ-CHANNEL-002: Rejects a NULL config->send/config->recv.

Local makros Local types declarations Local variables declarations Global variables declarations Local function declarations Global functions

Definition at line 23 of file sapi_channel.c.

◆ sapi_channel_send()

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.

Parameters

[in]	handle	Vital channel handle. Must not be NULL and must have been initialized.
[in]	data	Data to send. Must not be NULL.
[in]	data_size	Size of data in bytes. Must be > 0.

Returns: SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if handle/data is NULL, data_size is 0, or handle was never initialized; Whatever config->send() itself returns on failure (typically SAPI_STATUS_TIMEOUT or SAPI_STATUS_HARDWARE_FAULT)

Postcondition: health.send_count or health.send_error_count is incremented; on failure, health.last_error is updated.

REQ-CHANNEL-003: Dispatches to config->send and updates health counters on every call, regardless of outcome.

Definition at line 56 of file sapi_channel.c.

◆ sapi_channel_receive()

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.

Parameters

[in]	handle	Vital channel handle. Must not be NULL and must have been initialized.
[out]	data	Buffer to receive data. Must not be NULL.
[in]	data_size	Size of data buffer. Must be > 0.
[in]	timeout_ms	Timeout passed to config->recv().

Returns: SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if handle/data is NULL, data_size is 0, or handle was never initialized; Whatever config->recv() itself returns on failure

Postcondition: health.receive_count or health.receive_error_count is incremented; on failure, health.last_error is updated.

REQ-CHANNEL-003: Dispatches to config->recv and updates health counters on every call, regardless of outcome.

Definition at line 84 of file sapi_channel.c.

◆ sapi_channel_get_health()

sapi_status_t sapi_channel_get_health	(	const sapi_channel_t *	handle,
		sapi_channel_health_t *	out_health )

Queries this channel's health statistics.

Parameters

[in]	handle	Vital channel handle. Must not be NULL.
[out]	out_health	Receives a copy of the current health state. Must not be NULL.

Returns: SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if handle or out_health is NULL

Safety:: Read-only; safe to call from any context.

Definition at line 113 of file sapi_channel.c.

◆ sapi_channel_get_name()

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.

Parameters

[in] handle Vital channel handle. Must not be NULL.

Returns: The channel's name (may itself be NULL if none was configured, or if handle was never initialized); NULL if handle is NULL.

Safety:: Read-only; safe to call from any context.

Definition at line 124 of file sapi_channel.c.

◆ sapi_channel_set_healthy()

sapi_status_t sapi_channel_set_healthy	(	sapi_channel_t *	handle,
		bool	is_healthy )

Marks this channel healthy/unhealthy.

Intended for a sapi_voter_t/sapi_cross_comparator_t (or any other owner) to call after deciding, by its own policy, that this channel should stop (or resume) participating - this module itself never changes is_healthy on its own (a single I/O failure alone does not mark a channel unhealthy; that decision belongs to the owner tracking failures across multiple channels).

Parameters

[in]	handle	Vital channel handle. Must not be NULL.
[in]	is_healthy	New health state.

Returns: SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if handle is NULL

REQ-CHANNEL-004: is_healthy defaults true at init and is never cleared automatically by this module - only via this explicit call.

Definition at line 133 of file sapi_channel.c.

◆ sapi_channel_destroy()

sapi_status_t sapi_channel_destroy ( sapi_channel_t * handle )

Destroys a vital channel instance.

No dynamic memory to free; the underlying transport is NOT closed (caller retains ownership of channel_handle).

Parameters

[in] handle Vital channel handle. May be NULL.

Returns: SAPI_STATUS_OK always (including when handle is NULL).

Safety:: Idempotent; safe to call with NULL.

Definition at line 144 of file sapi_channel.c.

Files

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ sapi_channel_send_fn

◆ sapi_channel_recv_fn

◆ sapi_channel_t

Function Documentation

◆ sapi_channel_init()

◆ sapi_channel_send()

◆ sapi_channel_receive()

◆ sapi_channel_get_health()

◆ sapi_channel_get_name()

◆ sapi_channel_set_healthy()

◆ sapi_channel_destroy()