Struct aldrin::Service

pub struct Service { /* private fields */ }

Owned service on the bus.

Services are associated with an Object and created with Object::create_service. Services can be destroyed again by calling destroy, by dropping them, or implicitly when the Object is destroyed.

Service exposes an asynchronous stream of incoming FunctionCalls via its implementation of the Stream trait.

Events can be emitted directly with Handle::emit_event. This is available on Handle, because usually Service is borrowed mutably to wait for function calls. The ServiceId required for Handle::emit_event can be obtained with e.g. Service::id.

Examples

Creating and destroying Services:

use aldrin::Error;
use aldrin::core::{ObjectUuid, ServiceUuid};
use std::mem;
use uuid::uuid;

const SERVICE_UUID: ServiceUuid = ServiceUuid(uuid!("f88f1706-9609-42a4-8796-4e7bb8c3ef24"));

let object = handle.create_object(ObjectUuid::new_v4()).await?;

// Create a service and destroy it again explicitly:
let service = object.create_service(SERVICE_UUID, 1).await?;
service.destroy().await?;

// Destroy a service implicitly by dropping it:
let service = object.create_service(SERVICE_UUID, 1).await?;
mem::drop(service);

// Destroy a service implicitly by dropping the object:
let service = object.create_service(SERVICE_UUID, 1).await?;
let service_id = service.id();
mem::drop(object);
assert_eq!(service.destroy().await, Err(Error::InvalidService));

The following is a small chat server example, which shows how to handle function call on a service and how to emit events.

use aldrin::core::{ObjectUuid, ServiceUuid};
use std::collections::HashSet;
use uuid::uuid;

const CHAT_UUID: ServiceUuid = ServiceUuid(uuid!("91334d42-7045-4292-99dc-9fd89c5f104f"));

// Functions
const SHUTDOWN: u32 = 1;
const JOIN_CHAT: u32 = 2;
const LEAVE_CHAT: u32 = 3;
const LIST_USERS: u32 = 4;
const SEND_MESSAGE: u32 = 5;

// Events
const JOINED_CHAT: u32 = 1;
const LEFT_CHAT: u32 = 2;
const MESSAGE_SENT: u32 = 3;

// Create object and our chat service:
let object = handle.create_object(ObjectUuid::new_v4()).await?;
let mut service = object.create_service(CHAT_UUID, 1).await?;
let service_id = service.id();

// HashSet to keep track of users:
let mut users = HashSet::new();

// Iterate (asynchronously) over incoming function calls. `func` is of type `FunctionCall`,
// which contains the function's id, the arguments, and a reply object.
while let Some(func) = service.next_function_call().await {
    match func.id {
        SHUTDOWN => break,

        JOIN_CHAT => {
            let name: String = func.args.deserialize()?;
            if users.insert(name.clone()) {
                // Emit an event that a new user with the given name joined:
                handle.emit_event(service_id, JOINED_CHAT, &name)?;

                func.reply.ok(&())?;
            } else {
                // Signal that the name is already taken.
                func.reply.err(&())?;
            }
        }

        LEAVE_CHAT => {
            let name: String = func.args.deserialize()?;
            if users.remove(&name) {
                // Emit an event that a user with the given name left:
                handle.emit_event(service_id, LEFT_CHAT, &name)?;

                func.reply.ok(&())?;
            } else {
                // Signal that the name is not known.
                func.reply.err(&())?;
            }
        }

        LIST_USERS => func.reply.ok(&users)?,

        SEND_MESSAGE => {
            // Broadcast the message:
            let message = func.args.deserialize()?;
            handle.emit_event(service_id, MESSAGE_SENT, &message)?;
            func.reply.ok(&())?;
        }

        _ => {}
    }
}

Implementations

impl Service

pub fn id(&self) -> ServiceId

Returns the id of the service.

pub fn version(&self) -> u32

Returns the version of the service.

pub fn handle(&self) -> &Handle

Returns a handle to the client that was used to create the service.

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

Destroys the service.

If the Service has already been destroyed, then Error::InvalidService is returned.

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

Polls for the next function call.

pub async fn next_function_call(&mut self) -> Option<FunctionCall>

Returns the next function call.

Trait Implementations

impl Debug for Service

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

Formats the value using the given formatter.

impl Drop for Service

fn drop(&mut self)

Executes the destructor for this type.

impl FusedStream for Service

fn is_terminated(&self) -> bool

Returns true if the stream should no longer be polled.

impl Stream for Service

type Item = FunctionCall

Values yielded by the stream.

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

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.