State transfer registry (hot/warm/cold standby)

Data Structures
struct	rte_state_field_t
struct	rte_state_transfer_registry_t

Macros
#define	RTE_STATE_TRANSFER_MAX_FIELDS   8U

Typedefs
typedef rte_status_t(*)	rte_state_field_encode_fn(const void *data, uint8_t *out, size_t size)
	Optional custom wire encoder for one field, registered via rte_state_transfer_register_field_ex() - e.g. a field whose live in-memory struct has compiler-inserted padding this module's default raw memcpy would transfer verbatim (uninitialized bytes), or whose wire form is genuinely smaller than its live struct (index/count fields the wire form omits). Must write EXACTLY the field's registered size bytes to out - the same fixed-size contract rte_state_transfer_encode()'s own offset bookkeeping already assumes for a plain (non-callback) field.
typedef rte_status_t(*)	rte_state_field_decode_fn(void *data, const uint8_t *in, size_t size)
	Inverse of rte_state_field_encode_fn - must consume EXACTLY size bytes from in and write the result into *data.

Functions
rte_status_t	rte_state_transfer_registry_init (rte_state_transfer_registry_t *registry)
	Initializes an empty registry.
rte_status_t	rte_state_transfer_register_field (rte_state_transfer_registry_t *registry, const char *name, void *data, size_t size)
	Registers one field. Order matters - encode()/decode() pack/unpack in registration order.
rte_status_t	rte_state_transfer_register_field_ex (rte_state_transfer_registry_t *registry, const char *name, void *data, size_t size, rte_state_field_encode_fn encode_fn, rte_state_field_decode_fn decode_fn)
	Registers one field with a custom wire encoder/decoder pair instead of this module's default raw memcpy - see rte_state_field_t's own doc for when this is needed (e.g. a field whose live struct has padding, or a wire form narrower than its live representation).
