pub struct SubscriptionTable<C: Config, const N: usize = 15, const P: usize = 3> { /* private fields */ }Expand description
The publisher’s set of active subscriptions.
Fixed capacity from N, which SubscriptionTable::CHECK holds to
§2.11.2.2’s “at least three Subscribe Interactions” per fabric.
Implementations§
Source§impl<C: Config, const N: usize, const P: usize> SubscriptionTable<C, N, P>
impl<C: Config, const N: usize, const P: usize> SubscriptionTable<C, N, P>
Sourcepub const CHECK: ()
pub const CHECK: ()
Compile-time proof that this table can keep §2.11.2.2’s promise.
A publisher SHALL ensure that every fabric the node is commissioned into can support at least three Subscribe Interactions to the publisher.
A promise of SUBSCRIPTIONS_PER_FABRIC to each of FABRICS fabrics needs room for
their product. Without this the node advertises a guarantee it cannot keep, and the
fabric that finds out is the last one commissioned.
Source§impl<C: Config, const N: usize, const P: usize> SubscriptionTable<C, N, P>
impl<C: Config, const N: usize, const P: usize> SubscriptionTable<C, N, P>
Sourcepub fn iter(&self) -> impl Iterator<Item = &Subscription<P>>
pub fn iter(&self) -> impl Iterator<Item = &Subscription<P>>
The subscriptions, in creation order.
Sourcepub fn find(&self, id: u32) -> Option<&Subscription<P>>
pub fn find(&self, id: u32) -> Option<&Subscription<P>>
The subscription with this id.
Sourcepub fn find_mut(&mut self, id: u32) -> Option<&mut Subscription<P>>
pub fn find_mut(&mut self, id: u32) -> Option<&mut Subscription<P>>
The subscription with this id, mutably.
Sourcepub fn remove(&mut self, id: u32) -> bool
pub fn remove(&mut self, id: u32) -> bool
Ends a subscription.
§8.5: “When a Subscribe interaction is terminated on the publisher or subscriber, the subscription, identified by a SubscriptionId, SHALL also be terminated.”
Sourcepub fn remove_for_session(&mut self, session: Option<SessionId>) -> usize
pub fn remove_for_session(&mut self, session: Option<SessionId>) -> usize
Ends every subscription belonging to one session — §8.5.2.3’s KeepSubscriptions.
If KeepSubscriptions is FALSE, all existing or pending subscriptions on the publisher for this subscriber SHALL be terminated.
Returns how many went. A subscriber that re-subscribes without the flag is saying “I have restarted, forget what you knew about me” — and a publisher that kept the old subscriptions would report to a twin that no longer exists until the maximum interval ran out on each.
Sourcepub fn remove_for_fabric(&mut self, fabric: FabricIndex) -> usize
pub fn remove_for_fabric(&mut self, fabric: FabricIndex) -> usize
Ends every subscription scoped to a fabric — what RemoveFabric cascades into.
Sourcepub fn note_event(&mut self, endpoint: u16, cluster: u32, event: u32) -> usize
pub fn note_event(&mut self, endpoint: u16, cluster: u32, event: u32) -> usize
Records a queued event against every subscription that wants it.
Returns how many were made pending — that is, how many had marked the path urgent. A subscription that wants the event but did not ask urgently still receives it, on whatever report happens next; §8.5 is explicit that non-urgent queueing “does not automatically trigger a Report transaction”.
Sourcepub fn note_change(&mut self, path: &AttributePath) -> usize
pub fn note_change(&mut self, path: &AttributePath) -> usize
Records a change against every subscription that covers it.
This is the whole of the reporting engine’s input: a cluster whose value changed calls it once, and each subscription decides for itself whether it cares and when it will say so.
Not for an attribute with the C quality. §8.5: a report carries every change
“with the exception of attribute data with the Changes Omitted (C) quality” — a client
polls for those, and reporting one would be reporting what the specification asked a
publisher not to.
Sourcepub fn reprime_all(&mut self)
pub fn reprime_all(&mut self)
Marks every subscription for a full re-prime — what a lost acknowledgement calls for.
Sourcepub fn next_deadline(&self) -> Option<Instant>
pub fn next_deadline(&self) -> Option<Instant>
The earliest moment any subscription needs attention, if there are any.
A device sleeps until this. An intermittently connected one uses it to decide whether it can stay idle, which is why §2.11.2.2 lets it choose a long maximum interval.
Unbound subscriptions are skipped for the same reason SubscriptionTable::due skips
them: waking for one would be waking to do nothing.
Sourcepub fn due(
&self,
now: Instant,
) -> impl Iterator<Item = (&Subscription<P>, ReportReason)>
pub fn due( &self, now: Instant, ) -> impl Iterator<Item = (&Subscription<P>, ReportReason)>
The subscriptions with a report due at now, and why.
A subscription with no session is skipped however overdue it is, because there is
nowhere to send the report — that is the state a subscription restored from storage
begins in (persist), waiting for its subscriber to come back
on a new CASE session. Handing it to a caller that could only discard it would make
every poll return work that cannot be done.
Sourcepub fn subscribe(
&mut self,
request: &NewSubscription<'_>,
now: Instant,
) -> Result<u32, SubscribeError>
pub fn subscribe( &mut self, request: &NewSubscription<'_>, now: Instant, ) -> Result<u32, SubscribeError>
Creates a subscription, allocating an id.
keep_subscriptions is the request’s flag: when false, every existing subscription
for this session goes first (§8.5.2.3). That happens before the capacity check, so a
subscriber re-subscribing at the table’s limit succeeds rather than being refused with
its own stale subscriptions in the way.
Sourcepub fn note_cluster_change(
&mut self,
endpoint: EndpointId,
cluster: ClusterId,
) -> usize
pub fn note_cluster_change( &mut self, endpoint: EndpointId, cluster: ClusterId, ) -> usize
Records that an attribute of one cluster instance changed, dirtying every subscription that overlaps it. Returns how many.
This is the cluster-grained counterpart to SubscriptionTable::note_change, and it is
what DataVersions::drain_changes feeds. The
grain is the cluster because that is the grain §7.10.3 records changes at: “A cluster
data version SHALL be incremented if any attribute data changes” says which cluster,
never which attribute.
Reporting a whole cluster when one attribute of it moved is more than the minimum and never less, which is the safe direction: §8.5 already allows a report to carry more than changed — a re-prime carries everything — and a subscriber that is told too much is correct where one that is told too little is not.
Sourcepub fn iter_mut(&mut self) -> impl Iterator<Item = &mut Subscription<P>>
pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut Subscription<P>>
Every subscription, mutably.
Sourcepub fn len_of_fabric(&self, fabric: Option<FabricIndex>) -> usize
pub fn len_of_fabric(&self, fabric: Option<FabricIndex>) -> usize
How many subscriptions one fabric holds. None counts the fabric-less ones.
Trait Implementations§
Source§impl<C: Config, const N: usize, const P: usize> Capacity for SubscriptionTable<C, N, P>
impl<C: Config, const N: usize, const P: usize> Capacity for SubscriptionTable<C, N, P>
Source§const PER_FABRIC: usize = C::SUBSCRIPTIONS_PER_FABRIC
const PER_FABRIC: usize = C::SUBSCRIPTIONS_PER_FABRIC
§11.1.4.4’s SubscriptionsPerFabric: the fixed share each fabric is promised.
The policy figure rather than N / FABRICS, because the share is what
SubscriptionTable::admit enforces — and SubscriptionTable::CHECK is what makes
the two agree.