dApp-role E3AP session with a batched, lock-free inbound ring. More...

#include <e3_dapp_session.hpp>

Classes
struct	Impl

Public Member Functions
	DAppSession (libe3::E3Config config, std::size_t queue_capacity=8192)
	Construct the session and register all inbound handlers.
	~DAppSession ()
	DAppSession (const DAppSession &)=delete
DAppSession &	operator= (const DAppSession &)=delete
int	start ()
	Start the agent, re-arming the inbound ring so a stop()->start() cycle works again.
int	wait_for_setup (int timeout_ms)
	Block until the setup handshake completes.
int	release ()
	Send a ReleaseMessage (session keeps running until stop).
void	stop ()
	Stop the agent and shut down the ring so a blocked poll_events returns an empty batch (i.e. empty-after-stop means "done"). Restartable via start.
long	dapp_id () const
	dApp id assigned at setup, or -1 if not yet assigned.
std::string	ran_identifier () const
	RAN identifier from the SetupResponse, or "" if none.
int	setup_response_code () const
	SetupResponse code: 0=positive, 1=negative, -1=not received.
std::size_t	setup_ran_function_count () const
	Number of RAN functions advertised in the SetupResponse.
uint32_t	setup_ran_function_id (std::size_t i) const
	RAN function id of advertised entry `i` (0 if out of range).
std::vector< uint32_t >	setup_ran_function_telemetry (std::size_t i) const
	Telemetry ids of advertised entry `i`.
std::vector< uint32_t >	setup_ran_function_control (std::size_t i) const
	Control ids of advertised entry `i`.
std::vector< uint8_t >	setup_ran_function_data (std::size_t i) const
	Opaque ranFunctionData bytes of advertised entry `i`.
int64_t	subscribe (uint32_t ran_function_id, std::vector< uint32_t > telemetry_ids, std::vector< uint32_t > control_ids, int sub_time_ms, int periodicity)
	Subscribe to a RAN function (after a positive setup).
int	unsubscribe (uint32_t ran_function_id)
	Delete a previously created subscription.
int64_t	send_control (uint32_t ran_function_id, uint32_t control_id, std::vector< uint8_t > action_data, uint32_t sequence_id=0)
	Send a dApp control action to the RAN.
int64_t	send_report (uint32_t ran_function_id, std::vector< uint8_t > report_data, uint32_t sequence_id)
	Send a dApp report to the RAN.
int	send_message_ack (uint32_t request_id, int response_code)
	Acknowledge a request.
std::vector< E3Event >	poll_events (std::size_t max_batch, int timeout_ms)
	Drain up to `max_batch` inbound events, waiting up to `timeout_ms` for the first.
unsigned long long	dropped_events () const
	Total inbound events dropped due to ring overflow (backpressure).

Detailed Description

dApp-role E3AP session with a batched, lock-free inbound ring.

Thread model: two producers push into the ring — the setup-response handler (libe3 setup thread) and the other handlers (libe3 inbound thread), which run concurrently at startup; the Python drainer thread is the single consumer via poll_events. The ring is MPMC, so this is safe (do not "optimize" it to SPSC). All outbound verbs are thread-safe (delegated to libe3::E3Agent).

Definition at line 100 of file e3_dapp_session.hpp.

Constructor & Destructor Documentation

◆ DAppSession() [1/2]

libe3::py::DAppSession::DAppSession	(	libe3::E3Config	config,
		std::size_t	queue_capacity = 8192 )

explicit

Construct the session and register all inbound handlers.

Parameters

config	Agent config; role is forced to E3Role::DAPP.
queue_capacity	Inbound ring capacity (rounded up to a power of two). Sized for high-throughput headroom; overflow increments the drop counter (dropped_events) rather than blocking libe3.

Definition at line 66 of file e3_dapp_session.cpp.

◆ ~DAppSession()

libe3::py::DAppSession::~DAppSession ( )

Definition at line 125 of file e3_dapp_session.cpp.

◆ DAppSession() [2/2]

libe3::py::DAppSession::DAppSession ( const DAppSession & )

delete

Member Function Documentation

◆ dapp_id()

long libe3::py::DAppSession::dapp_id ( ) const

dApp id assigned at setup, or -1 if not yet assigned.

Definition at line 154 of file e3_dapp_session.cpp.

◆ dropped_events()

unsigned long long libe3::py::DAppSession::dropped_events ( ) const

Total inbound events dropped due to ring overflow (backpressure).

Definition at line 284 of file e3_dapp_session.cpp.

◆ operator=()

DAppSession & libe3::py::DAppSession::operator= ( const DAppSession & )

delete

◆ poll_events()

std::vector< E3Event > libe3::py::DAppSession::poll_events	(	std::size_t	max_batch,
		int	timeout_ms )

Drain up to max_batch inbound events, waiting up to timeout_ms for the first.

Blocks on the ring for the first event (latency ≈ ring wakeup), then sweeps up any further already-queued events without blocking. timeout_ms <= 0 polls non-blocking (does not busy-wait). Returns an empty vector on a quiet tick or after stop. The SWIG wrapper releases the GIL for the whole call so libe3's threads run freely while Python waits.

Definition at line 253 of file e3_dapp_session.cpp.

◆ ran_identifier()

std::string libe3::py::DAppSession::ran_identifier ( ) const

RAN identifier from the SetupResponse, or "" if none.

Definition at line 159 of file e3_dapp_session.cpp.

◆ release()

int libe3::py::DAppSession::release ( )

Send a ReleaseMessage (session keeps running until stop).

Returns: ErrorCode as int.

