Struct aldrin_broker::BrokerHandle

source ·

pub struct BrokerHandle { /* private fields */ }

Expand description

Handle of an active broker.

BrokerHandles are used to interact with an active Broker. The first BrokerHandle can be acquired from the Broker with handle, and from then on, BrokerHandles can be cloned cheaply.

The Broker will automatically shut down when the last BrokerHandle has been dropped and while there are no active clients.

Implementations§

source §

impl BrokerHandle

source

pub async fn connect<T>( &mut self, t: T ) -> Result<Connection<T>, EstablishError<T::Error>>
where T: AsyncTransport + Unpin,

Establishes a new connection.

This method performs the initial connection setup and Aldrin handshake between broker and client. If successful, the resulting Connection must be run and polled to completion, much like the Broker itself.

The Aldrin protocol allows client and broker to exchange custom data during the handshake. This function will ignore the client’s data and send () back. If you need to inspect the data and possibly reject some clients, then use begin_connect.

Examples

// Create an AsyncTransport to a new incoming connection:
// let t = ...

// Establish a connection to the client:
let connection = broker_handle.connect(t).await?;

// Run the connection:
tokio::spawn(connection.run());

// The connection is now active and the client is fully connected.

source

pub async fn begin_connect<T>( &mut self, t: T ) -> Result<PendingConnection<T>, EstablishError<T::Error>>
where T: AsyncTransport + Unpin,

Begins establishing a new connection.

Unlike connect, this function will not automatically establish a connection. It will only receive the client’s initial connection message. This allows you to inspect the client’s custom data and accept or reject the client.

source

pub async fn shutdown(&mut self)

Shuts down the broker.

This method informs the Broker that it should initiate shutdown, but doesn’t block until Broker has done so. The Broker will cleanly shut down all connections, before the Broker::run returns.

Examples

use aldrin_broker::Broker;

let broker = Broker::new();
let mut handle = broker.handle().clone();
let join = tokio::spawn(broker.run());

// Tell the broker to shutdown:
handle.shutdown().await;

// `run` will return as soon as all connections have been shut down:
join.await?;

source

pub async fn shutdown_idle(&mut self)

Shuts down the broker when the last client disconnects.

This method informs the Broker that it should shutdown as soon as there are no active clients left.

Calling this method does not prevent new connections. It also doesn’t actively tell the connected clients to shut down.

Examples

use aldrin_broker::Broker;

let broker = Broker::new();
let mut handle = broker.handle().clone();
let join = tokio::spawn(broker.run());

// Tell the broker to shutdown when it becomes idle:
handle.shutdown_idle().await;

// `run` will return as soon as the last client disconnects:
join.await?;

source

pub async fn shutdown_connection( &mut self, conn: &ConnectionHandle ) -> Result<(), BrokerShutdown>

Shuts down a specific connection.

Similar to the other shutdown methods, this method will only initiate shutdown of the Connection specified by conn and then return before it has actually shut down.

Examples

// Create an AsyncTransport to a new incoming connection:
// let t = ...

// Establish a connection to the client:
let connection = broker_handle.connect(t).await?;

// Get a handle to the connection:
let connection_handle = connection.handle().clone();

// Run the connection:
let connection_join = tokio::spawn(connection.run());

// Tell the broker to shut down the connection again:
broker_handle.shutdown_connection(&connection_handle).await?;
connection_join.await??;

source

pub async fn take_statistics( &mut self ) -> Result<BrokerStatistics, BrokerShutdown>

Gets the current broker statistics.

Some statistics are measured over the time interval between two calls to this function. Such statistics will be reset to 0 when this function is called.

Examples

let statistics = broker_handle.take_statistics().await?;

// Calculate the duration over which the statistics were measured.
let time_diff = statistics.end - statistics.start;

println!("The current number of connections is {}.", statistics.num_connections);
println!(
    "{} connections were added within the last {} seconds.",
    statistics.connections_added,
    time_diff.as_secs_f32()
);