Struct AsyncClient 

pub struct AsyncClient { /* private fields */ }

An asynchronous client, communicates with MQTT EventLoop.

This is cloneable and can be used to asynchronously publish, subscribe through the EventLoop, which is to be polled parallelly.

NOTE: The EventLoop must be regularly polled in order to send, receive and process packets from the broker, i.e. move ahead.

Bounded clients apply backpressure through the client request channel. If the same task that drives EventLoop::poll awaits request-sending APIs such as publish, subscribe, unsubscribe, or ack while that channel is full, it can self-block: the send is waiting for the event loop to read a request, but the event loop cannot make progress until that same task polls it again. For bounded async clients, prefer driving the event loop in a dedicated task. Use try_publish when dropping outgoing publishes under overload is intended.

The request channel is an admission queue, not a strict global wire FIFO guarantee. Under publish flow-control pressure, non-PUBLISH control packets can pass earlier QoS 1/ QoS 2 publishes that are not currently sendable. Application publishes preserve FIFO with other publishes.

Implementations

impl AsyncClient

pub const fn builder(options: MqttOptions) -> AsyncClientBuilder

Create a builder for an AsyncClient.

The returned AsyncClientBuilder only builds the asynchronous client pair, which keeps the terminal build() method aligned with this entry point.

pub const fn from_senders(request_tx: Sender<Request>) -> Self

Create a new AsyncClient from a channel Sender.

This is mostly useful for creating a test instance where you can listen on the corresponding receiver.

pub async fn publish<T, V>( &self, topic: T, qos: QoS, retain: bool, payload: V, ) -> Result<(), ClientError>

where T: Into<PublishTopic>, V: Into<Vec<u8>>,

Sends a MQTT Publish to the EventLoop.

Errors

Returns an error if the topic is invalid or if the request cannot be queued on the event loop.

pub async fn publish_tracked<T, V>( &self, topic: T, qos: QoS, retain: bool, payload: V, ) -> Result<PublishNotice, ClientError>

where T: Into<PublishTopic>, V: Into<Vec<u8>>,

Sends a MQTT Publish to the EventLoop and returns a notice which resolves on MQTT ack milestone.

Errors

Returns an error if the topic is invalid or if the request cannot be queued on the event loop.

pub fn try_publish<T, V>( &self, topic: T, qos: QoS, retain: bool, payload: V, ) -> Result<(), ClientError>

where T: Into<PublishTopic>, V: Into<Vec<u8>>,

Attempts to send a MQTT Publish to the EventLoop.

This is the non-blocking publish API for overload policies that may drop outgoing publishes. If the bounded request channel is full, this returns an error immediately and the publish has not been queued.

Errors

Returns an error if the topic is invalid or if the request cannot be queued immediately on the event loop.

pub fn try_publish_tracked<T, V>( &self, topic: T, qos: QoS, retain: bool, payload: V, ) -> Result<PublishNotice, ClientError>

where T: Into<PublishTopic>, V: Into<Vec<u8>>,

Attempts to send a MQTT Publish to the EventLoop and returns a notice.

This is the non-blocking tracked publish API for overload policies that may drop outgoing publishes. If the bounded request channel is full, this returns an error immediately and the publish has not been queued.

Errors

Returns an error if the topic is invalid or if the request cannot be queued immediately on the event loop.

pub const fn prepare_ack(&self, publish: &Publish) -> Option<ManualAck>

Prepares a MQTT PubAck/PubRec packet for manual acknowledgement.

Returns None for QoS0 publishes, which do not require acknowledgement.

pub async fn manual_ack(&self, ack: ManualAck) -> Result<(), ClientError>

Sends a prepared MQTT PubAck/PubRec to the EventLoop.

This is useful when manual_acks is enabled and acknowledgement must be deferred.

Errors

Returns an error if the acknowledgement cannot be queued on the event loop.

pub fn try_manual_ack(&self, ack: ManualAck) -> Result<(), ClientError>

Attempts to send a prepared MQTT PubAck/PubRec to the EventLoop.

Errors

Returns an error if the acknowledgement cannot be queued immediately on the event loop.

pub async fn ack(&self, publish: &Publish) -> Result<(), ClientError>

Sends a MQTT PubAck/PubRec to the EventLoop based on publish QoS. Only needed if the manual_acks flag is set.

Errors

Returns an error if the derived acknowledgement cannot be queued on the event loop.

pub fn try_ack(&self, publish: &Publish) -> Result<(), ClientError>

