rte_state_transfer.h File Reference

Declarative registry of application state that must survive a STANDBY -> ONLINE promotion (RCA/OCORA compatibility initiative). More...

#include <stdint.h>
#include <stddef.h>
#include "rte/utils/status/rte_status.h"

Include dependency graph for rte_state_transfer.h:

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

Go to the source code of this file.

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

Declarative registry of application state that must survive a STANDBY -> ONLINE promotion (RCA/OCORA compatibility initiative).

The Platform-owned registry of the fields an application must hand over on a promotion: the application REGISTERS which of its own data fields are transferred (name, pointer, size, optionally its own per-field codec) instead of the framework hardcoding that list. RBC_GP builds its negotiation state codec from this registry (RBC_GP/src/application/AB/GP/com/ab_gp_channel_negotiate.c, build_state_transfer_registry(): its train sessions and route database); the hand-rolled fixed struct and byte-offset codec it used before are gone. See docs/rca/ at the workspace root and the workspace root TODO.dox's "Platform (RCA/OCORA)" section.

This module does NOT decide WHEN a transfer happens, or over what transport - it only knows how to pack/unpack whatever has been registered into/from one bounds-checked buffer. Cadence (hot/warm/cold) is rte_redundancy_config_t::standby_mode's job; carrying the encoded buffer across the wire is the caller's (e.g. RBC_GP encodes it into the state region of the rte_site_role frame through that service's encode_state/receive_state callbacks, rte_site_role.h).

REQ-STATE-TRANSFER-001: no dynamic allocation; a fixed-size static field table, caller-owned buffers for encode/decode. REQ-STATE-TRANSFER-002: fields are packed/unpacked in registration order, byte-for-byte, no padding inserted between them.

Definition in file rte_state_transfer.h.