Struct aldrin::Client

pub struct Client<T>
where
    T: AsyncTransport + Unpin,
{ /* private fields */ }

Aldrin client used to connect to a broker.

This is the first entry point to aldrin-client. A Client is used to establish a connection to an Aldrin broker. Afterwards, it should be turned into a Future with the run method, which must then be continuously polled and run to completion.

All interaction with a Client happens asynchronously through one or more Handles, which must be acquired with Client::handle before calling Client::run.

Shutdown

A Client will automatically shut down when the last Handle has been dropped. Keep in mind that several other types (such as e.g. Object) keep an internal Handle. Use Handle::shutdown to shut down the Client manually.

Implementations

impl<T> Client<T>

where T: AsyncTransport + Unpin,

pub async fn connect(t: T) -> Result<Self, ConnectError<T::Error>>

Creates a client and connects to an Aldrin broker.

If you need to send custom data to the broker, then use connect_with_data instead. This function sends () and discards the broker’s data.

After creating a client, it must be continuously polled and run to completion with the run method.

Examples

use aldrin::Client;

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

pub async fn connect_with_data<D: Serialize + ?Sized>( t: T, data: &D ) -> Result<(Self, SerializedValue), ConnectError<T::Error>>

Creates a client and connects to an Aldrin broker. Allows to send and receive custom data.

After creating a client, it must be continuously polled and run to completion with the run method.

pub async fn connect_with_data_and_deserialize<D1, D2>( t: T, data: &D1 ) -> Result<(Self, D2), ConnectError<T::Error>>

where D1: Serialize + ?Sized, D2: Deserialize,

Creates a client and connects to an Aldrin broker. Allows to send and receive custom data.

After creating a client, it must be continuously polled and run to completion with the run method.

Examples

use aldrin::Client;

// Create an AsyncTransport for connecting to the broker.
// let async_transport = ...

// Connect to the broker, sending some custom data.
let (client, data) = Client::connect_with_data(async_transport, "Hi!").await?;

println!("Data the broker sent back: {:?}.", data);

pub fn handle(&self) -> &Handle

Returns a handle to the client.

After creating the Client, Handles are the primary entry point for interacting with it.

When the last Handle is dropped, the Client will automatically shut down.

pub async fn run(self) -> Result<(), RunError<T::Error>>

Runs the client until it shuts down.

After creating a Client it is important to run it before calling any method on a Handle.

This is a long running method, that will only complete once the Client has shut down. It should ideally be spawned on a dedicated task (not for performance or technical reasons, but for ergonomics).

Shutdown

A running Client can be shut down manually with Handle::shutdown. It will also automatically shut down when the last Handle has been dropped. Be aware, that some types (such as e.g. Service) hold an internal Handle and will thus keep the Client running. Clients can also be instructed by the broker to shut down.

Trait Implementations

impl<T> Debug for Client<T>

where T: AsyncTransport + Unpin + Debug,

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

Formats the value using the given formatter.

impl<T> Drop for Client<T>

where T: AsyncTransport + Unpin,

fn drop(&mut self)

Executes the destructor for this type.