Attempts to send a MQTT PubAck/PubRec to the EventLoop based on publish QoS. Only needed if the manual_acks flag is set.

Errors

Returns an error if the derived acknowledgement cannot be queued immediately on the event loop.

pub async fn publish_bytes<T>( &self, topic: T, qos: QoS, retain: bool, payload: Bytes, ) -> Result<(), ClientError>

where T: Into<PublishTopic>,

Sends a MQTT Publish to the EventLoop

Errors

Returns an error if the topic is invalid or if the request cannot be queued on the event loop.

pub async fn publish_bytes_tracked<T>( &self, topic: T, qos: QoS, retain: bool, payload: Bytes, ) -> Result<PublishNotice, ClientError>

where T: Into<PublishTopic>,

Sends a MQTT Publish with Bytes payload and returns a tracked notice.

Errors

Returns an error if the topic is invalid or if the request cannot be queued on the event loop.

pub async fn subscribe<S: Into<String>>( &self, topic: S, qos: QoS, ) -> Result<(), ClientError>

Sends a MQTT Subscribe to the EventLoop

Errors

Returns an error if the topic filter is invalid or if the request cannot be queued on the event loop.

pub async fn subscribe_tracked<S: Into<String>>( &self, topic: S, qos: QoS, ) -> Result<SubscribeNotice, ClientError>

Sends a tracked MQTT Subscribe to the EventLoop.

Errors

Returns an error if the topic filter is invalid or if the request cannot be queued on the event loop.

pub fn try_subscribe<S: Into<String>>( &self, topic: S, qos: QoS, ) -> Result<(), ClientError>

Attempts to send a MQTT Subscribe to the EventLoop

Errors

Returns an error if the topic filter is invalid or if the request cannot be queued immediately on the event loop.

pub fn try_subscribe_tracked<S: Into<String>>( &self, topic: S, qos: QoS, ) -> Result<SubscribeNotice, ClientError>

Attempts to send a tracked MQTT Subscribe to the EventLoop.

Errors

Returns an error if the topic filter is invalid or if the request cannot be queued immediately on the event loop.

pub async fn subscribe_many<T>(&self, topics: T) -> Result<(), ClientError>

where T: IntoIterator<Item = SubscribeFilter>,

Sends a MQTT Subscribe for multiple topics to the EventLoop

Errors

Returns an error if the filter list is invalid or if the request cannot be queued on the event loop.

pub async fn subscribe_many_tracked<T>( &self, topics: T, ) -> Result<SubscribeNotice, ClientError>

where T: IntoIterator<Item = SubscribeFilter>,

Sends a tracked MQTT Subscribe for multiple topics to the EventLoop.

Errors

Returns an error if the filter list is invalid or if the request cannot be queued on the event loop.

pub fn try_subscribe_many<T>(&self, topics: T) -> Result<(), ClientError>

where T: IntoIterator<Item = SubscribeFilter>,

Attempts to send a MQTT Subscribe for multiple topics to the EventLoop

Errors

Returns an error if the filter list is invalid or if the request cannot be queued immediately on the event loop.

pub fn try_subscribe_many_tracked<T>( &self, topics: T, ) -> Result<SubscribeNotice, ClientError>

where T: IntoIterator<Item = SubscribeFilter>,

Attempts to send a tracked MQTT Subscribe for multiple topics to the EventLoop.

Errors

Returns an error if the filter list is invalid or if the request cannot be queued immediately on the event loop.

pub async fn unsubscribe<S: Into<String>>( &self, topic: S, ) -> Result<(), ClientError>

Sends a MQTT Unsubscribe to the EventLoop

Errors

Returns an error if the request cannot be queued on the event loop.

pub async fn unsubscribe_tracked<S: Into<String>>( &self, topic: S, ) -> Result<UnsubscribeNotice, ClientError>

Sends a tracked MQTT Unsubscribe to the EventLoop.

Errors

Returns an error if the request cannot be queued on the event loop.

pub fn try_unsubscribe<S: Into<String>>( &self, topic: S, ) -> Result<(), ClientError>

Attempts to send a MQTT Unsubscribe to the EventLoop

Errors

Returns an error if the request cannot be queued immediately on the event loop.

pub fn try_unsubscribe_tracked<S: Into<String>>( &self, topic: S, ) -> Result<UnsubscribeNotice, ClientError>

Attempts to send a tracked MQTT Unsubscribe to the EventLoop.

