Skip to main content

Subscription

Struct Subscription 

Source
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: u32

SubscriptionId — “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: bool

FabricFiltered, 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: u16

The 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: u16

The 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: Instant

When 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: u64

The 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>

Source

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.

Source

pub fn earliest_report(&self) -> Instant

The earliest a report may go out — last_report + min_interval.

Source

pub fn latest_report(&self) -> Instant

The latest a report may go out — last_report + max_interval.

Source

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.

Source

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”.

Source

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.

Source

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.

Source

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.

Source

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.”

Source

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.

Source

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.

Trait Implementations§

Source§

impl<const P: usize> Clone for Subscription<P>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<const P: usize> Debug for Subscription<P>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<const P: usize> Forget for Subscription<P>

§

impl<const P: usize> Freeze for Subscription<P>
where VecInner<AttributePath, usize, VecStorageInner<[MaybeUninit<AttributePath>; P]>>: Freeze, VecInner<EventPath, usize, VecStorageInner<[MaybeUninit<EventPath>; P]>>: Freeze,

§

impl<const P: usize> Move for Subscription<P>

§

impl<const P: usize> RefUnwindSafe for Subscription<P>

§

impl<const P: usize> Send for Subscription<P>
where VecInner<AttributePath, usize, VecStorageInner<[MaybeUninit<AttributePath>; P]>>: Send, VecInner<EventPath, usize, VecStorageInner<[MaybeUninit<EventPath>; P]>>: Send,

§

impl<const P: usize> Sync for Subscription<P>
where VecInner<AttributePath, usize, VecStorageInner<[MaybeUninit<AttributePath>; P]>>: Sync, VecInner<EventPath, usize, VecStorageInner<[MaybeUninit<EventPath>; P]>>: Sync,

§

impl<const P: usize> Unpin for Subscription<P>
where VecInner<AttributePath, usize, VecStorageInner<[MaybeUninit<AttributePath>; P]>>: Unpin, VecInner<EventPath, usize, VecStorageInner<[MaybeUninit<EventPath>; P]>>: Unpin,

§

impl<const P: usize> UnsafeUnpin for Subscription<P>

§

impl<const P: usize> UnwindSafe for Subscription<P>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.