rte_flow.h File Reference

OS Abstraction Layer - OCORA PI-API-compatible Flow service. More...

#include "rte/utils/status/rte_status.h"
#include "rte/utils/types/rte_types.h"

Include dependency graph for rte_flow.h:

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

Go to the source code of this file.

Data Structures
struct	rte_flow_attr_t
	Flow attributes (OCORA PI API Annex A.1 leaves fl_attr's content as "to be defined" - this is this framework's own concrete, deliberately minimal choice of static+dynamic attributes, not a claim of OCORA-authored content). More...
struct	rte_flow_config_t
	Configuration for rte_flow_open(). More...

Typedefs
typedef struct rte_flow_impl_s *	rte_flow_handle_t
	Opaque handle to an opened Flow, returned by rte_flow_open().

Enumerations
enum	rte_flow_oflag_t {   RTE_FLOW_O_REQUESTER = 1 , RTE_FLOW_O_RESPONDER = 2 , RTE_FLOW_O_PUBLISHER = 4 , RTE_FLOW_O_SUBSCRIBER = 8 ,   RTE_FLOW_O_NONBLOCK = 16 }
	Open-mode bitmask, matching OCORA PI API Annex A.1's e_fl_oflags values exactly (so an integrator porting real OCORA-authored configuration data does not need to remap numeric flag values). More...
enum	rte_flow_channel_t { RTE_FLOW_CHANNEL_USER = 1 , RTE_FLOW_CHANNEL_CTRL = 2 }
	Message-channel discriminator, matching OCORA PI API Annex A.1's e_fl_channels: a Flow can carry ordinary application (user) traffic and platform control traffic on the same opened endpoint, distinguished per send/receive call. More...

Functions
	RTE_DECLARE_STORAGE (rte_flow_storage_t, 64U)
	Caller-owned, fixed-size storage backing one rte_flow_handle_t.
rte_status_t	rte_flow_open (rte_flow_storage_t *storage, const rte_flow_config_t *config, rte_flow_handle_t *out_handle)
	Opens (joins/registers/subscribes to, per OCORA's own fl_open() doc) a named Flow.
rte_status_t	rte_flow_close (rte_flow_handle_t handle)
	Closes (leaves/unregisters/unsubscribes from) a Flow.
rte_status_t	rte_flow_send (rte_flow_handle_t handle, const void *data, size_t data_size, rte_flow_channel_t channel, rte_duration_ms_t timeout_ms)
	Sends one fixed-size message on the given channel, blocking at most timeout_ms.
rte_status_t	rte_flow_receive (rte_flow_handle_t handle, void *out_data, size_t buffer_size, rte_flow_channel_t *out_channel, rte_duration_ms_t timeout_ms)
	Receives one fixed-size message, blocking at most timeout_ms.
rte_status_t	rte_flow_getattr (rte_flow_handle_t handle, rte_flow_attr_t *out_attr)
	Reads this Flow's current (static and dynamic) attributes.
rte_status_t	rte_flow_setattr (rte_flow_handle_t handle, const rte_flow_attr_t *new_attr, rte_flow_attr_t *out_old_attr)
	Sets this Flow's mutable (dynamic) attributes.

Detailed Description

OS Abstraction Layer - OCORA PI-API-compatible Flow service.

A name-based, publish/subscribe (or request/response) message endpoint, matching the shape OCORA's "Generic Safe Computing Platform - Specification of the PI API between Application and Platform" (v2.0, July 2022) Annex A.1 sketches in flows.h: fl_open/ fl_close/fl_send/fl_receive/fl_getattr/fl_setattr, an e_fl_oflags open-mode bitmask (O_REQUESTER/O_RESPONDER/O_PUBLISHER/ O_SUBSCRIBER/O_NONBLOCK), and a USER/CTRL channel discriminator on send/receive. Function names here use this project's own rte_ prefix convention instead of shadowing OCORA's bare fl_* names verbatim - the intent is shape/semantic compatibility with the PI API, not literal symbol-name compatibility.

Deliberately NOT a thin wrapper over rte_netlink (oal/netlink/ rte_netlink.h): netlink is connection-oriented point-to-point (LISTEN/CONNECT, host:port) - a Flow is name/topic-addressed publish-subscribe, the same shape a real DDS OSAdapter provides natively. Forcing Flow through netlink's host:port model would waste a DDS OSAdapter's actual pub/sub capability (topic discovery, N subscribers) later. This service has its own OSAdapter seam instead (rte_osadapter/flow/rte_osadapter_flow.h) so a POSIX/TCP OSAdapter can emulate pub/sub over point-to-point links today, and a DDS OSAdapter can implement it natively later, with zero change to this header or any Functional-Actor code written against it.

Per the PI API's own model (see docs/rca/RCA-OCORA-PI-API.dox at the workspace root for the OCORA research this is based on), a Flow is the ONLY I/O primitive a replicated Functional Actor uses - N-way voting/replication of what is sent/received over a Flow is meant to happen transparently, beneath this API, inside the Platform/RTE layer. This header defines the actor-facing surface only; the replication/voting layer underneath it (built from this framework's existing rte_voter/rte_cross_comparator primitives) is tracked as separate, follow-up work - see the workspace root TODO.dox (G3 and Phase 2b, transparent voting under rte_flow).

REQ-OAL-FLOW-001: no dynamic allocation; caller supplies storage. REQ-OAL-FLOW-002: rte_flow_open() shall never block longer than config->open_timeout_ms. REQ-OAL-FLOW-003: send/receive shall accept an explicit timeout and shall never block indefinitely by default - a deliberate strengthening beyond the PI API sketch (which relies on O_NONBLOCK alone), matching every other blocking call in this framework (e.g. REQ-OAL-NETLINK-003). REQ-OAL-FLOW-004: this service provides no message ordering, deduplication, or delivery guarantee of its own, same posture as rte_netlink (REQ-OAL-NETLINK-014).

Definition in file rte_flow.h.