rte_cross_comparator.h File Reference

Pairwise comparison between exactly 2 registered rte_channel_t links (ADR-025). More...

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include "rte/utils/status/rte_status.h"
#include "rte/utils/safestate/rte_safestate.h"
#include "rte/redundancy/channel_link/rte_channel.h"
#include "rte/redundancy/voter/rte_voter.h"

Include dependency graph for rte_cross_comparator.h:

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

Go to the source code of this file.

Data Structures
struct	rte_cross_comparator_config_t
	Configuration for rte_cross_comparator_init(). More...
struct	rte_cross_comparator_storage_t
	Storage for one cross-comparator instance (opaque to caller). No dynamic memory. More...

Macros
#define	RTE_CROSS_COMPARATOR_MAX_MESSAGE_SIZE   256U
	Maximum payload size rte_cross_comparator_execute() supports.

Typedefs
typedef rte_cross_comparator_storage_t	rte_cross_comparator_t
	Opaque handle to a cross-comparator instance.

Functions
rte_status_t	rte_cross_comparator_init (rte_cross_comparator_storage_t *storage, const rte_cross_comparator_config_t *config)
	Initializes a cross-comparator with zero registered channels.
rte_status_t	rte_cross_comparator_register_channel (rte_cross_comparator_t *cmp, rte_channel_t *channel)
	Registers one already-initialized channel (channel A, then B).
rte_status_t	rte_cross_comparator_execute (rte_cross_comparator_t *cmp, size_t data_size, rte_voting_result_t *result, void *out_data, size_t *out_size)
	Receives from both registered channels and compares them.
rte_status_t	rte_cross_comparator_execute_buffers (rte_cross_comparator_t *cmp, const void *local_data, const void *peer_data, size_t data_size, rte_voting_result_t *result, void *out_data, size_t *out_size)
	Compares two already-in-hand data buffers directly, with the same on_disagreement-then-unconditional-safestate semantics as rte_cross_comparator_execute() - no rte_channel_t registration needed. Added per direct request as part of the RCA/OCORA compatibility initiative's Phase 2b (see docs/rca/ at the workspace root and TODO.dox): an integrator whose local/peer data already arrived through its own transport (e.g. RBC_GP's kind-multiplexed peer_channel, which carries cross-compare traffic alongside checkpoint/site-state frames on one shared link - not something a generic comparator API can transparently subsume) no longer needs to hand-wire two pure in-memory rte_channel_t "already arrived" adapters (send() that is never called, recv() that just returns a buffer) purely to satisfy rte_cross_comparator_execute()'s channel-based interface - this collapses that boilerplate to one call.
rte_status_t	rte_cross_comparator_get_aggregated_health (const rte_cross_comparator_t *cmp, uint32_t *healthy_count, uint32_t *total_disagreements)
	Aggregated health across both registered channels.
rte_status_t	rte_cross_comparator_destroy (rte_cross_comparator_t *cmp)
	Destroys a cross-comparator instance.

Detailed Description

Pairwise comparison between exactly 2 registered rte_channel_t links (ADR-025).

Distinct from rte_voter: a voter does N-modular-redundancy voting on channels that are expected to carry the same computation (pick the majority value). A cross-comparator checks consistency between two independent channels/peers whose agreement is a diagnostic invariant, not a value to pick a winner from - generalizes the pattern RBC_GP's cross-compare used to hand-roll (its ab_gp_channel_crosscompare.c now calls this module).

RCA/OCORA PI-API compatibility note (see docs/rca/RCA_CONCEPT.dox at the workspace root, section 3 "OCORA terminology"): per OCORA's Safe Computing Platform model, the Platform - not the application - owns the decision to transition to a safe state on disagreement between replicas/peers. rte_cross_comparator_execute() therefore ALWAYS enters config->safestate_level on a DISAGREED result; an application can no longer opt out of the transition happening (only earlier, on_disagreement gave the application a chance to react - e.g. clean up - before it does).

Definition in file rte_cross_comparator.h.