You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 7d83eb0
Browse filesBrowse the repository at this point in the historyBrowse files
core: register a dApp with the RAN again when it lost the RAN
A libe3 dApp that was released by the RAN, or lost its connection to it,
reported the disconnect and then stayed down until the program called stop() and
start(). Aerial's manager runs setup again every second until it works (#121). A
RAN that releases a quiet dApp (#93) would otherwise leave every such dApp down.
A dApp started with start() now has a thread that, after
E3Config::reconnect_interval_ms (default 1000, 0 is off), stops and starts the
interface again, and again every interval until the RAN answers. The cases are:
* the RAN released the dApp, or the connection was lost: the disconnect handler
runs first, as before;
* setup did not finish or the RAN refused it, including a dApp that was started
before any RAN was up;
* a restart that fails because the RAN cannot be reached asks again;
* a dApp whose inbound or outbound connection cannot be made because the RAN
left first: those threads ended with a log line and the dApp never noticed
that the RAN was gone, so nothing would have brought it back. It reports
CONNECTION_LOST now. The same gap made test_dapp_ran_loss fail now and then on
the POSIX link, whenever the RAN stopped before the dApp had connected.
The new session has a new dApp id and none of the old subscriptions. The
application subscribes again; it learns the dApp is back from the setup response
handler, which runs on every setup. A dApp that called release(), and one that
called stop(), are not restarted, and stop() does not wait for a RAN.
start() and stop() keep their meaning: they are now the locked halves
start_locked() and stop_locked() behind one lock, which the reconnect thread
takes to restart, so a restart cannot overlap a call of the application. stop()
joins the reconnect thread before it takes that lock.
test_dapp_ran_loss and test_dapp_idle_e2e set the interval to 0: the first
restarts the dApp by hand, the second counts dApps on the RAN.
Specification and guide: 03 and 05 say a dApp may run Setup again after a
release or a lost link, with a new identifier and no subscriptions; the
integrator guide gets the row and its pointers; the Word edition is rebuilt.
README and swig/README.md name reconnect_interval_ms and set_disconnect_handler,
and the handler's comment and the example say the library registers again. The
interop page replaces "the dApp does not reconnect", says what a dApp sees
against OCUDU's 30 s idle close, and gets a ledger row.
Tests: a dApp registers with a new RAN on ZeroMQ and POSIX without stop() and
start(), hears of it, and can subscribe; one released for being idle is told
RELEASED_BY_RAN and comes back; one started before any RAN registers when one
comes up; one that released itself stays released; stop() ends the retrying
quickly; 0 keeps the dApp down.
Assisted-by: Claude:claude-sonnet-5-5
Signed-off-by: Thecave3 <thecave003@gmail.com>
Copy file name to clipboardExpand all lines: README.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -382,6 +382,7 @@ The single entry-point class for both roles. Configure `E3Config.role = E3Role::
382
382
|`set_setup_response_handler(handler)`| (dApp) Callback for incoming `SetupResponse`|
383
383
|`set_xapp_control_handler(handler)`| (dApp) Callback for incoming `XAppControlAction`|
384
384
|`set_message_ack_handler(handler)`| (dApp) Callback for incoming `MessageAck`|
385
+
|`set_disconnect_handler(handler)`| (dApp) Callback when the RAN released the dApp or the connection to it was lost. The dApp then registers again by itself unless `reconnect_interval_ms` is 0 |
385
386
|`wait_for_setup(timeout)`| (dApp) Block until setup handshake completes |
386
387
|`subscribe(ran_function_id, telemetry, control, ...)`| (dApp) Subscribe to a RAN function |
387
388
|`unsubscribe(ran_function_id)`| (dApp) Tear down a subscription |
@@ -417,6 +418,7 @@ for local development (IPC) or production deployments.
|`dapp_idle_timeout_s`| uint32_t | RAN: seconds without a message from a dApp before it is released and removed (default 1800, 0 never). Only what the dApp sends counts. In the C API, `e3_config_t` has `dapp_idle_timeout_s` and the flag `set_dapp_idle_timeout`, since 0 is a legitimate value |
421
+
|`reconnect_interval_ms`| uint32_t | dApp: milliseconds between attempts to register again after a release, a lost link or a failed setup (default 1000, 0 never). The new session has a new dApp id and no subscriptions |
Copy file name to clipboardExpand all lines: docs/e3ap/03-procedure-flow.md
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -327,7 +327,8 @@ the link.
327
327
328
328
### Abnormal conditions
329
329
330
-
* The link is lost with no RELEASE message. The dApp reports the reason "connection lost". The dApp does not reconnect by itself. The application stops the session and starts it again.
330
+
* The link is lost with no RELEASE message. The dApp reports the reason "connection lost".
331
+
* After a RELEASE message from the E3 Agent or a lost link, a dApp may run the Setup procedure again by itself. It gets a new dApp identifier and none of its earlier subscriptions. The application subscribes again. A dApp that sent its own RELEASE message does not.
331
332
* An E3 Agent that does not detect the end of a dApp keeps its dApp identifier, its subscriptions and its running service models. An E3 Agent detects it from a closed connection, or from a dApp that has sent nothing for a long time. Only what the dApp sends shows that the dApp is there: a message the E3 Agent sends to a dApp is broadcast and proves nothing.
332
333
* A RELEASE message from a dApp that names another dApp identifier is not authenticated by the protocol. An E3 Agent that can tell its connections apart should bind each dApp identifier to the connection that first sent a message naming it, and ignore a message that names the identifier on another connection. An E3 Agent that does not bind removes the named dApp.
Copy file name to clipboardExpand all lines: docs/e3ap/05-semantics-and-constraints.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -130,8 +130,8 @@ side.
130
130
131
131
### Lost links
132
132
133
-
A dApp that loses its link reports the reason "connection lost". It does not
134
-
reconnect by itself. An E3 Agent that loses a dApp, or that has heard nothing from it for a long
133
+
A dApp that loses its link reports the reason "connection lost". It may run the Setup
134
+
procedure again by itself, and then has a new dApp identifier and no subscriptions. An E3 Agent that loses a dApp, or that has heard nothing from it for a long
135
135
time, should send a RELEASE message where the link is still there, and should remove the
136
136
registration and the subscriptions of that dApp. Some implementations do not detect this, so the
| dApp waits 200 ms after connecting the PUB socket (slow joiner) |`zmq_connector.cpp:505`|
@@ -66,32 +66,32 @@ in the connectors.
66
66
67
67
| Claim | Code pointer |
68
68
|---|---|
69
-
| Setup on the E3 Agent: decode, register, build the list, answer |`src/core/e3_interface.cpp:528-576`, `931-1043`|
70
-
| Negative reply for garbage or a wrong PDU type, with the cause protocolError |`e3_interface.cpp:1045-1079`|
71
-
| RAN function list limits: data 1 to 32768 octets, 256 identifiers, 64 functions |`e3_interface.cpp:960-1001`, `src/core/sm_registry.cpp:35-57`|
72
-
| Encode failure of the SETUP RESPONSE ends the process |`e3_interface.cpp:1026-1032`|
73
-
| Setup on the dApp: 5 attempts, 4 receives of 500 ms each |`e3_interface.cpp:1374-1452`|
74
-
| A negative response still gives "success" to the dApp |`e3_interface.cpp:1446`, `1610-1613`|
75
-
| Subscription: the registration, the RAN function, the lists and every identifier are checked, and a refusal carries a cause |`e3_interface.cpp:892-925`, `1081-1154`|
69
+
| Setup on the E3 Agent: decode, register, build the list, answer |`src/core/e3_interface.cpp:561-609`, `964-1076`|
70
+
| Negative reply for garbage or a wrong PDU type, with the cause protocolError |`e3_interface.cpp:1078-1112`|
71
+
| RAN function list limits: data 1 to 32768 octets, 256 identifiers, 64 functions |`e3_interface.cpp:993-1034`, `src/core/sm_registry.cpp:35-57`|
72
+
| Encode failure of the SETUP RESPONSE ends the process |`e3_interface.cpp:1059-1065`|
73
+
| Setup on the dApp: 5 attempts, 4 receives of 500 ms each |`e3_interface.cpp:1458-1541`|
74
+
| A negative response still gives "success" to the dApp |`e3_interface.cpp:1530`, `1703-1706`|
75
+
| Subscription: the registration, the RAN function, the lists and every identifier are checked, and a refusal carries a cause |`e3_interface.cpp:925-958`, `1114-1187`|
76
76
| Repeat returns the existing identifier. Renewal after expiry keeps the identifier |`subscription_manager.cpp:187-205`|
77
-
| The response echoes the request lists and interval |`e3_interface.cpp:1138-1149`|
78
-
| Subscription expiry sweep every 250 ms |`e3_interface.cpp:40`, `789-813`|
| The dApp keeps its own deadline from the response |`e3_interface.cpp:1651-1661`|
81
-
| Service model starts with the first subscriber and stops with the last |`subscription_manager.cpp:238-241`, `376-378`, `535-554`; `e3_interface.cpp:1914-1928`|
82
-
| dApp control: the registration, the RAN function, the control identifier and a running service model are checked. Otherwise a negative MESSAGE ACK with a cause |`e3_interface.cpp:1199-1262`|
83
-
| The core sends a MESSAGE ACK only to refuse a control. The service model answers for the controls it takes |`e3_interface.cpp:1209-1222`, `examples/sm_simple/simple_service_model.hpp:167`|
84
-
| The dApp handles every MESSAGE ACK, with no dApp filter |`e3_interface.cpp:1719-1733`|
85
-
| dApp report goes through a queue of 1024 and a worker |`e3_interface.cpp:654-684`, `767-788`, `1264-1272`|
86
-
| A report with `sequence_id` 0 is refused with `INVALID_PARAM`|`e3_interface.cpp:1864`|
77
+
| The response echoes the request lists and interval |`e3_interface.cpp:1171-1182`|
78
+
| Subscription expiry sweep every 250 ms |`e3_interface.cpp:40`, `822-846`|
| The dApp keeps its own deadline from the response |`e3_interface.cpp:1744-1754`|
81
+
| Service model starts with the first subscriber and stops with the last |`subscription_manager.cpp:238-241`, `376-378`, `535-554`; `e3_interface.cpp:2007-2021`|
82
+
| dApp control: the registration, the RAN function, the control identifier and a running service model are checked. Otherwise a negative MESSAGE ACK with a cause |`e3_interface.cpp:1232-1295`|
83
+
| The core sends a MESSAGE ACK only to refuse a control. The service model answers for the controls it takes |`e3_interface.cpp:1242-1255`, `examples/sm_simple/simple_service_model.hpp:167`|
84
+
| The dApp handles every MESSAGE ACK, with no dApp filter |`e3_interface.cpp:1812-1826`|
85
+
| dApp report goes through a queue of 1024 and a worker |`e3_interface.cpp:687-717`, `800-821`, `1297-1305`|
86
+
| A report with `sequence_id` 0 is refused with `INVALID_PARAM`|`e3_interface.cpp:1957`|
87
87
| xApp control from the E3 Agent has no check of `sequence_id`|`src/core/e3_agent.cpp:230-251`|
88
-
| Release from the dApp: unregister, free identifiers, stop service models |`e3_interface.cpp:1274-1297`; `subscription_manager.cpp:84-138`|
89
-
| RELEASE from the E3 Agent to a dApp that sent nothing for `dapp_idle_timeout_s` (default 1800 s, 0 is off): queued first, then the removal a release from the dApp gets. Only what the dApp sends resets the time |`e3_interface.cpp:1344-1364`; `subscription_manager.cpp:403-410`, `422-434`|
90
-
| RELEASE from the E3 Agent: the dApp clears its session |`e3_interface.cpp:1573-1605`|
88
+
| Release from the dApp: unregister, free identifiers, stop service models |`e3_interface.cpp:1307-1330`; `subscription_manager.cpp:84-138`|
89
+
| RELEASE from the E3 Agent to a dApp that sent nothing for `dapp_idle_timeout_s` (default 1800 s, 0 is off): queued first, then the removal a release from the dApp gets. Only what the dApp sends resets the time |`e3_interface.cpp:1428-1448`; `subscription_manager.cpp:403-410`, `422-434`|
90
+
| RELEASE from the E3 Agent: the dApp clears its session |`e3_interface.cpp:1665-1698`|
91
91
| Message identifiers: one counter, 1 to 4294967295 |`e3_interface.cpp:167-174`|
92
92
| A request identifier of 0 is replaced |`e3_interface.cpp:189-196`|
93
93
| The timestamp is set in the `Pdu` constructor |`types.hpp:426-437`|
94
-
| Outbound queue of 128 places, 10 ms pop |`e3_interface.cpp:265`, `705-765`; `include/libe3/lockfree_queue.hpp:55`|
94
+
| Outbound queue of 128 places, 10 ms pop |`e3_interface.cpp:265`, `738-798`; `include/libe3/lockfree_queue.hpp:55`|
95
95
96
96
### Encoding and framing (chapter 04)
97
97
@@ -102,8 +102,9 @@ in the connectors.
102
102
| The dApp sends unframed |`posix_connector.cpp:681`, `798`|
103
103
| The E3 Agent reads one raw `recv()` of up to 60000 octets |`posix_connector.cpp:355`, `537`|
104
104
| Per-peer send timeout 500 ms |`posix_connector.cpp:41`, `181`|
105
-
| A POSIX E3 Agent removes a dApp whose connection closed, if the dApp had sent a message that names it on that connection. ZeroMQ cannot tell its peers apart, so there the idle time removes the dApp |`posix_connector.cpp:515`, `556`, `565-574`, `584-592`; `e3_interface.cpp:1323-1342`|
106
-
| A POSIX E3 Agent binds a dApp identifier to the connection that first named it, and drops a later message that names it on another connection. A dApp that has not spoken yet is not bound: the first message wins |`e3_interface.cpp:619`, `1299-1321`|
105
+
| A POSIX E3 Agent removes a dApp whose connection closed, if the dApp had sent a message that names it on that connection. ZeroMQ cannot tell its peers apart, so there the idle time removes the dApp |`posix_connector.cpp:515`, `556`, `565-574`, `584-592`; `e3_interface.cpp:1356-1375`|
106
+
| A POSIX E3 Agent binds a dApp identifier to the connection that first named it, and drops a later message that names it on another connection. A dApp that has not spoken yet is not bound: the first message wins |`e3_interface.cpp:652`, `1332-1354`|
107
+
| A dApp that lost the E3 Agent registers again every `reconnect_interval_ms` (default 1000, 0 is off), with a new identifier and no subscriptions. `release()` and `stop()` end it |`e3_interface.cpp:1377-1426`|
107
108
| ASN.1 encoder buffer of 65536 octets |`src/encoder/asn1_encoder.hpp:39`|
108
109
| An empty RAN function list is omitted |`src/encoder/asn1_encoder.cpp:315`|
109
110
| A zero timestamp is left out in APER and Protobuf |`asn1_encoder.cpp:233-243`|
@@ -127,7 +128,7 @@ Update the hex in `tests/test_asn1_golden.cpp` and add a row to the change ledge
127
128
128
129
These comments disagree with the code. They are not discrepancies of the protocol.
129
130
130
-
*`include/libe3/types.hpp:523` says dApp identifiers are 1 to 100. The range is 1 to 65535.
131
+
*`include/libe3/types.hpp:538` says dApp identifiers are 1 to 100. The range is 1 to 65535.
131
132
*`include/libe3/subscription_manager.hpp:114` says at most 101 dApps. `:148` says RAN function identifiers 0 to 255. `:34` and `:151` say that periodicity 0 means "the service model default".
132
133
*`types.hpp:211` and `e3_encoder.hpp:81` use `0.0.0` as the version example. The default is `1.0.0`.
133
134
*`types.hpp:442` and `include/libe3/c_api.h:166` leave Protobuf out of the encoding comments.
0 commit comments