pub struct Subscription { /* private fields */ }Expand description
A handle to one subscription — owns the receive end of the bus channel.
Drop unsubscribes from everything automatically. While the handle is
alive, recv / recv_timeout /
try_recv drain queued PubsubFrames in arrival
order.
Threading. Subscription is Send + Sync —
Arc<Subscription> works, so multiple async tasks (or
spawn_blocking jobs) can share one subscription and call recv
concurrently. The underlying std::sync::mpsc::Receiver is
!Sync, so we wrap it (and the matching ack Sender) in a Mutex;
concurrent recv callers serialise on that lock, with each call
receiving a different frame in arrival order (single-consumer
semantics — NOT broadcast fanout). try_recv is non-blocking even
under contention: if the lock is held by a blocking recv,
try_recv returns Ok(None) rather than waiting.
If you need broadcast fanout (every subscriber sees every message),
open a separate Subscription per consumer — they’re cheap.
Implementations§
Source§impl Subscription
impl Subscription
Sourcepub fn subscribe(&mut self, channels: &[&[u8]])
pub fn subscribe(&mut self, channels: &[&[u8]])
SUBSCRIBE channel [channel ...]. Per-channel Subscribe acks are
enqueued onto the receive queue in order.
Sourcepub fn psubscribe(&mut self, patterns: &[&[u8]])
pub fn psubscribe(&mut self, patterns: &[&[u8]])
PSUBSCRIBE pattern [pattern ...]. Patterns use Redis glob syntax
(*, ?, [abc]).
Sourcepub fn unsubscribe(&mut self, channels: &[&[u8]])
pub fn unsubscribe(&mut self, channels: &[&[u8]])
UNSUBSCRIBE [channel ...]. Empty channels removes every channel
subscription this handle holds (matching the Redis wire shape:
individual ack frames for each channel that was actually removed,
or a single Unsubscribe { channel: None } if none were held).
Sourcepub fn punsubscribe(&mut self, patterns: &[&[u8]])
pub fn punsubscribe(&mut self, patterns: &[&[u8]])
PUNSUBSCRIBE [pattern ...]. Empty patterns removes every pattern.
Sourcepub fn recv(&self) -> Result<PubsubFrame>
pub fn recv(&self) -> Result<PubsubFrame>
Block until one frame is queued. Err(io::ErrorKind::UnexpectedEof)
once the underlying bus tears down (last Store clone dropped).
Acquires the receiver mutex for the entire blocking wait — other
recv/recv_timeout callers serialise behind this one. Concurrent
try_recv calls return Ok(None) while a recv is blocked (no
wait on the lock); see the type-level doc for the trade-off.
Sourcepub fn recv_timeout(&self, dur: Duration) -> Result<PubsubFrame>
pub fn recv_timeout(&self, dur: Duration) -> Result<PubsubFrame>
Bounded blocking recv. Err(io::ErrorKind::TimedOut) when dur
elapses; Err(io::ErrorKind::UnexpectedEof) when the bus is gone.
Sourcepub fn try_recv(&self) -> Result<Option<PubsubFrame>>
pub fn try_recv(&self) -> Result<Option<PubsubFrame>>
Non-blocking recv. Ok(None) if the queue is empty;
Err(UnexpectedEof) when the bus is gone.
Uses try_lock so a concurrent blocking recv doesn’t make
try_recv itself block — lock contention is reported as Ok(None)
(semantically: “no frame available right now”). Same shape callers
already handle for an empty queue.