pub struct Client<T>where
T: AsyncTransport + Unpin,{ /* private fields */ }
Expand description
Aldrin client used to connect to a broker.
This is the first entry point to Aldrin. 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
Handle
s, 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§
source§impl<T> Client<T>where
T: AsyncTransport + Unpin,
impl<T> Client<T>where
T: AsyncTransport + Unpin,
sourcepub async fn connect(t: T) -> Result<Self, ConnectError<T::Error>>
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??;
sourcepub async fn connect_with_data<D: Serialize + ?Sized>(
t: T,
data: Option<&D>,
) -> Result<(Self, Option<SerializedValue>), ConnectError<T::Error>>
pub async fn connect_with_data<D: Serialize + ?Sized>( t: T, data: Option<&D>, ) -> Result<(Self, Option<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.
sourcepub async fn connect_with_data_and_deserialize<D1, D2>(
t: T,
data: Option<&D1>,
) -> Result<(Self, Option<D2>), ConnectError<T::Error>>
pub async fn connect_with_data_and_deserialize<D1, D2>( t: T, data: Option<&D1>, ) -> Result<(Self, Option<D2>), 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.
§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, Some("Hi!")).await?;
println!("Data the broker sent back: {:?}.", data);
sourcepub fn protocol_version(self) -> ProtocolVersion
pub fn protocol_version(self) -> ProtocolVersion
Returns the protocol version that was negotiated with the broker.
sourcepub async fn run(self) -> Result<(), RunError<T::Error>>
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. Client
s can also be instructed by the broker to shut down.