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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: libe3py
3
- Version: 0.4.1
3
+ Version: 0.4.3
4
4
  Summary: Python binding of libe3, the O-RAN E3 interface library
5
5
  Author: Northeastern University
6
6
  License-Expression: Apache-2.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}; ///< granted interval in microseconds (subscription response), -1 = not reported
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: 0=positive, 1=negative, -1=not received. */
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 @p i (0 if out of range). */
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 @p i. */
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 @p i. */
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 @p i. */
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