pub struct Subscription<const P: usize> {
pub id: u32,
pub session: Option<SessionId>,
pub fabric_index: Option<FabricIndex>,
pub peer_node_id: Option<NodeId>,
pub fabric_filtered: bool,
pub min_interval_s: u16,
pub max_interval_s: u16,
pub paths: Vec<AttributePath, P>,
pub last_report: Instant,
pub event_paths: Vec<EventPath, P>,
pub dirty: DirtySet<DIRTY_PATHS>,
pub next_event_number: u64,
/* private fields */
}Expand description
One active subscription (§8.5).
Fields§
§id: u32SubscriptionId — “generated by the publisher”, unique among its subscriptions.
session: Option<SessionId>The session it was created on.
§8.5.2.3: “If KeepSubscriptions is FALSE, all existing or pending subscriptions on the publisher for this subscriber SHALL be terminated” — so a subscription has to remember whose it is.
fabric_index: Option<FabricIndex>The accessing fabric, if the session has one. §2.11.2.2 permits a subscription with none: “A server MAY permit Subscribe Interactions even when there is no accessing fabric, subject to available resources (e.g over PASE).”
peer_node_id: Option<NodeId>Whose subscription it is, as CASE proved it.
A SessionId names a session, and a session does not survive a reboot; this names the
node, and does. It is what persist rebinds a restored
subscription by, and None on a PASE session, which has no operational identity.
fabric_filtered: boolFabricFiltered, which “SHALL remain in effect for all data reported during the
interaction” — a one-time parameter that outlives the request carrying it.
min_interval_s: u16The negotiated minimum interval, in seconds — the subscriber’s requested floor.
§8.5.3.2: the subscription becomes active “with a min interval equal to the requested MinIntervalFloor”, so the publisher does not choose this one.
max_interval_s: u16The negotiated maximum interval, in seconds — what went in the SubscribeResponse.
paths: Vec<AttributePath, P>The subscribed attribute paths, as requested. Wildcards are kept as wildcards and expanded at report time, so a path that starts matching a newly-added endpoint is reported without the subscription being rebuilt.
last_report: InstantWhen the last report went out.
event_paths: Vec<EventPath, P>The subscribed event paths, as requested.
Separate from the attribute paths because they behave differently: an attribute change dirties a set that a report drains, while an event is queued and delivered in order.
dirty: DirtySet<DIRTY_PATHS>What has changed since.
next_event_number: u64The event number the next report starts from.
§8.5.3.4: “Subsequent ReportData actions, as part of the subscription, SHALL include
the latest EventNo associated with each node generating new events.” This is the
bookmark that makes that possible — and the reason EventFilters is “a one time
parameter for the priming of the subscription”: after the priming report the
subscription tracks its own position.
Implementations§
Source§impl<const P: usize> Subscription<P>
impl<const P: usize> Subscription<P>
Sourcepub fn reprime(&mut self)
pub fn reprime(&mut self)
Marks every path dirty, so the next report is a full one (§8.5.3.4).
What a re-prime says is not “these things changed” but “I no longer know what you have” — after a dirty-set overflow, or after a reboot, the subscriber’s twin is unknown rather than stale in some identified way.
Sourcepub fn earliest_report(&self) -> Instant
pub fn earliest_report(&self) -> Instant
The earliest a report may go out — last_report + min_interval.
Sourcepub fn latest_report(&self) -> Instant
pub fn latest_report(&self) -> Instant
The latest a report may go out — last_report + max_interval.
Sourcepub fn has_pending(&self) -> bool
pub fn has_pending(&self) -> bool
Whether anything is waiting to be reported.
An attribute change, or an event queued against a path the subscriber marked urgent. A non-urgent event is not pending: §8.5 says its queueing “does not automatically trigger a Report transaction”, and it rides out with the next one.
Sourcepub fn due(&self, now: Instant) -> Option<ReportReason>
pub fn due(&self, now: Instant) -> Option<ReportReason>
Whether a report is due now, and why.
The two rules, in the order they bind: nothing before the minimum interval, and something by the maximum. In between, a report goes out exactly when there is something to say — “Attribute changes SHALL be delivered as soon as possible, taking into account the minimum interval”.
Sourcepub fn next_deadline(&self) -> Instant
pub fn next_deadline(&self) -> Instant
When this subscription next needs attention.
A device sleeps until the earliest deadline across its subscriptions; an intermittently connected one uses it to decide whether it can stay idle. Dirty data pulls the deadline in to the minimum interval, clean data leaves it at the maximum.
Sourcepub fn reported(&mut self, now: Instant)
pub fn reported(&mut self, now: Instant)
Records that a report went out, resetting both timers and everything pending.
The event bookmark comes from the report the server built, not from the caller.
Server::report_chunk leaves
ReadOutcome::events_through here as
it writes, so §8.5.3.4’s “the next report resumes after the last event delivered” is a
fact the server already has rather than a number the device is asked to reconstruct.
Not a parameter, because it is not a number a caller can compute: a report is built path
by path and the cursor’s position is reset between them, so the answer every caller
reaches for is 0 — and a bookmark stuck at zero re-sends the subscriber’s whole event
history on every report, for the life of the subscription.
Sourcepub fn event_urgency(
&self,
endpoint: u16,
cluster: u32,
event: u32,
) -> Option<bool>
pub fn event_urgency( &self, endpoint: u16, cluster: u32, event: u32, ) -> Option<bool>
Whether this subscription asked for path, and whether it asked urgently.
Returns None when no subscribed path covers the event. §10.6.8’s IsUrgent is a
property of the path, not of the event, so the same event may be urgent to one
subscriber and not to another.
Sourcepub fn note_event(&mut self, endpoint: u16, cluster: u32, event: u32) -> bool
pub fn note_event(&mut self, endpoint: u16, cluster: u32, event: u32) -> bool
Records that an event was queued, if this subscription wants it.
Returns whether the event triggers a report — which is only when the subscriber marked the path urgent. §8.5: “When the IsUrgent flag is FALSE or absent … event queueing does not automatically trigger a Report transaction.”
Sourcepub fn covers(&self, path: &AttributePath) -> bool
pub fn covers(&self, path: &AttributePath) -> bool
Whether this subscription covers path — the test a change has to pass before it
dirties anything.
A subscribed path may be a wildcard, so this is containment rather than equality: a
subscription to “every attribute of cluster 6 on every endpoint” is dirtied by a
change to endpoint 1’s OnOff.
Sourcepub fn note_change(&mut self, path: &AttributePath) -> bool
pub fn note_change(&mut self, path: &AttributePath) -> bool
Records a change, if this subscription covers it.
Returns whether it did, so a caller can tell whether a report is now pending.