Skip to content

Report the interval the Service Model keeps in the subscription response - #148

Draft
Thecave3 wants to merge 3 commits into
fix/97-repeat-subscriptionfrom
fix/119-granted-periodicity
Draft

Thecave3 wants to merge 3 commits into
fix/97-repeat-subscriptionfrom
fix/119-granted-periodicity

Conversation

@Thecave3

@Thecave3 Thecave3 commented Nov 6, 2026

Copy link
Copy Markdown
Collaborator

Summary

The periodicity of a subscription response was the periodicity of the request, whatever the Service Model did with it (#119). A dApp could be told 500 and get indications every 1000.

What a RAN does now

  • The response has a periodicity only when the Service Model reports one through the new ServiceModel::granted_periodicity(). The value is the least time the SM keeps between two indications, in microseconds. It is a floor: indications can be further apart.
  • An SM that does not override the function, one that returns 0, and one that returns more than the grammar carries (60000000) give a response without it, which reads as "not reported".
  • A repeat of a subscription asks the SM with the periodicity the subscription holds, not the one of the repeat.
  • The core no longer echoes the request.

The definition, on the three stacks. Aerial's agent returns the value it was asked for and also skips an indication that comes sooner, so there it is an enforced floor, which is the same definition. OCUDU's response carries no periodicity, which is "not reported". OCUDU's unit (milliseconds) is #98 and is unchanged here. ranFunctionIdentifier stays in the response as an optional field for information; removing it would be a wire change for nothing.

The range question in the issue was settled by #98: the grammar has been INTEGER (0..60000000) in microseconds since 0.2.8.

No grammar changes and the C API is unchanged. The bytes of a response lose a field that is optional.

What a user sees

Before After
SM without the hook, dApp asks for 5000 response periodicity 5000 response has none (E3Event.periodicity is -1 in libe3py)
SM that keeps a floor of 1000, dApp asks for 500 500 1000
the same dApp subscribes again asking for 9000 9000 1000
SM returns 0 or 70000000 echo of the request none; the response is still delivered
OAI's SMs (C API) echo of the request none: the C API has no hook

What is not done

  • A hook in the C API. Until then OAI's Service Models cannot report a periodicity and OAI dApps see "not reported". Needs a change in OAI's E3 agent too.
  • Enforcing the rate in the core. A limiter would sit on the indication path that the latency work measures.
  • An SM cannot tell "no periodicity" from "periodicity 0": the specification says absent means the SM sets the rate and 0 means one indication per event, but the core stores both as 0. Not changed here.

Commits

  1. sm: let a Service Model say the interval it keeps between indications: the hook, with a default that reports nothing; README; version bump.
  2. core: report the interval the SM keeps, not the one the dApp asked for: the response, the tests, the specification, guide and interop page changes, and a ledger row.

Notes for review

  • VERSION is 0.4.3: the SM interface grows by a virtual function, so a C++ SM built against an older header has to be rebuilt.
  • test_granted_periodicity_e2e runs on ASN.1 and on JSON, and fails on the code before commit 2. The test of [Interop]: Subscribing twice to the same RAN function is handled differently #97 no longer reads the periodicity from the response; it asks the RAN what the subscription holds.
  • The ASN.1 block in 04-encoding.md and the Protobuf grammar get a comment change only.

Type of change

  • Bug fix
  • New feature / enhancement
  • New Service Model
  • Refactor (no behavior change)
  • Documentation
  • Test / CI / packaging
  • Other (explain):

Linked issue

Closes #119

Twin-repo coordination

  • This PR does not change the E3 wire protocol or public ABI, OR a paired PR exists in each affected twin repo (link below).
  • This PR does not change the wire format or a behavior a peer (OAI, Aerial, OCUDU) can observe, OR I added a row to the change ledger in docs/interop.md.

The wire grammar is unchanged, but ServiceModel gains a virtual function, so OAI's E3 agent and the dApp library have to be rebuilt with it, and OAI's dApps no longer read a periodicity from libe3's response.

Paired PR(s): none yet

Checks run locally

Same as the #97 PR: each commit built and tested on its own in Release, this PR in Release and Debug, --docs-strict clean, linear branch. Not run: the MPMC benchmark, the SWIG build and the other CI workflows.

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

CI report — d742497 — ✅ all checks passed

Workflow Result Time Run
CI ✅ success 25m26s #11
Docs ✅ success 0m37s #85
CI

✅ posix/ipc

  • dApp exit: 0
  • Indications received: 7

✅ posix/tcp

  • dApp exit: 0
  • Indications received: 7

✅ zmq/ipc

  • dApp exit: 0
  • Indications received: 7

✅ zmq/tcp

  • dApp exit: 0
  • Indications received: 7

zmq/ipc

  • ✅ 1 RAN - 1 dApp: indications=5
    • dapp peer=t11 ran=ran-solo sub=1 indications=5 seq=[0..4] dropped=0 (0%) age_ms(avg=1 max=1 @seq=0) hist[<=1:5 2-5:0 6-10:0 >10:0]
  • ✅ 1 RAN - 2 dApps: dApp#1 ind=5 sub=1, dApp#2 ind=6 sub=2, RAN saw 2 dApps
    • dapp1 peer=t12 ran=ran-shared sub=1 indications=5 seq=[0..4] dropped=0 (0%) age_ms(avg=0 max=0 @seq=0) hist[<=1:5 2-5:0 6-10:0 >10:0]
    • dapp2 peer=t12 ran=ran-shared sub=2 indications=6 seq=[0..5] dropped=0 (0%) age_ms(avg=0 max=0 @seq=0) hist[<=1:6 2-5:0 6-10:0 >10:0]
  • ✅ 2 RANs - 1 dApp: from ran-a ind=5, from ran-b ind=5
    • dapp peer=t2a ran=ran-a sub=1 indications=5 seq=[0..4] dropped=0 (0%) age_ms(avg=1 max=1 @seq=0) hist[<=1:5 2-5:0 6-10:0 >10:0]
    • dapp peer=t2b ran=ran-b sub=1 indications=5 seq=[0..4] dropped=0 (0%) age_ms(avg=0.2 max=1 @seq=0) hist[<=1:5 2-5:0 6-10:0 >10:0]

zmq/tcp

  • ✅ 1 RAN - 1 dApp: indications=5
    • dapp peer=default ran=ran-solo sub=1 indications=5 seq=[0..4] dropped=0 (0%) age_ms(avg=0 max=0 @seq=0) hist[<=1:5 2-5:0 6-10:0 >10:0]
  • ✅ 1 RAN - 2 dApps: dApp#1 ind=5 sub=1, dApp#2 ind=6 sub=2, RAN saw 2 dApps
    • dapp1 peer=default ran=ran-shared sub=1 indications=5 seq=[0..4] dropped=0 (0%) age_ms(avg=0 max=0 @seq=0) hist[<=1:5 2-5:0 6-10:0 >10:0]
    • dapp2 peer=default ran=ran-shared sub=2 indications=6 seq=[0..5] dropped=0 (0%) age_ms(avg=0 max=0 @seq=0) hist[<=1:6 2-5:0 6-10:0 >10:0]
  • ✅ 2 RANs - 1 dApp: from ran-a ind=5, from ran-b ind=5
    • dapp peer=default ran=ran-a sub=1 indications=5 seq=[0..4] dropped=0 (0%) age_ms(avg=0 max=0 @seq=0) hist[<=1:5 2-5:0 6-10:0 >10:0]
    • dapp peer=off100 ran=ran-b sub=1 indications=5 seq=[0..4] dropped=0 (0%) age_ms(avg=0 max=0 @seq=0) hist[<=1:5 2-5:0 6-10:0 >10:0]

Full-loop latency

Full-loop latency benchmark (N=1050 after 50 warmup)

All values in microseconds (μs). Link: zmq, transport: ipc, encoding: ASN.1 APER.

# Description Tags mean p50 p99 max
1 Collect indication data RECORD_BEGIN to ENCODE_E3SM_BEGIN 0.12 0.12 0.26 0.43
2 Create & encode indication ENCODE_E3SM_BEGIN to ENCODE_E3SM_DONE 0.92 0.89 1.61 2.69
3 Encode E3AP (indication) EMIT_ENTER to ENQUEUE, then DEQUEUE to ENCODE_E3AP_DONE 2.67 2.47 5.15 18.25
4 Queuing (indication) ENQUEUE to DEQUEUE 5.10 3.40 25.52 37.20
5 Delivery (indication) ENCODE_E3AP_DONE to SEND_DONE 2.26 0.31 19.89 33.94
6 E3 wire (RAN -> dApp) SEND_DONE to RECV 37.07 37.05 60.30 810.04
7 Decode E3AP (indication) RECV to DECODE_E3AP_DONE 1.72 1.45 7.05 27.78
8 libe3 dispatch (indication) DECODE_E3AP_DONE to DELIVER_BEGIN 0.14 0.13 0.27 0.41
9 Decode indication DELIVER_BEGIN to DECODE_E3SM_DONE 0.50 0.53 0.84 1.43
10 Process data DECODE_E3SM_DONE to ENCODE_E3SM_BEGIN 0.04 0.04 0.05 0.12
11 Create & encode control ENCODE_E3SM_BEGIN to ENCODE_E3SM_DONE 0.32 0.31 0.56 0.99
12 Encode E3AP (control) EMIT_ENTER to ENQUEUE, then DEQUEUE to ENCODE_E3AP_DONE 3.51 3.32 6.39 22.78
13 Queuing (control) ENQUEUE to DEQUEUE 7.68 11.37 23.93 30.71
14 Delivery (control) ENCODE_E3AP_DONE to SEND_DONE 6.04 5.54 13.22 25.11
15 E3 wire (dApp -> RAN) SEND_DONE to RECV 37.53 37.47 64.84 327.56
16 Decode E3AP (control) RECV to DECODE_E3AP_DONE 2.60 2.50 4.64 17.38
17 libe3 dispatch (control) DECODE_E3AP_DONE to DECODE_E3SM_BEGIN 0.62 0.61 1.27 1.70
18 Decode & handle control DECODE_E3SM_BEGIN to DECODE_E3SM_DONE 0.32 0.33 0.50 0.61
Total Total round-trip 109.68 112.80 159.64 919.33

ubuntu-latest, Release build, ZMQ + IPC, ASN.1 APER.

These numbers are measured inside a GitHub Actions container and should be treated as an upper bound on E3AP's and the library's own latency, not a representative deployment measurement.

Docs

Doxygen warnings

0 warning(s) in the files this pull request changes, which fail the check; 65 more elsewhere, which do not. The full list is in the job log and the doxygen-warnings artifact of the Docs workflow.

Gaps in files this pull request does not change, by file:

Warnings File
17 include/libe3/logger.hpp
17 swig/libe3_swig.hpp
9 include/libe3/dapp_subscription_state.hpp
7 include/libe3/lockfree_queue.hpp
6 include/libe3/mpmc_queue.hpp
1 include/libe3/error_codes.h
1 include/libe3/libe3.hpp
1 src/connector/zmq_connector.hpp

Ready to merge (fast-forward only)

A maintainer can land the reviewed commits with:

git fetch origin
git checkout main && git merge --ff-only d74249716ced15d219d27826f8992ed6ba2cca9b && git push origin main

Head: d74249716ced15d219d27826f8992ed6ba2cca9b (branch fix/119-granted-periodicity). If --ff-only fails as non-fast-forward, the branch must be rebased on the latest main.

One comment per PR, rewritten in place once every workflow for d742497 finished.

@Thecave3
Thecave3 force-pushed the fix/97-repeat-subscription branch from d2c8c0e to 3ca4c67 Compare November 7, 2026 15:09
@Thecave3
Thecave3 force-pushed the fix/119-granted-periodicity branch from 4e841c9 to 4832cc2 Compare November 7, 2026 15:09
@Thecave3
Thecave3 force-pushed the fix/97-repeat-subscription branch from 3ca4c67 to 1713b1b Compare November 10, 2026 12:41
@Thecave3
Thecave3 force-pushed the fix/119-granted-periodicity branch from 4832cc2 to df6a666 Compare November 10, 2026 12:41
@Thecave3
Thecave3 force-pushed the fix/97-repeat-subscription branch from 1713b1b to b69184e Compare November 11, 2026 01:43
@Thecave3
Thecave3 force-pushed the fix/119-granted-periodicity branch from df6a666 to 1c7da28 Compare November 11, 2026 01:44
The granted periodicity of a subscription response was the periodicity of the
request, whatever the Service Model did with it (#119). Only the SM knows
whether it keeps its indications that far apart.

ServiceModel gets granted_periodicity(), with a default that reports nothing, so
an SM written before it builds and behaves as it did. Nothing calls it yet: the
core still answers as before until the next commit.

The README lists the method. VERSION 0.4.3: the SM interface grows by a virtual
function, so a C++ SM built against an older header has to be rebuilt.

Assisted-by: Claude:claude-sonnet-5-5
Signed-off-by: Thecave3 <thecave003@gmail.com>
The periodicity of a subscription response was the periodicity of the request
(#119). Nothing checked that the Service Model delivered at that rate, so a dApp
could be told 500 and get indications every 1000. Aerial's agent returns the
requested value too, but it also skips an indication that comes sooner, so there
the number is true; here it was not.

The response now has a periodicity only when the SM reports one through
granted_periodicity(), in microseconds, as the least time it keeps between two
indications. An SM that does not override it, one that says 0, and one that says
more than the grammar carries (60000000) give a response without it, which reads
as "not reported". A repeat of a subscription asks the SM with the periodicity
the subscription holds, not the one of the repeat. The telemetry and control
lists are unchanged by this commit.

No grammar changes and the C API is unchanged. The bytes of a response lose a
field that is optional, so an older decoder reads it as before. libe3py's
E3Event.periodicity is -1 where it was the requested value. OAI's SMs go through
the C API, which has no hook yet, so they report none.

Specification and guide: 02 and 03 define the interval as the least time between
two indications that the E3 Agent keeps, say that it is not a copy of the request
and that a missing one is "not reported", and that the RAN function identifier is
for information; 05 gets the row; the encoding clause, the Protobuf grammar and
the code comments say the same; the guide gets the row and its pointers; the Word
edition is rebuilt. The interop page defines the field in "Granted values" and in
the table of field contracts, with what Aerial's agent does, and gets a ledger
row.

Tests: against four SMs, one without the hook, one that keeps a floor of 1000,
one that says 0 and one that says 70000000, on ASN.1 and on JSON: the response
has no periodicity, 1000 for a request of 500 and again for a repeat that asks for
9000, none, and none, and the last response is still delivered. The #97 test no
longer reads the periodicity from the response, which its SM does not report; it
asks the RAN what the subscription holds. The new test fails on the code before
this commit.

Assisted-by: Claude:claude-sonnet-5-5
Signed-off-by: Thecave3 <thecave003@gmail.com>
…gen flags

The Docs check fails a pull request on any Doxygen warning in a file it changes,
old ones included (#132). This change touches sm_interface.hpp and
swig/e3_dapp_session.hpp, so their gaps are filled here instead of being left for
the check to report.

* @return and @PARAM for the accessors, the registry functions and the protected
  helpers of ServiceModel and SmRegistry.
* @PARAM and @return for the setup accessors, unsubscribe, poll_events and
  dropped_events of DAppSession.

The integrator guide's pointer to granted_periodicity() follows the added lines.
Comments only: no code changes.

Assisted-by: Claude:claude-sonnet-5-5
Signed-off-by: Thecave3 <thecave003@gmail.com>
@Thecave3
Thecave3 force-pushed the fix/97-repeat-subscription branch from b69184e to ff4feb9 Compare November 11, 2026 02:04
@Thecave3
Thecave3 force-pushed the fix/119-granted-periodicity branch from 1c7da28 to d742497 Compare November 11, 2026 02:04

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant