pub struct Consumer { /* private fields */ }Expand description
Cheap read handle over an origin’s broadcast tree.
Clones share the underlying tree state without allocating any per-cursor
resources. To actually receive announce / unannounce events, call
Self::announced to obtain an AnnounceConsumer.
Implementations§
Source§impl Consumer
impl Consumer
Sourcepub fn with_stats(self, session: Session) -> Self
pub fn with_stats(self, session: Session) -> Self
Attach an egress stats context: broadcasts handed out through this handle (and
any handle derived from it) are attributed to session on the publisher
(egress) side. Pass stats::Session::default to opt out.
Sourcepub fn announced(&self) -> AnnounceConsumer
pub fn announced(&self) -> AnnounceConsumer
Subscribe to announce / unannounce events for this consumer’s subtree.
Allocates a per-cursor coalescing buffer, registers it with each root
in this consumer’s scope, and replays the currently active broadcast
set as initial announcements. Drop the returned AnnounceConsumer
to unregister.
Sourcepub async fn announced_broadcast(&self, path: impl AsPath) -> Option<Consumer>
pub async fn announced_broadcast(&self, path: impl AsPath) -> Option<Consumer>
Block until a broadcast with the given path is announced and return it.
Returns None if the path is outside this consumer’s allowed prefixes or if the consumer
is closed before the broadcast is announced. The returned broadcast may itself be closed
later. Subscribers should watch broadcast::Consumer::closed to react to that.
Prefer this over Self::request_broadcast when you know the exact path you want but
cannot guarantee the announcement has already been received. With moq-lite-05 (and
the older Lite01/02) connect() already blocks until the initial announce set lands,
so Self::request_broadcast is race-free for broadcasts that were live at connect time;
this method is still needed to wait for a broadcast that comes online after connect.
Sourcepub fn scope(&self, prefixes: &[Path<'_>]) -> Option<Consumer>
pub fn scope(&self, prefixes: &[Path<'_>]) -> Option<Consumer>
Returns a new Consumer restricted to broadcasts under one of prefixes.
Returns None if there are no legal prefixes (the requested prefixes are disjoint from this consumer’s current scope, so it would always return None).
Sourcepub fn request_broadcast(&self, path: impl AsPath) -> Pending<Requesting>
pub fn request_broadcast(&self, path: impl AsPath) -> Pending<Requesting>
Get a broadcast by path, falling back to a dynamic request when it is not announced.
Returns a kio::Pending future (resolved synchronously for an announced broadcast,
otherwise once a handler serves it), mirroring track::Consumer::fetch_group.
The lookup order is: an already-announced broadcast resolves
immediately; otherwise, if an Dynamic handler is live (see
Producer::dynamic), a fallback request is registered and the future resolves
when the handler accepts it (or errors if it
rejects or every handler drops). Concurrent requests for
the same unannounced path coalesce onto one handler request, and once served the
broadcast is cached weakly so later requests for that path also share it (rather
than re-invoking the handler and opening a duplicate upstream subscription) for as
long as it stays live; a closed one is re-served on the next request.
The returned future resolves to Error::Unroutable when the path is not announced and no
dynamic handler exists. A request that is registered while a handler is live but then loses
every handler before being served also resolves to Error::Unroutable. Unlike an announced
broadcast, a dynamically served one is never visible to Self::announced.
Sourcepub fn with_root(&self, prefix: impl AsPath) -> Option<Self>
pub fn with_root(&self, prefix: impl AsPath) -> Option<Self>
Returns a new Consumer that automatically strips out the provided prefix.
Returns None if the provided root is not authorized; when Self::scope was
already used without a wildcard.
Sourcepub fn root(&self) -> &Path<'_>
pub fn root(&self) -> &Path<'_>
Returns the prefix that is automatically stripped from all paths.