size_t	rte_state_transfer_encoded_size (const rte_state_transfer_registry_t *registry)
	Total encoded size (sum of every registered field's size) - the minimum buffer size encode()/decode() need.
rte_status_t	rte_state_transfer_encode (const rte_state_transfer_registry_t *registry, uint8_t *out, size_t out_size, size_t *out_len)
	Packs every registered field's current live value into out, in registration order, back-to-back with no padding.
rte_status_t	rte_state_transfer_decode (const rte_state_transfer_registry_t *registry, const uint8_t *in, size_t in_len)
	Inverse of encode(): overwrites every registered field's live value from in, in registration order.

Detailed Description

Macro Definition Documentation

RTE_STATE_TRANSFER_MAX_FIELDS

#define RTE_STATE_TRANSFER_MAX_FIELDS   8U

Largest number of fields one registry can hold.

Definition at line 45 of file rte_state_transfer.h.

Typedef Documentation

rte_state_field_encode_fn

typedef rte_status_t(*) rte_state_field_encode_fn(const void *data, uint8_t *out, size_t size)

Optional custom wire encoder for one field, registered via rte_state_transfer_register_field_ex() - e.g. a field whose live in-memory struct has compiler-inserted padding this module's default raw memcpy would transfer verbatim (uninitialized bytes), or whose wire form is genuinely smaller than its live struct (index/count fields the wire form omits). Must write EXACTLY the field's registered size bytes to out - the same fixed-size contract rte_state_transfer_encode()'s own offset bookkeeping already assumes for a plain (non-callback) field.

Parameters

[in]	data	The field's own live data pointer, as registered.
[out]	out	Destination for exactly size encoded bytes.
[in]	size	The field's own registered size (the exact byte count to write - NOT necessarily sizeof(*data)).

Returns

RTE_STATUS_OK on success; any other value aborts the whole rte_state_transfer_encode() call with that status.

Definition at line 64 of file rte_state_transfer.h.

rte_state_field_decode_fn

typedef rte_status_t(*) rte_state_field_decode_fn(void *data, const uint8_t *in, size_t size)

Inverse of rte_state_field_encode_fn - must consume EXACTLY size bytes from in and write the result into *data.

Returns

RTE_STATUS_OK on success; any other value aborts the whole rte_state_transfer_decode() call with that status.

Definition at line 72 of file rte_state_transfer.h.

Function Documentation

rte_state_transfer_registry_init()

rte_status_t rte_state_transfer_registry_init

(

rte_state_transfer_registry_t *

registry

)

Initializes an empty registry.

Parameters

[out]

registry

Must not be NULL.

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM if registry is NULL.

Definition at line 8 of file rte_state_transfer.c.

rte_state_transfer_register_field()

rte_status_t rte_state_transfer_register_field	(	rte_state_transfer_registry_t *	registry,
		const char *	name,
		void *	data,
		size_t	size )

Registers one field. Order matters - encode()/decode() pack/unpack in registration order.

Parameters

[in,out]	registry	Must not be NULL.
[in]	name	May be NULL (diagnostic only).
[in]	data	Must not be NULL.
[in]	size	Must be > 0.

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM (NULL registry/data, or size 0); RTE_STATUS_RESOURCE_EXHAUSTED if the registry already holds RTE_STATE_TRANSFER_MAX_FIELDS entries.

Definition at line 18 of file rte_state_transfer.c.

rte_state_transfer_register_field_ex()

rte_status_t rte_state_transfer_register_field_ex	(	rte_state_transfer_registry_t *	registry,
		const char *	name,
		void *	data,
		size_t	size,
		rte_state_field_encode_fn	encode_fn,
		rte_state_field_decode_fn	decode_fn )

Registers one field with a custom wire encoder/decoder pair instead of this module's default raw memcpy - see rte_state_field_t's own doc for when this is needed (e.g. a field whose live struct has padding, or a wire form narrower than its live representation).

Parameters

[in,out]	registry	Must not be NULL.
[in]	name	May be NULL (diagnostic only).
[in]	data	Must not be NULL.
[in]	size	The field's exact encoded byte count. Must be > 0.
[in]	encode_fn	Must not be NULL.
[in]	decode_fn	Must not be NULL.

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM (any required pointer NULL, or size 0); RTE_STATUS_RESOURCE_EXHAUSTED as in rte_state_transfer_register_field().

Definition at line 24 of file rte_state_transfer.c.

rte_state_transfer_encoded_size()

size_t rte_state_transfer_encoded_size

(

const rte_state_transfer_registry_t *

registry

)

Total encoded size (sum of every registered field's size) - the minimum buffer size encode()/decode() need.

Parameters

[in]

registry

Must not be NULL.

Returns

The total size, or 0 if registry is NULL or empty.

Definition at line 56 of file rte_state_transfer.c.

rte_state_transfer_encode()

rte_status_t rte_state_transfer_encode	(	const rte_state_transfer_registry_t *	registry,
		uint8_t *	out,
		size_t	out_size,
		size_t *	out_len )

Packs every registered field's current live value into out, in registration order, back-to-back with no padding.

Parameters

[in]	registry	Must not be NULL.
[out]	out	Destination buffer. Must not be NULL.
[in]	out_size	Usable size of out; must be >= rte_state_transfer_encoded_size(registry).
[out]	out_len	Receives the number of bytes actually written (== rte_state_transfer_encoded_size(registry) on success). May be NULL.

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM (NULL registry/out); RTE_STATUS_RESOURCE_EXHAUSTED if out_size is too small.

Definition at line 72 of file rte_state_transfer.c.

rte_state_transfer_decode()

rte_status_t rte_state_transfer_decode	(	const rte_state_transfer_registry_t *	registry,
		const uint8_t *	in,
		size_t	in_len )

Inverse of encode(): overwrites every registered field's live value from in, in registration order.

Parameters

[in]	registry	Must not be NULL.
[in]	in	Source buffer. Must not be NULL.
[in]	in_len	Usable size of in; must be >= rte_state_transfer_encoded_size(registry).

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM (NULL registry/in); RTE_STATUS_RESOURCE_EXHAUSTED if in_len is too small.

Postcondition

On success, every registered field's live data equals the bytes encode() would have produced from in at that same offset - i.e. the live application state now matches whatever was encoded.

Definition at line 110 of file rte_state_transfer.c.