Struct aldrin::BusListener
source · pub struct BusListener { /* private fields */ }
Expand description
Monitors the bus for the creation and destruction of objects and services.
BusListener
s use BusListenerFilter
to specify which objects and/or services to
consider. It is possible to register interest in either a set of specific objects (based on
their ObjectUuid
), any object or no objects at all. The same
applies also to services. In all cases, filters match both creation and destruction events. It
is not possible to limit a BusListener
to just one type.
BusListener
s must be started before they emit events. At this point a BusListenerScope
has
to be specified, which controls whether to consider current objects/services, future ones, or
both.
It is also possible to repeatedly start and stop a BusListener
, as well as add and remove
filters at any time. However, some caveats need to be kept in mind:
- Adding filters will not cause events to be emitted for objects/services which exist already on
the bus (if the
BusListener
is started and the scope matches). For this to work, it must be stopped and restarted. - Adding and removing filters is not synchronized with the broker (the respective functions are
not
async
). This means that they will not take effect immediately.
§Examples
§Enumerating all current objects and services
use aldrin::core::{BusEvent, BusListenerFilter, BusListenerScope, ObjectUuid, ServiceUuid};
// Create a few objects and services.
let obj1 = handle.create_object(ObjectUuid::new_v4()).await?;
let service1 = obj1.create_service(ServiceUuid::new_v4(), 0).await?;
let obj2 = handle.create_object(ObjectUuid::new_v4()).await?;
let service2 = obj2.create_service(ServiceUuid::new_v4(), 0).await?;
// Create a bus listener.
let mut bus_listener = handle.create_bus_listener().await?;
// Add filters for all objects and services.
bus_listener.add_filter(BusListenerFilter::any_object())?;
bus_listener.add_filter(BusListenerFilter::any_object_any_service())?;
// Start the bus listener and limit the scope to only current objects and services.
bus_listener.start(BusListenerScope::Current).await?;
// Drain the bus listener of all events. When using [`BusListenerScope::Current`], then only
// creation events will be emitted and `None` will be returned when the bus listener finishes.
while let Some(event) = bus_listener.next_event().await {
match event {
BusEvent::ObjectCreated(id) => {
println!("Object {} found.", id.uuid);
}
BusEvent::ServiceCreated(id) => {
println!("Service {} on object {} found.", id.uuid, id.object_id.uuid);
}
BusEvent::ObjectDestroyed(_) | BusEvent::ServiceDestroyed(_) => unreachable!(),
}
}
Implementations§
source§impl BusListener
impl BusListener
sourcepub fn client(&self) -> &Handle
pub fn client(&self) -> &Handle
Returns a handle to the client that was used to create the bus listener.
sourcepub async fn destroy(&mut self) -> Result<(), Error>
pub async fn destroy(&mut self) -> Result<(), Error>
Destroys the bus listener.
Bus listener are also destroyed implicitly when they fall out of scope.
Events that have already been emitted by the broker may still be emitted by the bus listener after destroying it.
sourcepub fn add_filter(&mut self, filter: BusListenerFilter) -> Result<(), Error>
pub fn add_filter(&mut self, filter: BusListenerFilter) -> Result<(), Error>
Adds a filter to the bus listener.
For an event to be emitted, there must be a filter that matches it. Adding the same filter twice has no effect. In particular, there is no reference counting for filters.
Note that new filters do not affect events which are already in the bus listener’s internal queue.
§Examples
use aldrin::core::{BusListenerFilter, ObjectUuid};
const MY_OBJECT_UUID: ObjectUuid = ObjectUuid(uuid!("0228a930-e194-4b1a-bc3e-6a4defb32527"));
// Add a filter for `MY_OBJECT_UUID`.
bus_listener.add_filter(BusListenerFilter::object(MY_OBJECT_UUID))?;
// Add a filter for all services of `MY_OBJECT_UUID`.
bus_listener.add_filter(BusListenerFilter::specific_object_any_service(MY_OBJECT_UUID))?;
sourcepub fn remove_filter(&mut self, filter: BusListenerFilter) -> Result<(), Error>
pub fn remove_filter(&mut self, filter: BusListenerFilter) -> Result<(), Error>
Remove a filter from the bus listener.
Removing a filter, that isn’t present in the bus listener, has no effect.
Note that filters do not affect events which are already in the bus listener’s internal queue. Thus, events that match only a single filter, may still be emitted after removing it.
§Examples
use aldrin::core::BusListenerFilter;
// Remove the filter that matches all services of any object.
bus_listener.remove_filter(BusListenerFilter::any_object_any_service())?;
sourcepub fn clear_filters(&mut self) -> Result<(), Error>
pub fn clear_filters(&mut self) -> Result<(), Error>
Clears the set of all filters.
The same caveats as with remove_filter
apply.
sourcepub fn filters(&self) -> impl Iterator<Item = BusListenerFilter> + '_
pub fn filters(&self) -> impl Iterator<Item = BusListenerFilter> + '_
Returns an iterator of all filters.
The order in which the filters are returned is unspecified.
sourcepub fn has_filter(&self, filter: BusListenerFilter) -> bool
pub fn has_filter(&self, filter: BusListenerFilter) -> bool
Checks if a specific filter is present.
§Examples
use aldrin::core::BusListenerFilter;
bus_listener.add_filter(BusListenerFilter::any_object_any_service())?;
assert!(bus_listener.has_filter(BusListenerFilter::any_object_any_service()));
bus_listener.remove_filter(BusListenerFilter::any_object_any_service())?;
assert!(!bus_listener.has_filter(BusListenerFilter::any_object_any_service()));
sourcepub fn has_any_filters(&self) -> bool
pub fn has_any_filters(&self) -> bool
Checks if the bus listener has any filters.
§Examples
use aldrin::core::BusListenerFilter;
assert!(!bus_listener.has_any_filters());
bus_listener.add_filter(BusListenerFilter::any_object_any_service())?;
assert!(bus_listener.has_any_filters());
bus_listener.remove_filter(BusListenerFilter::any_object_any_service())?;
assert!(!bus_listener.has_any_filters());
sourcepub fn has_no_filters(&self) -> bool
pub fn has_no_filters(&self) -> bool
Checks if the bus listener has no filters.
§Examples
use aldrin::core::BusListenerFilter;
assert!(bus_listener.has_no_filters());
bus_listener.add_filter(BusListenerFilter::any_object_any_service())?;
assert!(!bus_listener.has_no_filters());
bus_listener.remove_filter(BusListenerFilter::any_object_any_service())?;
assert!(bus_listener.has_no_filters());
sourcepub fn num_filters(&self) -> usize
pub fn num_filters(&self) -> usize
Returns the number of filters.
§Examples
use aldrin::core::BusListenerFilter;
assert_eq!(bus_listener.num_filters(), 0);
bus_listener.add_filter(BusListenerFilter::any_object_any_service())?;
assert_eq!(bus_listener.num_filters(), 1);
bus_listener.add_filter(BusListenerFilter::any_object_any_service())?;
assert_eq!(bus_listener.num_filters(), 1); // No duplicates
bus_listener.remove_filter(BusListenerFilter::any_object_any_service())?;
assert_eq!(bus_listener.num_filters(), 0);
sourcepub async fn start(&mut self, scope: BusListenerScope) -> Result<(), Error>
pub async fn start(&mut self, scope: BusListenerScope) -> Result<(), Error>
Starts the bus listener with the given scope.
Bus listeners can only be started when they are stopped.
sourcepub fn scope(&self) -> Option<BusListenerScope>
pub fn scope(&self) -> Option<BusListenerScope>
Returns the bus listener’s active scope, if any.
The scope returned by this function does not change immediately after calling
start
. It returns the scope that is associated with the events that are
currently returned by next_event
and
poll_next_event
.
sourcepub fn is_finished(&self) -> bool
pub fn is_finished(&self) -> bool
Indicates whether the bus listener can return more events.
This function essentially indicates whether next_event
and
poll_next_event
can possible return Some
or not. You should
continue to call either function for as long as this function returns false
.
Bus listeners can only ever finish if they are stopped or if their scope is
BusListenerScope::Current
and all events have been emitted.
sourcepub fn poll_next_event(
&mut self,
cx: &mut Context<'_>,
) -> Poll<Option<BusEvent>>
pub fn poll_next_event( &mut self, cx: &mut Context<'_>, ) -> Poll<Option<BusEvent>>
Polls the bus listener for an event.
sourcepub async fn next_event(&mut self) -> Option<BusEvent>
pub async fn next_event(&mut self) -> Option<BusEvent>
Await an event from the bus listener.
Trait Implementations§
source§impl Debug for BusListener
impl Debug for BusListener
source§impl Drop for BusListener
impl Drop for BusListener
source§impl FusedStream for BusListener
impl FusedStream for BusListener
source§fn is_terminated(&self) -> bool
fn is_terminated(&self) -> bool
true
if the stream should no longer be polled.source§impl Stream for BusListener
impl Stream for BusListener
Auto Trait Implementations§
impl Freeze for BusListener
impl !RefUnwindSafe for BusListener
impl Send for BusListener
impl Sync for BusListener
impl Unpin for BusListener
impl !UnwindSafe for BusListener
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> 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 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 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 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 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.