libe3py 0.4.1__tar.gz → 0.4.3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {libe3py-0.4.1 → libe3py-0.4.3}/PKG-INFO +1 -1
- libe3py-0.4.3/VERSION +1 -0
- {libe3py-0.4.1 → libe3py-0.4.3}/swig/README.md +9 -0
- {libe3py-0.4.1 → libe3py-0.4.3}/swig/e3_dapp_session.cpp +10 -0
- {libe3py-0.4.1 → libe3py-0.4.3}/swig/e3_dapp_session.hpp +22 -12
- libe3py-0.4.1/VERSION +0 -1
- {libe3py-0.4.1 → libe3py-0.4.3}/LICENSE +0 -0
- {libe3py-0.4.1 → libe3py-0.4.3}/NOTICE +0 -0
- {libe3py-0.4.1 → libe3py-0.4.3}/cmake/libe3SwigModule.cmake +0 -0
- {libe3py-0.4.1 → libe3py-0.4.3}/pyproject.toml +0 -0
- {libe3py-0.4.1 → libe3py-0.4.3}/python/CMakeLists.txt +0 -0
- {libe3py-0.4.1 → libe3py-0.4.3}/python/README.md +0 -0
- {libe3py-0.4.1 → libe3py-0.4.3}/swig/libe3.i +0 -0
- {libe3py-0.4.1 → libe3py-0.4.3}/swig/libe3_swig.hpp +0 -0
libe3py-0.4.3/VERSION
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
0.4.3
|
|
@@ -51,6 +51,15 @@ inbound thread under the GIL (serialises dispatch, deadlock-prone if Python
|
|
|
51
51
|
re-enters libe3); a *per-message* poll pays one GIL round-trip per message and
|
|
52
52
|
caps throughput with no latency benefit over batching.
|
|
53
53
|
|
|
54
|
+
## Refusals
|
|
55
|
+
|
|
56
|
+
A negative subscription response, setup response or message ack arrives as an `E3Event`
|
|
57
|
+
with `response_code == 1`, and `cause` and `detail` say why: `cause` is a `libe3py.Cause_*`
|
|
58
|
+
value (for example `Cause_UNSUPPORTED_IDENTIFIER` when a control id is not one the RAN
|
|
59
|
+
function advertises) or -1 when the RAN gave none, as Aerial does, and `detail` is its text
|
|
60
|
+
or empty. libe3py does not raise: the dApp reads the event and decides, for example to drop
|
|
61
|
+
the control and subscribe again.
|
|
62
|
+
|
|
54
63
|
## Lifecycle
|
|
55
64
|
|
|
56
65
|
```
|
|
@@ -27,6 +27,13 @@ inline std::optional<uint32_t> opt_u32(int v) {
|
|
|
27
27
|
if (v < 0) return std::nullopt;
|
|
28
28
|
return static_cast<uint32_t>(v);
|
|
29
29
|
}
|
|
30
|
+
|
|
31
|
+
// Copy why a response was negative onto the event; a positive one has neither.
|
|
32
|
+
inline void set_refusal(E3Event& ev, const std::optional<libe3::Cause>& cause,
|
|
33
|
+
const std::optional<std::string>& detail) {
|
|
34
|
+
if (cause) ev.cause = static_cast<int>(*cause);
|
|
35
|
+
if (detail) ev.detail = *detail;
|
|
36
|
+
}
|
|
30
37
|
} // namespace
|
|
31
38
|
|
|
32
39
|
/// What a DAppSession holds: the agent, the event queue and the setup snapshot.
|
|
@@ -108,6 +115,7 @@ DAppSession::DAppSession(libe3::E3Config config, std::size_t queue_capacity) {
|
|
|
108
115
|
ev.response_code = static_cast<int>(r.response_code);
|
|
109
116
|
ev.ran_function_id = r.ran_function_identifier.value_or(0);
|
|
110
117
|
ev.periodicity = r.periodicity ? static_cast<long>(*r.periodicity) : -1;
|
|
118
|
+
set_refusal(ev, r.cause, r.detail);
|
|
111
119
|
if (r.telemetry_identifier_list) {
|
|
112
120
|
ev.has_telemetry_granted = true;
|
|
113
121
|
ev.telemetry_granted = *r.telemetry_identifier_list;
|
|
@@ -130,6 +138,7 @@ DAppSession::DAppSession(libe3::E3Config config, std::size_t queue_capacity) {
|
|
|
130
138
|
ev.dapp_id = r.dapp_identifier.value_or(0);
|
|
131
139
|
ev.request_id = r.request_id;
|
|
132
140
|
ev.response_code = static_cast<int>(r.response_code);
|
|
141
|
+
set_refusal(ev, r.cause, r.detail);
|
|
133
142
|
impl->enqueue(std::move(ev));
|
|
134
143
|
});
|
|
135
144
|
|
|
@@ -145,6 +154,7 @@ DAppSession::DAppSession(libe3::E3Config config, std::size_t queue_capacity) {
|
|
|
145
154
|
ev.kind = E3_EVENT_MESSAGE_ACK;
|
|
146
155
|
ev.request_id = ack.request_id;
|
|
147
156
|
ev.response_code = static_cast<int>(ack.response_code);
|
|
157
|
+
set_refusal(ev, ack.cause, ack.detail);
|
|
148
158
|
impl->enqueue(std::move(ev));
|
|
149
159
|
});
|
|
150
160
|
}
|
|
@@ -76,6 +76,11 @@ enum E3EventKind {
|
|
|
76
76
|
*
|
|
77
77
|
* A subscription response also carries the grant: `ran_function_id` (0 = not
|
|
78
78
|
* reported), `periodicity`, and the id lists, valid only when their has_* flag is set.
|
|
79
|
+
*
|
|
80
|
+
* A negative subscription response, setup response or message ack also carries why:
|
|
81
|
+
* `cause` (a @ref libe3::Cause value, -1 when the RAN gave none, as Aerial does) and
|
|
82
|
+
* `detail` (the RAN's text, empty when there is none). A dApp reads them to decide what
|
|
83
|
+
* to do, for example to drop a control the RAN function does not offer and subscribe again.
|
|
79
84
|
*/
|
|
80
85
|
struct E3Event {
|
|
81
86
|
int kind{E3_EVENT_NONE}; ///< one of @ref E3EventKind
|
|
@@ -87,7 +92,9 @@ struct E3Event {
|
|
|
87
92
|
int response_code{-1}; ///< 0=positive, 1=negative, -1=n/a
|
|
88
93
|
int disconnect_reason{-1}; ///< disconnect: 0=released by RAN, 1=connection lost, -1=n/a
|
|
89
94
|
std::vector<uint8_t> payload; ///< opaque E3SM bytes (indication / xApp control)
|
|
90
|
-
long periodicity{-1}; ///<
|
|
95
|
+
long periodicity{-1}; ///< least microseconds the RAN keeps between two indications (subscription response), -1 = not reported
|
|
96
|
+
int cause{-1}; ///< why a negative response was refused, a libe3::Cause value; -1 = none given
|
|
97
|
+
std::string detail; ///< the RAN's text for the refusal; empty = none given
|
|
91
98
|
bool has_telemetry_granted{false}; ///< telemetry_granted was reported
|
|
92
99
|
bool has_control_granted{false}; ///< control_granted was reported
|
|
93
100
|
std::vector<uint32_t> telemetry_granted; ///< granted telemetry ids
|
|
@@ -126,7 +133,7 @@ public:
|
|
|
126
133
|
/** @brief Start the agent, re-arming the inbound ring so a stop()->start()
|
|
127
134
|
* cycle works again. @return ErrorCode as int. */
|
|
128
135
|
int start();
|
|
129
|
-
/** @brief Block until the setup handshake completes. @return ErrorCode as int. */
|
|
136
|
+
/** @brief Block until the setup handshake completes. @param timeout_ms longest wait, in milliseconds. @return ErrorCode as int. */
|
|
130
137
|
int wait_for_setup(int timeout_ms);
|
|
131
138
|
/** @brief Send a ReleaseMessage (session keeps running until @ref stop). @return ErrorCode as int. */
|
|
132
139
|
int release();
|
|
@@ -135,22 +142,22 @@ public:
|
|
|
135
142
|
* via @ref start. */
|
|
136
143
|
void stop();
|
|
137
144
|
|
|
138
|
-
/** @brief dApp id assigned at setup, or -1 if not yet assigned. */
|
|
145
|
+
/** @brief dApp id assigned at setup. @return the id, or -1 if not yet assigned. */
|
|
139
146
|
long dapp_id() const;
|
|
140
|
-
/** @brief RAN identifier from the SetupResponse, or "" if none. */
|
|
147
|
+
/** @brief RAN identifier from the SetupResponse. @return the identifier, or "" if none. */
|
|
141
148
|
std::string ran_identifier() const;
|
|
142
149
|
|
|
143
|
-
/** @brief SetupResponse code
|
|
150
|
+
/** @brief SetupResponse code. @return 0=positive, 1=negative, -1=not received. */
|
|
144
151
|
int setup_response_code() const;
|
|
145
|
-
/** @brief Number of RAN functions advertised in the SetupResponse. */
|
|
152
|
+
/** @brief Number of RAN functions advertised in the SetupResponse. @return the count. */
|
|
146
153
|
std::size_t setup_ran_function_count() const;
|
|
147
|
-
/** @brief RAN function id of advertised entry @
|
|
154
|
+
/** @brief RAN function id of an advertised entry. @param i index of the entry. @return the id, 0 if out of range. */
|
|
148
155
|
uint32_t setup_ran_function_id(std::size_t i) const;
|
|
149
|
-
/** @brief Telemetry ids of advertised entry @
|
|
156
|
+
/** @brief Telemetry ids of an advertised entry. @param i index of the entry. @return the ids. */
|
|
150
157
|
std::vector<uint32_t> setup_ran_function_telemetry(std::size_t i) const;
|
|
151
|
-
/** @brief Control ids of advertised entry @
|
|
158
|
+
/** @brief Control ids of an advertised entry. @param i index of the entry. @return the ids. */
|
|
152
159
|
std::vector<uint32_t> setup_ran_function_control(std::size_t i) const;
|
|
153
|
-
/** @brief Opaque ranFunctionData bytes of advertised entry @
|
|
160
|
+
/** @brief Opaque ranFunctionData bytes of an advertised entry. @param i index of the entry. @return the bytes. */
|
|
154
161
|
std::vector<uint8_t> setup_ran_function_data(std::size_t i) const;
|
|
155
162
|
|
|
156
163
|
/**
|
|
@@ -172,7 +179,7 @@ public:
|
|
|
172
179
|
std::vector<uint32_t> control_ids,
|
|
173
180
|
int sub_time_ms,
|
|
174
181
|
int periodicity);
|
|
175
|
-
/** @brief Delete a previously created subscription. @return ErrorCode as int. */
|
|
182
|
+
/** @brief Delete a previously created subscription. @param ran_function_id RAN function it was for. @return ErrorCode as int. */
|
|
176
183
|
int unsubscribe(uint32_t ran_function_id);
|
|
177
184
|
|
|
178
185
|
/**
|
|
@@ -216,10 +223,13 @@ public:
|
|
|
216
223
|
* @p timeout_ms <= 0 polls non-blocking (does not busy-wait). Returns an
|
|
217
224
|
* empty vector on a quiet tick or after @ref stop. The SWIG wrapper releases
|
|
218
225
|
* the GIL for the whole call so libe3's threads run freely while Python waits.
|
|
226
|
+
* @param max_batch most events to return
|
|
227
|
+
* @param timeout_ms longest wait for the first event, in milliseconds
|
|
228
|
+
* @return the events, empty on a quiet tick or after stop
|
|
219
229
|
*/
|
|
220
230
|
std::vector<E3Event> poll_events(std::size_t max_batch, int timeout_ms);
|
|
221
231
|
|
|
222
|
-
/** @brief Total inbound events dropped due to ring overflow (backpressure). */
|
|
232
|
+
/** @brief Total inbound events dropped due to ring overflow (backpressure). @return the count. */
|
|
223
233
|
unsigned long long dropped_events() const;
|
|
224
234
|
|
|
225
235
|
private:
|
libe3py-0.4.1/VERSION
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
0.4.1
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|