NNG_AIO_DEFER(3)

📦
version 1.12.0 · 4 versions
, in ubuntu stonking

💖 nng_aio_defer — defer asynchronous I/O operation 💖

okay bestie, so this page lives in the NNG Reference Manual (section 3, the library-call girlies) and it's literally all about nng_aio_defer. it's giving "I'm an I/O provider and I need a minute" energy. let's get into it 🦋

✨ SYNOPSIS ✨

#include <nng/nng.h>

typedef void (*nng_aio_cancelfn)(nng_aio *aio, void *arg, int err);

void nng_aio_defer(nng_aio *aio, nng_aio_cancelfn fn, void *arg);

like, copy that verbatim bestie, no cap 🔥

🌸 DESCRIPTION 🌸

so nng_aio_defer() does two things at once and honestly? multitasking queen 👑

it marks the operation associated with aio as being deferred for asynchronous completion — like, "not now, but soon, I promise" — and it also registers a cancellation function fn plus its associated argument arg, which is what makes it possible for the operation to be canceled at all.

if the aio is being canceled, the cancellation routine fn gets called, and it receives the aio, the arg you passed into nng_aio_defer(), and an error value in err. and err is the whole reason — it's why the operation is being canceled 💀

now, plot twist: the operation may not be cancelable. like, maybe it's already been completed, or it's in a state where it's no longer possible to unschedule it. in that case, the cancelfn should just... return. no changes, no edits, no drama. just vibes and an early return 🙈

if the cancellation routine did successfully cancel the operation, it should make sure that nng_aio_finish() gets called, using the error code specified by err. that part is not optional bestie 🫶

Important 💅 it is mandatory that I/O providers call nng_aio_finish() EXACTLY ONCE when they are finished with the operation. exactly once. not zero, not two, not "oops I forgot", not "I did it twice for good luck". EXACTLY ONCE. periodt.
Note 🎀 this function is only for I/O providers — the ones actually performing the operation, like HTTP handler functions or transport providers. ordinary users of the aio should not call this function. it's not for you, babe, it's for them.
Note 🧚 care must be taken to ensure that cancellation and completion of the routine are multi-thread safe. this will usually involve the use of locks or other synchronization primitives. yes, actual locks. yes, they're annoying. no, you can't skip them 😭
Tip ⭐ for operations that complete synchronously, with no need to be deferred at all, the provider should not bother to call nng_aio_defer() — although it is harmless if it does. so like, you can, but why would you. main character energy is knowing when to not do the thing 💜

🌈 RETURN VALUES 🌈

None. nothing. nada. the function returns void and simply does not have an opinion to share 💀

⭐ ERRORS ⭐

None. zero errors, zero drama, we love a low-maintenance function ✨

🦋 SEE ALSO 🦋

go read those too, they're the rest of the friend group 🫶

okay that's the whole page!! mwah 💖 this was pulled from the NNG Reference Manual and the version/date stamp on it is 2026-06-30 — so like, if you're reading this from the future, hi, hope the aios are behaving. slay, stay synchronized, and remember: nng_aio_finish() EXACTLY ONCE 👑💅🌸

📦 where this page comes from