NNG_RECV_AIO(3)

💌 nng_recv_aio(3) — bestie's guide to grabbing messages async

okay so this is a page from the NNG Reference Manual. yes THE nng manual. and today we're talking about nng_recv_aio — receiving messages, but make it ✨asynchronous✨. iykyk.

---

🌸 NAME 🌸

nng_recv_aio — receive message asynchronously ✨

---

🎀 SYNOPSIS 🎀

#include <nng/nng.h>

void nng_recv_aio(nng_socket s, nng_aio *aio);

like, that's it. two args. void return. she's simple, she's iconic.

---

🦋 DESCRIPTION 🦋

so the way that nng_recv_aio() works is: it receives a message using the socket s, but it does it asynchronously. no blocking, no waiting around, we're busy and booked.

when a message actually lands on the socket, it gets stashed in the aio — and the way that happens is an internal call that's equivalent to nng_aio_set_msg(). then the completion callback on the aio fires. and in this case nng_aio_result() returns zero 💚. the callback function is the one responsible for grabbing that message and disposing of it properly. that's on you, bestie.

⚠️ Important — not me being dramatic but: if you fail to accept and dispose of messages in this case, you can get memory leaks. like, actual leaks. your process will just be sitting there holding memory forever. no cap. dispose of your messages. periodt.

and listen — if for some reason the async receive cannot complete successfully (and yes that includes getting canceled, or timing out 😭), then the callback STILL gets executed. but nng_aio_result() will be non-zero. so check it!! always check it!!

📝 Note — the semantics of what "receiving a message" even means varies from protocol to protocol, so like, go read the protocol documentation, it's encouraged, it's giving homework but it's important. for example: with a pub socket the data is broadcast, so any peers who have a suitable subscription will be able to receive it using nng_recv() or a similar function. also some protocols may just straight up not support receiving (like pub, she doesn't do that) or may require other conditions. for example, req sockets cannot normally receive data (which are the replies to requests) until they have first sent a request. so like, order of operations matters, bestie.

---

💅 RETURN VALUES 💅

None. because the operation completes asynchronously. she doesn't return, she arrives. 💁♀️

---

💀 ERRORS 💀

these are the ways it can go wrong. know them. respect them.

• NNG_ECANCELED — the operation was aborted. she said no thank you 🙈
• NNG_ECLOSED — the socket s is not open. bestie the door is closed.
• NNG_ENOMEM — insufficient memory is available. the vibes are out of RAM 😭
• NNG_ENOTSUP — the protocol for socket s does not support receiving. not every protocol does recv, and that's okay, we don't shame.
• NNG_ESTATE — the socket s cannot receive data in this state. wrong place, wrong time fr fr.
• NNG_ETIMEDOUT — the receive timeout expired. clock ran out. ⏰

---

🔥 SEE ALSO 🔥

• nng_aio_get_msg(3)
• nng_aio_set_msg(3)
• nng_msg_alloc(3)
• nng_strerror(3)
• nng_aio(5)
• nng_msg(5)
• nng_socket(5)
• nng(7)

---

and that's the whole page bestie, every last option, every error, every cross-reference, untouched and immaculate 👑

mwah 💋 this was the NNG Reference Manual, dated 2026-06-30. go forth and dispose of your messages properly. slay. 🫶