Errors

Returns an error if the request cannot be queued immediately on the event loop.

pub async fn disconnect(&self) -> Result<(), ClientError>

Queues a graceful MQTT disconnect barrier.

Once the event loop observes this request, it stops processing later application work, flushes previously accepted QoS 0 publishes, and waits for previously accepted outbound QoS 1/ QoS 2 publishes and tracked subscribe/unsubscribe requests to complete. QoS 1 publishes complete on PUBACK, QoS 2 publishes complete on PUBCOMP, tracked subscribes complete on SUBACK, and tracked unsubscribes complete on UNSUBACK. It then sends and flushes MQTT DISCONNECT.

This request uses the normal client request channel. Under publish flow-control pressure, it may pass earlier QoS 1/ QoS 2 publishes that are not currently sendable; once observed, it becomes the graceful drain barrier.

Errors

Returns an error if the disconnect request cannot be queued on the event loop.

pub async fn disconnect_with_timeout( &self, timeout: Duration, ) -> Result<(), ClientError>

Queues a graceful MQTT disconnect barrier with a drain timeout.

Once the event loop observes this request, it stops processing later application work, flushes previously accepted QoS 0 publishes, and waits up to timeout for previously accepted outbound QoS 1/ QoS 2 publishes and tracked subscribe/unsubscribe requests to complete. QoS 1 publishes complete on PUBACK, QoS 2 publishes complete on PUBCOMP, tracked subscribes complete on SUBACK, and tracked unsubscribes complete on UNSUBACK.

If the drain completes before the deadline, the event loop sends and flushes MQTT DISCONNECT. If the deadline expires first, polling returns ConnectionError::DisconnectTimeout and MQTT DISCONNECT is not sent.

This request uses the normal client request channel. The timeout starts only after the event loop observes this request, not necessarily when this method queues it.

Errors

Returns an error if the disconnect request cannot be queued on the event loop.

pub async fn disconnect_now(&self) -> Result<(), ClientError>

Sends a MQTT disconnect immediately without waiting for in-flight requests.

This request uses a dedicated immediate shutdown channel, not the normal application request channel. It may bypass queued application work and does not wait for unresolved QoS 1/ QoS 2 publish handshakes.

Errors

Returns an error if the disconnect request cannot be queued on the event loop.

pub fn try_disconnect(&self) -> Result<(), ClientError>

Attempts to queue a graceful MQTT disconnect barrier.

Once the event loop observes this request, it stops processing later application work, flushes previously accepted QoS 0 publishes, and waits for previously accepted outbound QoS 1/ QoS 2 publishes and tracked subscribe/unsubscribe requests to complete before sending MQTT DISCONNECT.

This request uses the normal client request channel. Under publish flow-control pressure, it may pass earlier QoS 1/ QoS 2 publishes that are not currently sendable; once observed, it becomes the graceful drain barrier.

Errors

Returns an error if the disconnect request cannot be queued immediately on the event loop.

pub fn try_disconnect_with_timeout( &self, timeout: Duration, ) -> Result<(), ClientError>

Attempts to queue a graceful MQTT disconnect with a drain timeout.

Once the event loop observes this request, it stops processing later application work, flushes previously accepted QoS 0 publishes, and waits up to timeout for previously accepted outbound QoS 1/ QoS 2 publishes and tracked subscribe/unsubscribe requests to complete. QoS 1 publishes complete on PUBACK, QoS 2 publishes complete on PUBCOMP, tracked subscribes complete on SUBACK, and tracked unsubscribes complete on UNSUBACK.

If the drain completes before the deadline, the event loop sends and flushes MQTT DISCONNECT. If the deadline expires first, polling returns ConnectionError::DisconnectTimeout and MQTT DISCONNECT is not sent.

This request uses the normal client request channel. The timeout starts only after the event loop observes this request, not necessarily when this method queues it.

Errors

Returns an error if the disconnect request cannot be queued immediately on the event loop.

pub fn try_disconnect_now(&self) -> Result<(), ClientError>

Attempts to queue an immediate MQTT disconnect.

This request uses a dedicated immediate shutdown channel, not the normal application request channel. It may bypass queued application work and does not wait for unresolved QoS 1/ QoS 2 publish handshakes.

Errors

Returns an error if the disconnect request cannot be queued immediately on the event loop.

Trait Implementations

impl Clone for AsyncClient

fn clone(&self) -> AsyncClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AsyncClient

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

Formats the value using the given formatter.