Struct zbus::MessageStream
source · pub struct MessageStream { /* private fields */ }
Expand description
A stream::Stream
implementation that yields Message
items.
You can convert a Connection
to this type and back to Connection
.
NOTE: You must ensure a MessageStream
is continuously polled or you will experience hangs.
If you don’t need to continuously poll the MessageStream
but need to keep it around for later
use, keep the connection around and convert it into a MessageStream
when needed. The
conversion is not an expensive operation so you don’t need to worry about performance, unless
you do it very frequently. If you need to convert back and forth frequently, you may want to
consider keeping both a connection and stream around.
Implementations§
source§impl MessageStream
impl MessageStream
sourcepub async fn for_match_rule<R>(
rule: R,
conn: &Connection,
max_queued: Option<usize>,
) -> Result<Self>
pub async fn for_match_rule<R>( rule: R, conn: &Connection, max_queued: Option<usize>, ) -> Result<Self>
Create a message stream for the given match rule.
If conn
is a bus connection and match rule is for a signal, the match rule will be
registered with the bus and queued for deregistration when the stream is dropped. If you’d
like immediate deregistration, use AsyncDrop::async_drop
. The reason match rules are
only registered with the bus for signals is that D-Bus specification only allows signals to
be broadcasted and unicast messages are always sent to their destination (regardless of any
match rules registered by the destination) by the bus. Hence there is no need to register
match rules for non-signal messages with the bus.
Having said that, stream created by this method can still very useful as it allows you to avoid needless task wakeups and simplify your stream consuming code.
You can optionally also request the capacity of the underlying message queue through
max_queued
. If specified, the capacity is guaranteed to be at least max_queued
. If not
specified, the default of 64 is assumed. The capacity can also be changed later through
MessageStream::set_max_queued
.
§Example
use async_io::Timer;
use zbus::{AsyncDrop, Connection, MatchRule, MessageStream, fdo::NameOwnerChanged};
use futures_util::{TryStreamExt, future::select, future::Either::{Left, Right}, pin_mut};
let conn = Connection::session().await?;
let rule = MatchRule::builder()
.msg_type(zbus::MessageType::Signal)
.sender("org.freedesktop.DBus")?
.interface("org.freedesktop.DBus")?
.member("NameOwnerChanged")?
.add_arg("org.freedesktop.zbus.MatchRuleStreamTest42")?
.build();
let mut stream = MessageStream::for_match_rule(
rule,
&conn,
// For such a specific match rule, we don't need a big queue.
Some(1),
).await?;
let rule_str = "type='signal',sender='org.freedesktop.DBus',\
interface='org.freedesktop.DBus',member='NameOwnerChanged',\
arg0='org.freedesktop.zbus.MatchRuleStreamTest42'";
assert_eq!(
stream.match_rule().map(|r| r.to_string()).as_deref(),
Some(rule_str),
);
// We register 2 names, starting with the uninteresting one. If `stream` wasn't filtering
// messages based on the match rule, we'd receive method return call for each of these 2
// calls first.
//
// Note that the `NameOwnerChanged` signal will not be sent by the bus for the first name
// we register since we setup an arg filter.
conn.request_name("org.freedesktop.zbus.MatchRuleStreamTest44")
.await?;
conn.request_name("org.freedesktop.zbus.MatchRuleStreamTest42")
.await?;
let msg = stream.try_next().await?.unwrap();
let signal = NameOwnerChanged::from_message(msg).unwrap();
assert_eq!(signal.args()?.name(), "org.freedesktop.zbus.MatchRuleStreamTest42");
stream.async_drop().await;
// Ensure the match rule is deregistered and this connection doesn't receive
// `NameOwnerChanged` signals.
let stream = MessageStream::from(&conn).try_filter_map(|msg| async move {
Ok(NameOwnerChanged::from_message(msg))
});
conn.release_name("org.freedesktop.zbus.MatchRuleStreamTest42").await?;
pin_mut!(stream);
let next = stream.try_next();
pin_mut!(next);
let timeout = Timer::after(std::time::Duration::from_millis(50));
pin_mut!(timeout);
match select(next, timeout).await {
Left((msg, _)) => unreachable!("unexpected message: {:?}", msg),
Right((_, _)) => (),
}
§Caveats
Since this method relies on MatchRule::matches
, it inherits its caveats.
sourcepub fn match_rule(&self) -> Option<MatchRule<'_>>
pub fn match_rule(&self) -> Option<MatchRule<'_>>
The associated match rule, if any.
sourcepub fn max_queued(&self) -> usize
pub fn max_queued(&self) -> usize
The maximum number of messages to queue for this stream.
sourcepub fn set_max_queued(&mut self, max_queued: usize)
pub fn set_max_queued(&mut self, max_queued: usize)
Set maximum number of messages to queue for this stream.
After this call, the capacity is guaranteed to be at least max_queued
.
Trait Implementations§
source§impl AsyncDrop for MessageStream
impl AsyncDrop for MessageStream
source§impl Clone for MessageStream
impl Clone for MessageStream
source§fn clone(&self) -> MessageStream
fn clone(&self) -> MessageStream
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for MessageStream
impl Debug for MessageStream
source§impl From<&Connection> for MessageStream
impl From<&Connection> for MessageStream
source§fn from(conn: &Connection) -> Self
fn from(conn: &Connection) -> Self
source§impl From<&MessageStream> for Connection
impl From<&MessageStream> for Connection
source§fn from(stream: &MessageStream) -> Connection
fn from(stream: &MessageStream) -> Connection
source§impl From<Connection> for MessageStream
impl From<Connection> for MessageStream
source§fn from(conn: Connection) -> Self
fn from(conn: Connection) -> Self
source§impl From<MessageStream> for Connection
impl From<MessageStream> for Connection
source§fn from(stream: MessageStream) -> Connection
fn from(stream: MessageStream) -> Connection
source§impl FusedStream for MessageStream
impl FusedStream for MessageStream
source§fn is_terminated(&self) -> bool
fn is_terminated(&self) -> bool
true
if the stream should no longer be polled.source§impl OrderedStream for MessageStream
impl OrderedStream for MessageStream
source§type Ordering = MessageSequence
type Ordering = MessageSequence
source§fn poll_next_before(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
before: Option<&Self::Ordering>,
) -> Poll<PollResult<Self::Ordering, Self::Data>>
fn poll_next_before( self: Pin<&mut Self>, cx: &mut Context<'_>, before: Option<&Self::Ordering>, ) -> Poll<PollResult<Self::Ordering, Self::Data>>
NoneBefore
if it is known that the stream will not produce any
more values ordered before the given point. Read moresource§fn position_hint(&self) -> Option<MaybeBorrowed<'_, Self::Ordering>>
fn position_hint(&self) -> Option<MaybeBorrowed<'_, Self::Ordering>>
source§impl Stream for MessageStream
impl Stream for MessageStream
Auto Trait Implementations§
impl Freeze for MessageStream
impl !RefUnwindSafe for MessageStream
impl Send for MessageStream
impl Sync for MessageStream
impl Unpin for MessageStream
impl !UnwindSafe for MessageStream
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)source§impl<T> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> OrderedStreamExt for Twhere
T: OrderedStream + ?Sized,
impl<T> OrderedStreamExt for Twhere
T: OrderedStream + ?Sized,
source§fn map_item<F, R>(self, f: F) -> MapItem<Self, F>
fn map_item<F, R>(self, f: F) -> MapItem<Self, F>
source§fn map_ordering<NewOrdering, NewData, MapInto, MapFrom>(
self,
map_into: MapInto,
map_from: MapFrom,
) -> MapOrdering<Self, MapInto, MapFrom>where
Self: Sized,
MapInto: FnMut(Self::Ordering, Self::Data) -> (NewOrdering, NewData),
MapFrom: FnMut(&NewOrdering) -> Option<Self::Ordering>,
NewOrdering: Ord,
fn map_ordering<NewOrdering, NewData, MapInto, MapFrom>(
self,
map_into: MapInto,
map_from: MapFrom,
) -> MapOrdering<Self, MapInto, MapFrom>where
Self: Sized,
MapInto: FnMut(Self::Ordering, Self::Data) -> (NewOrdering, NewData),
MapFrom: FnMut(&NewOrdering) -> Option<Self::Ordering>,
NewOrdering: Ord,
fn filter<F>(self, filter: F) -> Filter<Self, F>
fn filter_map<F, R>(self, filter: F) -> FilterMap<Self, F>
source§fn into_stream(self) -> IntoStream<Self>where
Self: Sized,
fn into_stream(self) -> IntoStream<Self>where
Self: Sized,
Stream
, discarding the ordering information.source§fn into_tuple_stream(self) -> IntoTupleStream<Self>where
Self: Sized,
fn into_tuple_stream(self) -> IntoTupleStream<Self>where
Self: Sized,
Stream
, keeping the ordering objects.source§fn into_ordering(self) -> IntoOrdering<Self>where
Self: Sized,
fn into_ordering(self) -> IntoOrdering<Self>where
Self: Sized,
Stream
, keeping only the ordering objects.source§fn next_before<'a>(
&'a mut self,
before: Option<&'a Self::Ordering>,
) -> NextBefore<'a, Self>where
Self: Unpin,
fn next_before<'a>(
&'a mut self,
before: Option<&'a Self::Ordering>,
) -> NextBefore<'a, Self>where
Self: Unpin,
PollResult
corresponding to the next item in the stream.fn peekable(self) -> Peekable<Self>where
Self: Sized,
source§impl<T> StreamExt for T
impl<T> StreamExt for T
source§fn next(&mut self) -> Next<'_, Self>where
Self: Unpin,
fn next(&mut self) -> Next<'_, Self>where
Self: Unpin,
source§fn into_future(self) -> StreamFuture<Self>
fn into_future(self) -> StreamFuture<Self>
source§fn map<T, F>(self, f: F) -> Map<Self, F>
fn map<T, F>(self, f: F) -> Map<Self, F>
source§fn enumerate(self) -> Enumerate<Self>where
Self: Sized,
fn enumerate(self) -> Enumerate<Self>where
Self: Sized,
source§fn filter<Fut, F>(self, f: F) -> Filter<Self, Fut, F>
fn filter<Fut, F>(self, f: F) -> Filter<Self, Fut, F>
source§fn filter_map<Fut, T, F>(self, f: F) -> FilterMap<Self, Fut, F>
fn filter_map<Fut, T, F>(self, f: F) -> FilterMap<Self, Fut, F>
source§fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F>
fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F>
source§fn collect<C>(self) -> Collect<Self, C>
fn collect<C>(self) -> Collect<Self, C>
source§fn unzip<A, B, FromA, FromB>(self) -> Unzip<Self, FromA, FromB>
fn unzip<A, B, FromA, FromB>(self) -> Unzip<Self, FromA, FromB>
source§fn concat(self) -> Concat<Self>
fn concat(self) -> Concat<Self>
source§fn count(self) -> Count<Self>where
Self: Sized,
fn count(self) -> Count<Self>where
Self: Sized,
source§fn fold<T, Fut, F>(self, init: T, f: F) -> Fold<Self, Fut, T, F>
fn fold<T, Fut, F>(self, init: T, f: F) -> Fold<Self, Fut, T, F>
source§fn any<Fut, F>(self, f: F) -> Any<Self, Fut, F>
fn any<Fut, F>(self, f: F) -> Any<Self, Fut, F>
true
if any element in stream satisfied a predicate. Read moresource§fn all<Fut, F>(self, f: F) -> All<Self, Fut, F>
fn all<Fut, F>(self, f: F) -> All<Self, Fut, F>
true
if all element in stream satisfied a predicate. Read moresource§fn flatten(self) -> Flatten<Self>
fn flatten(self) -> Flatten<Self>
source§fn flatten_unordered(
self,
limit: impl Into<Option<usize>>,
) -> FlattenUnorderedWithFlowController<Self, ()>
fn flatten_unordered( self, limit: impl Into<Option<usize>>, ) -> FlattenUnorderedWithFlowController<Self, ()>
source§fn flat_map_unordered<U, F>(
self,
limit: impl Into<Option<usize>>,
f: F,
) -> FlatMapUnordered<Self, U, F>
fn flat_map_unordered<U, F>( self, limit: impl Into<Option<usize>>, f: F, ) -> FlatMapUnordered<Self, U, F>
StreamExt::map
but flattens nested Stream
s
and polls them concurrently, yielding items in any order, as they made
available. Read moresource§fn scan<S, B, Fut, F>(self, initial_state: S, f: F) -> Scan<Self, S, Fut, F>
fn scan<S, B, Fut, F>(self, initial_state: S, f: F) -> Scan<Self, S, Fut, F>
StreamExt::fold
that holds internal state
and produces a new stream. Read moresource§fn skip_while<Fut, F>(self, f: F) -> SkipWhile<Self, Fut, F>
fn skip_while<Fut, F>(self, f: F) -> SkipWhile<Self, Fut, F>
true
. Read moresource§fn take_while<Fut, F>(self, f: F) -> TakeWhile<Self, Fut, F>
fn take_while<Fut, F>(self, f: F) -> TakeWhile<Self, Fut, F>
true
. Read moresource§fn take_until<Fut>(self, fut: Fut) -> TakeUntil<Self, Fut>
fn take_until<Fut>(self, fut: Fut) -> TakeUntil<Self, Fut>
source§fn for_each<Fut, F>(self, f: F) -> ForEach<Self, Fut, F>
fn for_each<Fut, F>(self, f: F) -> ForEach<Self, Fut, F>
source§fn for_each_concurrent<Fut, F>(
self,
limit: impl Into<Option<usize>>,
f: F,
) -> ForEachConcurrent<Self, Fut, F>
fn for_each_concurrent<Fut, F>( self, limit: impl Into<Option<usize>>, f: F, ) -> ForEachConcurrent<Self, Fut, F>
source§fn take(self, n: usize) -> Take<Self>where
Self: Sized,
fn take(self, n: usize) -> Take<Self>where
Self: Sized,
n
items of the underlying stream. Read moresource§fn skip(self, n: usize) -> Skip<Self>where
Self: Sized,
fn skip(self, n: usize) -> Skip<Self>where
Self: Sized,
n
items of the underlying stream. Read moresource§fn catch_unwind(self) -> CatchUnwind<Self>where
Self: Sized + UnwindSafe,
fn catch_unwind(self) -> CatchUnwind<Self>where
Self: Sized + UnwindSafe,
source§fn boxed<'a>(self) -> Pin<Box<dyn Stream<Item = Self::Item> + Send + 'a>>
fn boxed<'a>(self) -> Pin<Box<dyn Stream<Item = Self::Item> + Send + 'a>>
source§fn boxed_local<'a>(self) -> Pin<Box<dyn Stream<Item = Self::Item> + 'a>>where
Self: Sized + 'a,
fn boxed_local<'a>(self) -> Pin<Box<dyn Stream<Item = Self::Item> + 'a>>where
Self: Sized + 'a,
source§fn buffered(self, n: usize) -> Buffered<Self>
fn buffered(self, n: usize) -> Buffered<Self>
source§fn buffer_unordered(self, n: usize) -> BufferUnordered<Self>
fn buffer_unordered(self, n: usize) -> BufferUnordered<Self>
source§fn zip<St>(self, other: St) -> Zip<Self, St>
fn zip<St>(self, other: St) -> Zip<Self, St>
source§fn peekable(self) -> Peekable<Self>where
Self: Sized,
fn peekable(self) -> Peekable<Self>where
Self: Sized,
peek
method. Read moresource§fn chunks(self, capacity: usize) -> Chunks<Self>where
Self: Sized,
fn chunks(self, capacity: usize) -> Chunks<Self>where
Self: Sized,
source§fn ready_chunks(self, capacity: usize) -> ReadyChunks<Self>where
Self: Sized,
fn ready_chunks(self, capacity: usize) -> ReadyChunks<Self>where
Self: Sized,
source§fn forward<S>(self, sink: S) -> Forward<Self, S>
fn forward<S>(self, sink: S) -> Forward<Self, S>
source§fn split<Item>(self) -> (SplitSink<Self, Item>, SplitStream<Self>)
fn split<Item>(self) -> (SplitSink<Self, Item>, SplitStream<Self>)
source§fn inspect<F>(self, f: F) -> Inspect<Self, F>
fn inspect<F>(self, f: F) -> Inspect<Self, F>
source§fn left_stream<B>(self) -> Either<Self, B>
fn left_stream<B>(self) -> Either<Self, B>
source§fn right_stream<B>(self) -> Either<B, Self>
fn right_stream<B>(self) -> Either<B, Self>
source§fn poll_next_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>where
Self: Unpin,
fn poll_next_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>where
Self: Unpin,
Stream::poll_next
on Unpin
stream types.source§fn select_next_some(&mut self) -> SelectNextSome<'_, Self>where
Self: Unpin + FusedStream,
fn select_next_some(&mut self) -> SelectNextSome<'_, Self>where
Self: Unpin + FusedStream,
source§impl<S> TryStreamExt for S
impl<S> TryStreamExt for S
source§fn err_into<E>(self) -> ErrInto<Self, E>
fn err_into<E>(self) -> ErrInto<Self, E>
source§fn map_ok<T, F>(self, f: F) -> MapOk<Self, F>
fn map_ok<T, F>(self, f: F) -> MapOk<Self, F>
source§fn map_err<E, F>(self, f: F) -> MapErr<Self, F>
fn map_err<E, F>(self, f: F) -> MapErr<Self, F>
source§fn and_then<Fut, F>(self, f: F) -> AndThen<Self, Fut, F>
fn and_then<Fut, F>(self, f: F) -> AndThen<Self, Fut, F>
f
. Read moresource§fn or_else<Fut, F>(self, f: F) -> OrElse<Self, Fut, F>
fn or_else<Fut, F>(self, f: F) -> OrElse<Self, Fut, F>
f
. Read moresource§fn inspect_ok<F>(self, f: F) -> InspectOk<Self, F>
fn inspect_ok<F>(self, f: F) -> InspectOk<Self, F>
source§fn inspect_err<F>(self, f: F) -> InspectErr<Self, F>
fn inspect_err<F>(self, f: F) -> InspectErr<Self, F>
source§fn into_stream(self) -> IntoStream<Self>where
Self: Sized,
fn into_stream(self) -> IntoStream<Self>where
Self: Sized,
source§fn try_next(&mut self) -> TryNext<'_, Self>where
Self: Unpin,
fn try_next(&mut self) -> TryNext<'_, Self>where
Self: Unpin,
source§fn try_for_each<Fut, F>(self, f: F) -> TryForEach<Self, Fut, F>
fn try_for_each<Fut, F>(self, f: F) -> TryForEach<Self, Fut, F>
source§fn try_skip_while<Fut, F>(self, f: F) -> TrySkipWhile<Self, Fut, F>
fn try_skip_while<Fut, F>(self, f: F) -> TrySkipWhile<Self, Fut, F>
true
. Read moresource§fn try_take_while<Fut, F>(self, f: F) -> TryTakeWhile<Self, Fut, F>
fn try_take_while<Fut, F>(self, f: F) -> TryTakeWhile<Self, Fut, F>
true
. Read moresource§fn try_for_each_concurrent<Fut, F>(
self,
limit: impl Into<Option<usize>>,
f: F,
) -> TryForEachConcurrent<Self, Fut, F>
fn try_for_each_concurrent<Fut, F>( self, limit: impl Into<Option<usize>>, f: F, ) -> TryForEachConcurrent<Self, Fut, F>
source§fn try_collect<C>(self) -> TryCollect<Self, C>
fn try_collect<C>(self) -> TryCollect<Self, C>
source§fn try_chunks(self, capacity: usize) -> TryChunks<Self>where
Self: Sized,
fn try_chunks(self, capacity: usize) -> TryChunks<Self>where
Self: Sized,
source§fn try_ready_chunks(self, capacity: usize) -> TryReadyChunks<Self>where
Self: Sized,
fn try_ready_chunks(self, capacity: usize) -> TryReadyChunks<Self>where
Self: Sized,
source§fn try_filter<Fut, F>(self, f: F) -> TryFilter<Self, Fut, F>
fn try_filter<Fut, F>(self, f: F) -> TryFilter<Self, Fut, F>
source§fn try_filter_map<Fut, F, T>(self, f: F) -> TryFilterMap<Self, Fut, F>
fn try_filter_map<Fut, F, T>(self, f: F) -> TryFilterMap<Self, Fut, F>
source§fn try_flatten_unordered(
self,
limit: impl Into<Option<usize>>,
) -> TryFlattenUnordered<Self>
fn try_flatten_unordered( self, limit: impl Into<Option<usize>>, ) -> TryFlattenUnordered<Self>
source§fn try_flatten(self) -> TryFlatten<Self>
fn try_flatten(self) -> TryFlatten<Self>
source§fn try_fold<T, Fut, F>(self, init: T, f: F) -> TryFold<Self, Fut, T, F>
fn try_fold<T, Fut, F>(self, init: T, f: F) -> TryFold<Self, Fut, T, F>
source§fn try_concat(self) -> TryConcat<Self>
fn try_concat(self) -> TryConcat<Self>
source§fn try_buffer_unordered(self, n: usize) -> TryBufferUnordered<Self>
fn try_buffer_unordered(self, n: usize) -> TryBufferUnordered<Self>
source§fn try_buffered(self, n: usize) -> TryBuffered<Self>
fn try_buffered(self, n: usize) -> TryBuffered<Self>
source§fn try_poll_next_unpin(
&mut self,
cx: &mut Context<'_>,
) -> Poll<Option<Result<Self::Ok, Self::Error>>>where
Self: Unpin,
fn try_poll_next_unpin(
&mut self,
cx: &mut Context<'_>,
) -> Poll<Option<Result<Self::Ok, Self::Error>>>where
Self: Unpin,
TryStream::try_poll_next
on Unpin
stream types.source§fn into_async_read(self) -> IntoAsyncRead<Self>
fn into_async_read(self) -> IntoAsyncRead<Self>
AsyncBufRead
. Read moresource§fn try_all<Fut, F>(self, f: F) -> TryAll<Self, Fut, F>
fn try_all<Fut, F>(self, f: F) -> TryAll<Self, Fut, F>
Err
is encountered or if an Ok
item is found
that does not satisfy the predicate. Read more