Skip to main content

SubscriptionTable

Struct SubscriptionTable 

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

Source

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>

Source

pub fn new() -> Self

An empty table.

Source

pub fn len(&self) -> usize

How many subscriptions are active.

Source

pub fn is_empty(&self) -> bool

Whether none are.

Source

pub const fn capacity(&self) -> usize

How many this node can serve.

Source

pub fn iter(&self) -> impl Iterator<Item = &Subscription<P>>

The subscriptions, in creation order.

Source

pub fn find(&self, id: u32) -> Option<&Subscription<P>>

The subscription with this id.

Source

pub fn find_mut(&mut self, id: u32) -> Option<&mut Subscription<P>>

The subscription with this id, mutably.

Source

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

Source

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.

Source

pub fn remove_for_fabric(&mut self, fabric: FabricIndex) -> usize

Ends every subscription scoped to a fabric — what RemoveFabric cascades into.

Source

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

Source

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.

Source

pub fn reprime_all(&mut self)

Marks every subscription for a full re-prime — what a lost acknowledgement calls for.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut Subscription<P>>

Every subscription, mutably.

Source

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>

Source§

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.

Source§

const TOTAL: usize = N

Total slots, across every fabric.
Source§

impl<C: Debug + Config, const N: usize, const P: usize> Debug for SubscriptionTable<C, N, P>

Source§

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

Formats the value using the given formatter. Read more
Source§

impl<C: Config, const N: usize, const P: usize> Default for SubscriptionTable<C, N, P>

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl<C: Config, const N: usize, const P: usize> SubscriptionCapacity for SubscriptionTable<C, N, P>

Source§

const PATHS: usize = P

How many attribute or event paths one subscription can carry.

Auto Trait Implementations§

§

impl<C, const N: usize, const P: usize> Forget for SubscriptionTable<C, N, P>

§

impl<C, const N: usize, const P: usize> Freeze for SubscriptionTable<C, N, P>
where VecInner<Subscription<P>, usize, VecStorageInner<[MaybeUninit<Subscription<P>>; N]>>: Freeze, PhantomData<C>: Freeze,

§

impl<C, const N: usize, const P: usize> Move for SubscriptionTable<C, N, P>

§

impl<C, const N: usize, const P: usize> RefUnwindSafe for SubscriptionTable<C, N, P>

§

impl<C, const N: usize, const P: usize> Send for SubscriptionTable<C, N, P>
where VecInner<Subscription<P>, usize, VecStorageInner<[MaybeUninit<Subscription<P>>; N]>>: Send, PhantomData<C>: Send,

§

impl<C, const N: usize, const P: usize> Sync for SubscriptionTable<C, N, P>
where VecInner<Subscription<P>, usize, VecStorageInner<[MaybeUninit<Subscription<P>>; N]>>: Sync, PhantomData<C>: Sync,

§

impl<C, const N: usize, const P: usize> Unpin for SubscriptionTable<C, N, P>
where VecInner<Subscription<P>, usize, VecStorageInner<[MaybeUninit<Subscription<P>>; N]>>: Unpin, PhantomData<C>: Unpin,

§

impl<C, const N: usize, const P: usize> UnsafeUnpin for SubscriptionTable<C, N, P>

§

impl<C, const N: usize, const P: usize> UnwindSafe for SubscriptionTable<C, N, 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> 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, 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.