pub struct Subscriber { /* private fields */ }Expand description
One subscribed connection. Owns either a TCP socket or an in-process
Subscription; the variant is chosen by the URL scheme in
Subscriber::open / Subscriber::connect.
Implementations§
Source§impl Subscriber
impl Subscriber
Sourcepub fn connect(url: &str) -> Result<Self>
pub fn connect(url: &str) -> Result<Self>
Open a fresh connection without subscribing to anything yet. Call
Self::subscribe / Self::psubscribe next.
Accepted URLs:
kevy://,redis://,tcp://— TCP RESP servermem://<name>,file:///path— in-process shared busmem://(anonymous),rediss://,kevys://,redis://user:pass@…are rejected withio::ErrorKind::Unsupported
Sourcepub fn open(url: &str, channels: &[&[u8]]) -> Result<Self>
pub fn open(url: &str, channels: &[&[u8]]) -> Result<Self>
Open and subscribe to one or more channels in one step. Returns
ErrorKind::InvalidInput if channels is empty (use
Self::connect for an empty start).
Sourcepub fn subscribe(&mut self, channels: &[&[u8]]) -> Result<()>
pub fn subscribe(&mut self, channels: &[&[u8]]) -> Result<()>
SUBSCRIBE channel [channel ...]. Per-channel Subscribe acks
are delivered via Self::recv.
Sourcepub fn psubscribe(&mut self, patterns: &[&[u8]]) -> Result<()>
pub fn psubscribe(&mut self, patterns: &[&[u8]]) -> Result<()>
PSUBSCRIBE pattern [pattern ...]. Patterns use Redis glob syntax
(*, ?, […]).
Sourcepub fn unsubscribe(&mut self, channels: &[&[u8]]) -> Result<()>
pub fn unsubscribe(&mut self, channels: &[&[u8]]) -> Result<()>
UNSUBSCRIBE [channel ...]. Empty channels unsubscribes from
every channel (Redis wire semantics).
Sourcepub fn punsubscribe(&mut self, patterns: &[&[u8]]) -> Result<()>
pub fn punsubscribe(&mut self, patterns: &[&[u8]]) -> Result<()>
PUNSUBSCRIBE [pattern ...]. Empty patterns unsubscribes from
every pattern.
Sourcepub fn recv(&mut self) -> Result<PubsubEvent>
pub fn recv(&mut self) -> Result<PubsubEvent>
Block until the next pubsub frame arrives. Apply
Self::set_read_timeout for bounded blocking.
Connection close / bus tear-down yields ErrorKind::UnexpectedEof.
Sourcepub fn recv_message(&mut self) -> Result<(Vec<u8>, Vec<u8>)>
pub fn recv_message(&mut self) -> Result<(Vec<u8>, Vec<u8>)>
Block until the next published Message / Pmessage arrives,
silently skipping subscription-acknowledgement frames
(PubsubEvent::Subscribe / PubsubEvent::Unsubscribe /
PubsubEvent::Psubscribe / PubsubEvent::Punsubscribe) along
the way.
This is the form most callers want — almost no consumer of
pubsub needs to see the ack frames (they’re a wire-protocol
detail), so a loop+match around Self::recv is essentially
boilerplate. Returns (channel, payload). For pattern matches,
channel is the concrete channel the publisher used (matching
Redis’s pmessage shape, where pattern is discarded — use
Self::recv directly if you need it).
Errors from Self::recv (connection close, timeout, etc.)
propagate unchanged.
Sourcepub fn hello3(&mut self) -> Result<PubsubEvent>
pub fn hello3(&mut self) -> Result<PubsubEvent>
Negotiate RESP3 on this connection by sending HELLO 3 and
draining the ack. Subsequent SUBSCRIBE / PSUBSCRIBE /
PUBLISH deliveries arrive as push frames (>N\r\n…) instead
of the legacy RESP2 array shape (*N\r\n…); Self::recv
accepts both transparently, so existing code keeps working with
no other changes.
Remote-only: the embedded backend has no proto negotiation
concept (frames go through the in-process bus typed). Calling
hello3 on an embedded Subscriber returns
io::ErrorKind::Unsupported.
Must be called BEFORE any Self::subscribe /
Self::psubscribe — Redis requires HELLO be the first
command on a connection that uses it.
Sourcepub fn set_read_timeout(&mut self, dur: Option<Duration>) -> Result<()>
pub fn set_read_timeout(&mut self, dur: Option<Duration>) -> Result<()>
Apply (or clear) a read timeout. After setting Some(dur),
Self::recv returns an io::Error of kind WouldBlock /
TimedOut when no frame arrives within dur.
Sourcepub fn events(&mut self) -> SubscriberEvents<'_> ⓘ
pub fn events(&mut self) -> SubscriberEvents<'_> ⓘ
Borrowing iterator over every pubsub frame — ack frames included.
Each next() is one blocking Self::recv. Terminates (None)
when the underlying stream / bus is gone (ErrorKind::UnexpectedEof);
every other error is surfaced as Some(Err(_)) so the caller can
decide whether to retry (e.g. a read timeout) or break.
kevy stays 0-deps so this is a std::iter::Iterator, not a
futures::Stream. Async runtimes consume it via
spawn_blocking (see docs/pubsub.md).
Sourcepub fn messages(&mut self) -> SubscriberMessages<'_> ⓘ
pub fn messages(&mut self) -> SubscriberMessages<'_> ⓘ
Borrowing iterator that silently skips (p)?(un)?subscribe acks
and yields the payload tuples consumers actually want. Mirrors
Self::recv_message in iterator form. For Pmessage the
pattern is discarded — fall back to Self::events if you need it.