Definition at line 145 of file e3_dapp_session.cpp.

◆ send_control()

int64_t libe3::py::DAppSession::send_control	(	uint32_t	ran_function_id,
		uint32_t	control_id,
		std::vector< uint8_t >	action_data,
		uint32_t	sequence_id = 0 )

Send a dApp control action to the RAN.

Parameters

sequence_id correlation id of the xApp procedure this control re-issues; 0 when the dApp decided on its own.

Returns: the assigned message id (positive, 1..4294967295) on success, so the caller can correlate a later ack/response by id; a negative ErrorCode on failure. Returned as int64_t because a message id now spans the full uint32 range and would alias onto the negative error codes if narrowed to int.

Definition at line 221 of file e3_dapp_session.cpp.

◆ send_message_ack()

int libe3::py::DAppSession::send_message_ack	(	uint32_t	request_id,
		int	response_code )

Acknowledge a request.

Parameters

response_code 0=positive,1=negative.

Returns: ErrorCode as int.

Definition at line 248 of file e3_dapp_session.cpp.

◆ send_report()

int64_t libe3::py::DAppSession::send_report	(	uint32_t	ran_function_id,
		std::vector< uint8_t >	report_data,
		uint32_t	sequence_id )

Send a dApp report to the RAN.

Parameters

sequence_id correlation id this dApp assigns to the detection; mandatory on the wire, 1..4294967295 (0 is refused with INVALID_PARAM).

Returns: the assigned message id (positive, 1..4294967295) on success, so the caller can correlate a later ack/response by id; a negative ErrorCode on failure.

Definition at line 236 of file e3_dapp_session.cpp.

◆ setup_ran_function_control()

std::vector< uint32_t > libe3::py::DAppSession::setup_ran_function_control ( std::size_t i ) const

Control ids of advertised entry i.

Definition at line 187 of file e3_dapp_session.cpp.

◆ setup_ran_function_count()

std::size_t libe3::py::DAppSession::setup_ran_function_count ( ) const

Number of RAN functions advertised in the SetupResponse.

Definition at line 170 of file e3_dapp_session.cpp.

◆ setup_ran_function_data()

std::vector< uint8_t > libe3::py::DAppSession::setup_ran_function_data ( std::size_t i ) const

Opaque ranFunctionData bytes of advertised entry i.

Definition at line 193 of file e3_dapp_session.cpp.

◆ setup_ran_function_id()

uint32_t libe3::py::DAppSession::setup_ran_function_id ( std::size_t i ) const

RAN function id of advertised entry i (0 if out of range).

Definition at line 175 of file e3_dapp_session.cpp.

◆ setup_ran_function_telemetry()

std::vector< uint32_t > libe3::py::DAppSession::setup_ran_function_telemetry ( std::size_t i ) const

Telemetry ids of advertised entry i.

Definition at line 181 of file e3_dapp_session.cpp.

◆ setup_response_code()

int libe3::py::DAppSession::setup_response_code ( ) const

SetupResponse code: 0=positive, 1=negative, -1=not received.

Definition at line 164 of file e3_dapp_session.cpp.

◆ start()

int libe3::py::DAppSession::start ( )

Start the agent, re-arming the inbound ring so a stop()->start() cycle works again.

Returns: ErrorCode as int.

Definition at line 132 of file e3_dapp_session.cpp.

◆ stop()

void libe3::py::DAppSession::stop ( )

Stop the agent and shut down the ring so a blocked poll_events returns an empty batch (i.e. empty-after-stop means "done"). Restartable via start.

Definition at line 149 of file e3_dapp_session.cpp.

◆ subscribe()

int64_t libe3::py::DAppSession::subscribe	(	uint32_t	ran_function_id,
		std::vector< uint32_t >	telemetry_ids,
		std::vector< uint32_t >	control_ids,
		int	sub_time_ms,
		int	periodicity )

Subscribe to a RAN function (after a positive setup).

Parameters

sub_time_ms	subscription time, or -1 for unset.
periodicity	delivery periodicity (µs), or -1 for unset.

Returns: the assigned request id (positive, 1..4294967295) on success, so the caller can correlate the SubscriptionResponse by its request_id; a negative ErrorCode on failure.

Definition at line 199 of file e3_dapp_session.cpp.

◆ unsubscribe()

int libe3::py::DAppSession::unsubscribe ( uint32_t ran_function_id )

Delete a previously created subscription.

Returns: ErrorCode as int.

Definition at line 217 of file e3_dapp_session.cpp.

◆ wait_for_setup()

int libe3::py::DAppSession::wait_for_setup ( int timeout_ms )

Block until the setup handshake completes.

Returns: ErrorCode as int.

Definition at line 140 of file e3_dapp_session.cpp.

The documentation for this class was generated from the following files:

/home/runner/work/libe3/libe3/swig/e3_dapp_session.hpp
/home/runner/work/libe3/libe3/swig/e3_dapp_session.cpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ DAppSession() [1/2]

◆ ~DAppSession()

◆ DAppSession() [2/2]

Member Function Documentation

◆ dapp_id()

◆ dropped_events()

◆ operator=()

◆ poll_events()

◆ ran_identifier()

◆ release()

◆ send_control()

◆ send_message_ack()

◆ send_report()

◆ setup_ran_function_control()

◆ setup_ran_function_count()

◆ setup_ran_function_data()

◆ setup_ran_function_id()

◆ setup_ran_function_telemetry()

◆ setup_response_code()

◆ start()

◆ stop()

◆ subscribe()

◆ unsubscribe()

◆ wait_for_setup()