OCORA PI-API-compatible Flow Service

Name-addressed publish/subscribe message endpoint (OCORA PI API Annex A.1). More...

Files
file	src/oal/flow/rte_flow.c
	Flow service: validates parameters, then dispatches to the OSAdapter registered via rte_osadapter_flow_register() (ADR-005). See rte_netlink.c for the pattern this follows.

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

Name-addressed publish/subscribe message endpoint (OCORA PI API Annex A.1).

Typedef Documentation

rte_flow_handle_t

typedef struct rte_flow_impl_s* rte_flow_handle_t

Opaque handle to an opened Flow, returned by rte_flow_open().

Definition at line 71 of file rte_flow.h.

Enumeration Type Documentation

rte_flow_oflag_t

enum rte_flow_oflag_t

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).

Enumerator
RTE_FLOW_O_REQUESTER	Sends a request, expects a matching response.
RTE_FLOW_O_RESPONDER	Receives requests, sends matching responses.
RTE_FLOW_O_PUBLISHER	Sends messages to any current/future subscriber.
RTE_FLOW_O_SUBSCRIBER	Receives messages from any publisher on this name.
RTE_FLOW_O_NONBLOCK	Backend-defined non-blocking hint; callers should still pass an explicit timeout_ms (REQ-OAL-FLOW-003) rather than relying on this flag alone.

Definition at line 79 of file rte_flow.h.

rte_flow_channel_t

enum rte_flow_channel_t

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.

Enumerator
RTE_FLOW_CHANNEL_USER	Application/user message.
RTE_FLOW_CHANNEL_CTRL	Platform control message.

Definition at line 96 of file rte_flow.h.

Function Documentation

rte_flow_open()

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.

Parameters

storage	Caller-owned storage for the handle's state. Must not be NULL.
config	Flow configuration. Must not be NULL; config->name must not be NULL; config->message_size must be > 0; config->oflags must set exactly one of PUBLISHER/SUBSCRIBER/REQUESTER/RESPONDER.
out_handle	Receives the opened Flow's handle. Must not be NULL.

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM for a bad argument; RTE_STATUS_TIMEOUT if not opened within config->open_timeout_ms; RTE_STATUS_NOT_INITIALIZED if no OSAdapter is registered (rte_osadapter_flow_register()); RTE_STATUS_NOT_SUPPORTED if the registered OSAdapter does not implement open. REQ-OAL-FLOW-010

Definition at line 58 of file rte_flow.c.

rte_flow_close()

rte_status_t rte_flow_close

(

rte_flow_handle_t

handle

)

Closes (leaves/unregisters/unsubscribes from) a Flow.

Parameters

handle

Handle to close. Must not be NULL. Invalid to use after this call.

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM; RTE_STATUS_NOT_INITIALIZED/ RTE_STATUS_NOT_SUPPORTED as in rte_flow_open(). REQ-OAL-FLOW-013

Definition at line 132 of file rte_flow.c.

rte_flow_send()

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.

Parameters

handle	Flow handle. Must not be NULL.
data	Message data to send. Must not be NULL.
data_size	Size of data in bytes; must be > 0.
channel	Which logical channel (user/control) this message is on.
timeout_ms	Maximum time to wait for the send to complete.

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM; RTE_STATUS_TIMEOUT if the send does not complete in time; RTE_STATUS_HARDWARE_FAULT if the OSAdapter can positively confirm no peer is reachable (not guaranteed on every OSAdapter, see REQ-OAL-FLOW-004); RTE_STATUS_INTERNAL_ERROR for any other OSAdapter-level failure (OSAdapter-dependent: the Platform_Protocol_DDS stub passes it through from rte_netlink_send(), where the Platform_OS_POSIX netlink OSAdapter returns it for a poll() errno other than the retried EINTR, a send() errno other than the retried EINTR/EAGAIN/EWOULDBLOCK and the HARDWARE_FAULT-mapped ECONNREFUSED, or for a short datagram write); RTE_STATUS_NOT_INITIALIZED/RTE_STATUS_NOT_SUPPORTED as in rte_flow_open(). REQ-OAL-FLOW-011

Definition at line 86 of file rte_flow.c.

rte_flow_receive()

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.

Parameters

handle	Flow handle. Must not be NULL.
out_data	Destination buffer. Must not be NULL.
buffer_size	Usable size of out_data in bytes; must be > 0.
out_channel	Receives which logical channel the message arrived on. May be NULL if the caller does not need it.
timeout_ms	Maximum time to wait for a message to arrive.

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM (also returned by the Platform_Protocol_DDS stub when buffer_size is smaller than the Flow's message_size); RTE_STATUS_TIMEOUT if no message arrives in time; RTE_STATUS_HARDWARE_FAULT if the OSAdapter can positively confirm no peer is reachable; RTE_STATUS_DATA_CORRUPTION if the OSAdapter received a message whose length differs from the Flow's message_size (both OSAdapter-dependent, not guaranteed on every OSAdapter, see REQ-OAL-FLOW-004; the Platform_Protocol_DDS stub passes both through from rte_netlink_receive(). On Darwin the Platform_OS_POSIX netlink OSAdapter calls recvfrom() without MSG_TRUNC, so a datagram longer than message_size is cut to message_size and returned as RTE_STATUS_OK, the excess bytes discarded; only a shorter one (other than a stray 1-byte handshake datagram, which is dropped) yields RTE_STATUS_DATA_CORRUPTION. Every other build passes MSG_TRUNC, which on Linux reports the real length, so there a longer one is RTE_STATUS_DATA_CORRUPTION too); RTE_STATUS_INTERNAL_ERROR for any other OSAdapter-level failure (OSAdapter-dependent: passed through by the Platform_Protocol_DDS stub; the Platform_OS_POSIX netlink OSAdapter returns it for a poll() errno other than the retried EINTR, or a recvfrom() errno other than the retried EINTR/EAGAIN/EWOULDBLOCK and the HARDWARE_FAULT-mapped ECONNREFUSED); RTE_STATUS_NOT_INITIALIZED/RTE_STATUS_NOT_SUPPORTED as in rte_flow_open(). REQ-OAL-FLOW-012

Definition at line 111 of file rte_flow.c.

rte_flow_getattr()

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.

Parameters

handle	Flow handle. Must not be NULL.
out_attr	Receives the current attributes. Must not be NULL.

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM; RTE_STATUS_NOT_INITIALIZED/ RTE_STATUS_NOT_SUPPORTED as in rte_flow_open(). REQ-OAL-FLOW-014

Definition at line 149 of file rte_flow.c.

rte_flow_setattr()

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.

Parameters

handle	Flow handle. Must not be NULL.
new_attr	Attributes to apply. Must not be NULL. Backend-defined which fields are actually mutable; immutable fields (e.g. message_size) are ignored, not rejected.
out_old_attr	Receives the attributes as they were before this call. May be NULL if the caller does not need it.

Returns

RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM; RTE_STATUS_NOT_INITIALIZED/ RTE_STATUS_NOT_SUPPORTED as in rte_flow_open(). REQ-OAL-FLOW-015

Definition at line 166 of file rte_flow.c.