Struct aldrin::BusListener

pub struct BusListener { /* private fields */ }

Monitors the bus for the creation and destruction of objects and services.

BusListeners 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.

BusListeners 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

impl BusListener

pub fn handle(&self) -> &Handle

Returns a handle to the client that was used to create the bus listener.

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.

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))?;

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())?;

pub fn clear_filters(&mut self) -> Result<(), Error>

Clears the set of all filters.

The same caveats as with remove_filter apply.

pub fn filters(&self) -> impl Iterator<Item = BusListenerFilter> + '_

Returns an iterator of all filters.

The order in which the filters are returned is unspecified.

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()));

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());

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());

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);

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.

pub async fn stop(&mut self) -> Result<(), Error>

Stops the bus listener.

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.

pub fn 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.

pub fn poll_next_event( &mut self, cx: &mut Context<'_> ) -> Poll<Option<BusEvent>>

Polls the bus listener for an event.

pub async fn next_event(&mut self) -> Option<BusEvent>

Await an event from the bus listener.

Trait Implementations

impl Debug for BusListener

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for BusListener

fn drop(&mut self)

Executes the destructor for this type.

impl FusedStream for BusListener

fn is_terminated(&self) -> bool

Returns true if the stream should no longer be polled.

impl Stream for BusListener

type Item = BusEvent

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<BusEvent>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.