Crate aldrin

Source
Expand description

Aldrin client library

This library implements the client side of the Aldrin specification and can be used to connect to Aldrin brokers. It is fully asynchronous (async/await) and doesn’t depend on any specific async runtime.

Parts of this library should be considered low-level building blocks for the code that can be auto-generated from Aldrin schemas. As an example, performing a function call on a service requires knowing the function’s id and uses a polymorphic type to encode the function’s arguments. It is generally recommended to rely on the more ergonomic auto-generated code instead.

The first entry point is the Client and it’s connect method. Clients are parameterized over an AsyncTransport, which abstracts the low-level details of a transport, like e.g. TCP/IP.

After establishing a connection, the resulting Client must be continuously polled (through Client::run). One way to achieve this is to “spawn” it with an async runtime of your choice. Alternatively, it can also be polled manually.

While the Client is being polled, all interaction with it happens through a Handle, which can be acquired with Client::handle. The Client will automatically shut down (as in, the Client::run future will complete) when the last Handle has been dropped.

§Examples

use aldrin::Client;
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // Create an AsyncTransport for connecting to the broker.
    // let async_transport = ...

    // Connect to the broker:
    let client = Client::connect(async_transport).await?;

    // Acquire a handle and spawn the client:
    let handle = client.handle().clone();
    let join = tokio::spawn(client.run());

    // The client is now fully connected and can be interacted with through the handle.

    // Shut down client:
    handle.shutdown();
    join.await??;

    Ok(())
}

Re-exports§

pub use error::Error;
pub use aldrin_core as core;

Modules§

error
Error types.
low_level
Low-level types

Macros§

generate
Generates code from an Aldrin schema.
service
Defines a service and proxy type.

Structs§

BusListener
Monitors the bus for the creation and destruction of objects and services.
Call
Pending call.
ChannelBuilder
Builder type for creating channels.
Client
Aldrin client used to connect to a broker.
Discoverer
Discovers objects with multiple services on the bus.
DiscovererBuilder
Builder for Discoverers.
DiscovererEntry
Entry of a Discoverer.
DiscovererEntryIter
Iterator over all found objects corresponding to a specific key.
DiscovererEvent
Event emitted by Discoverers.
DiscovererIter
Iterator over all found objects of a Discoverer.
DiscovererIterEntry
Item type when iterating over a Discoverer or DiscovererEntry.
Event
Event emitted by a service.
Handle
Handle to a client.
Lifetime
Notifies when a LifetimeScope ends.
LifetimeId
Id of a scope’s lifetime.
LifetimeScope
A scope that notifies other clients when ends.
Object
Owned object on the bus.
PendingReceiver
A receiver that is waiting for the channel to be established.
PendingReply
Future to await the result of a call.
PendingSender
A sender that is waiting for the channel to be established.
Promise
Replies to a pending call.
Property
Tracks some state of a service.
Receiver
The receiving end of an established channel.
Reply
Reply of a call.
Sender
The sending end of an established channel.
UnboundReceiver
A receiver that isn’t bound to any client.
UnboundSender
A sender that isn’t bound to any client.
UnclaimedReceiver
A receiver that hasn’t been claimed yet by a client.
UnclaimedSender
A sender that hasn’t been claimed yet by a client.
UnknownCall
An unknown pending call.
UnknownEvent
An unknown event emitted by a service.

Enums§

DiscovererEventKind
Specifies whether an object was created or destroyed.

Derive Macros§

AsSerializeArg
Derive macro for the AsSerializeArg trait.
Deserialize
Derive macro for the Deserialize trait.
DeserializeKey
Derive macro for the DeserializeKey trait.
Introspectable
Derive macro for the Introspectable trait.
KeyTypeOf
Derive macro for the KeyTypeOf trait.
Serialize
Derive macro for the Serialize trait.
SerializeKey
Derive macro for the SerializeKey trait.