async(3)

✨ NAME ✨

async — asynchronous vs synchronous client applications, aka the two whole moods this client library can be in 💅

---

okay so bestie, listen. This client library supports two modes of operation, and they are literally called synchronous and asynchronous mode. That's it, that's the lore. 🦋

How do you get sorted into one? It's one call, no sorting hat needed: if your application calls MQTTClient_setCallbacks(), boom, you're in asynchronous mode. If it doesn't? You're in synchronous mode. That's the whole vibe check. ✨

---

synchronous mode is the chill single-lane one. Your client application runs on a single thread. One thread, one queen, one job.

Messages get published with the MQTTClient_publish() and MQTTClient_publishMessage() functions. Cool cool cool.

Now the part you can NOT skip: to determine that a QoS1 or QoS2 message (go peep Quality of service) has been successfully delivered, your application must call the MQTTClient_waitForCompletion() function. There's an example of this whole thing in Synchronous publication example if you wanna see it living its life.

Receiving messages in synchronous mode is MQTTClient_receive()'s moment. 👑

⚠️ and this is the one that gets people: client applications must call either MQTTClient_receive() or MQTTClient_yield() relatively frequently, because that's how acknowledgements get processed and how the MQTT "pings" happen — you know, the pings that keep the network connection to the server alive. Ignore them and the connection just… leaves. no cap. 💀

---

asynchronous mode is the multithreaded main-character era. Your client application runs on several threads. The main program still calls functions in the client library to publish and subscribe, exactly like in synchronous mode — that part didn't change, bestie.

What did change: processing of handshaking and maintaining the network connection happens in the background. Like a little gremlin doing chores while you live your life. 🧚

Status notifications and message reception get delivered to your client application through callbacks that you registered with the library when you called MQTTClient_setCallbacks(). The callback girlies are:

• MQTTClient_messageArrived()
• MQTTClient_connectionLost()
• MQTTClient_deliveryComplete()

💀 BUT. This API is not thread safe. Like, genuinely — it is not possible to call it from multiple threads without synchronization. Don't try it, it's giving chaos. If you need that multithreaded energy, you use the MQTTAsync API for that. iykyk.

---

and that's the whole page, bestie 🫶 go be the main character of your own network connection. 🌸

this lil manual page is brought to you by the Paho MQTT C Client Library, stamped Tue Jun 2 2026 00:00:00, and yes it's still async(3) 💖✨