Aio moved

16 files changed, 720 insertions, 0 deletions

diff --git a/docs/reference/src/aio/index.md b/docs/reference/src/aio/index.md
new file mode 100644
index 00000000..665a91e3
--- /dev/null
+++ b/docs/reference/src/aio/index.md
@@ -0,0 +1,76 @@
+# Aysnchronous I/O
+
+_NNG_ provides rich support for {{i:asynchronous I/O}}.
+This allows applications to achieve high levels of concurrency with a
+minimum of fuss, optimized for the platform.
+
+Asynchronous I/O is performed without blocking calling application
+threads, so they may continue to perform other work.
+
+## AIO Handles
+
+Applications create an `nng_aio` object with a function to call when
+the operation is done (along with a pointer to application private data),
+then submit the operation.
+
+These `nng_aio` objects are created using the [`nng_aio_alloc()`][nng_aio_alloc],
+and destroyed using [`nng_aio_free()`][nng_aio_free].
+
+The `nng_aio` object itself is declared like this:
+
+```c
+#include <nng/nng.h>
+
+typedef struct nng_aio nng_aio;
+```
+
+Every asynchronous operation uses its own instance an `nng_aio`, and each
+`nng_aio` can only be used with a single operation at a time.
+
+> [!IMPORTANT]
+> Attempting to submit an operation using an `nng_aio` that is already
+> in use for another operation will crash the application.
+> However, it is possible to submit another operation on the `nng_aio` from
+> the callback associated with the same `nng_aio`.
+
+When the operation is complete, whether successfully
+or otherwise, the callback function is executed.
+The callback will be executed exactly once.
+
+## Cancellation
+
+The asynchronous I/O framework also supports cancellation of
+operations that are already in progress
+(see [`nng_aio_cancel()`][nng_aio_cancel]), as well setting a maximum
+timeout for them to complete within
+(see [`nng_aio_set_timeout()`][nng_aio_set_timeout]).
+
+## Waiting for Completion
+
+It is also possible to initiate an asynchronous operation, and wait for it to
+complete [`nng_aio_wait()`][nng_aio_wait].
+
+> [!IMPORTANT]
+> Applications must never call [`nng_aio_wait()`][nng_aio_wait] or
+> [`nng_aio_stop()`][nng_aio_stop] from a callback registered to
+> an `nng_aio` object. Doing so can lead to a deadlock.
+
+## See Also
+
+[nng_aio_abort][nng_aio_abort],
+[nng_aio_alloc][nng_aio_alloc],
+[nng_aio_cancel][nng_aio_cancel],
+[nng_aio_count][nng_aio_count],
+[nng_aio_free][nng_aio_free],
+[nng_aio_get_input][nng_aio_get_input],
+[nng_aio_get_msg][nng_aio_get_msg],
+[nng_aio_get_output][nng_aio_get_output],
+[nng_aio_result][nng_aio_result],
+[nng_aio_set_input][nng_aio_set_input],
+[nng_aio_set_iov][nng_aio_set_iov],
+[nng_aio_set_msg][nng_aio_set_msg],
+[nng_aio_set_timeout][nng_aio_set_timeout],
+[nng_aio_stop][nng_aio_stop],
+[nng_aio_wait][nng_aio_wait]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_abort.md b/docs/reference/src/aio/nng_aio_abort.md
new file mode 100644
index 00000000..74804a5c
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_abort.md
@@ -0,0 +1,37 @@
+# nng_aio_abort
+
+## NAME
+
+nng_aio_abort --- abort asynchronous I/O operation
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void nng_aio_abort(nng_aio *aio, int err);
+```
+
+## DESCRIPTION
+
+The `nng_aio_abort()` function aborts an operation previously started
+with the handle _aio_.
+If the operation is aborted, then the callback
+for the handle will be called, and the function
+[`nng_aio_result()`][nng_aio_result]
+will return the error _err_.
+
+This function does not wait for the operation to be fully aborted, but
+returns immediately.
+
+If no operation is currently in progress (either because it has already
+finished, or no operation has been started yet), then this function
+has no effect.
+
+## SEE ALSO
+
+[nng_aio_alloc][nng_aio_alloc],
+[nng_aio_cancel][nng_aio_cancel],
+[nng_aio_result][nng_aio_result]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_alloc.md b/docs/reference/src/aio/nng_aio_alloc.md
new file mode 100644
index 00000000..988f4bf2
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_alloc.md
@@ -0,0 +1,75 @@
+# nng_aio_alloc
+
+## NAME
+
+nng_aio_alloc --- allocate asynchronous I/O handle
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+int nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg);
+```
+
+## DESCRIPTION
+
+The `nng_aio_alloc()` function allocates a handle for {{i:asynchronous I/O}}
+operations, and stores a pointer to it in the location referenced by _aiop_.
+The handle is initialized with a completion {{i:callback}} of _callb_,
+which will be executed when an associated asynchronous operation finishes.
+It will be called with the argument _arg_.
+
+> [!IMPORTANT]
+> The callback _callb_ must not perform any blocking operations, and
+> must complete its execution quickly. If _callb_ does block, this can
+> lead ultimately to an apparent "hang" or deadlock in the application.
+> This also means you should avoid operations such as allocating new objects,
+> which also means opening or closing sockets, dialers, and so forth.
+
+> [!TIP]
+> If more complex or blocking work needs to be performed by _callb_, a separate
+> thread can be used, along with a [condition variable][nng_cv_alloc]
+> which can be signaled by the callback.
+
+Asynchronous I/O operations all take an [`nng_aio`](index.md)
+handle such as allocated by this function.
+Such operations are usually started by a function that returns immediately.
+The operation is then run asynchronously, and completes sometime later.
+When that operation is complete, the callback supplied here is called,
+and that callback is able to determine the result of the operation using
+[`nng_aio_result()`][nng_aio_result], [`nng_aio_count()`][nng_aio_count],
+and [`nng_aio_get_output()`][nng_aio_get_output].
+
+It is possible to wait synchronously for an otherwise asynchronous operation
+by using the function [`nng_aio_wait()`][nng_aio_wait].
+In that case, it is permissible for _callb_ and _arg_ to both be `NULL`.
+Note that if these are `NULL`, then it will not be possible to determine when the
+operation is complete except by calling the aforementioned
+[`nng_aio_wait()`][nng_aio_wait].
+
+## RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+## ERRORS
+
+- `NNG_ENOMEM`: Insufficient free memory to perform the operation.
+
+## SEE ALSO
+
+[nng_aio_abort][nng_aio_abort],
+[nng_aio_cancel][nng_aio_cancel],
+[nng_aio_count][nng_aio_count],
+[nng_aio_free][nng_aio_free],
+[nng_aio_get_msg][nng_aio_get_msg],
+[nng_aio_get_output][nng_aio_get_output],
+[nng_aio_result][nng_aio_result],
+[nng_aio_set_input][nng_aio_set_input],
+[nng_aio_set_iov][nng_aio_set_iov],
+[nng_aio_set_msg][nng_aio_set_msg],
+[nng_aio_set_timeout][nng_aio_set_timeout],
+[nng_aio_stop][nng_aio_stop],
+[nng_aio_wait][nng_aio_wait]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_busy.md b/docs/reference/src/aio/nng_aio_busy.md
new file mode 100644
index 00000000..7aef17fb
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_busy.md
@@ -0,0 +1,43 @@
+# nng_aio_busy
+
+## NAME
+
+nng_aio_busy --- test if asynchronous I/O is busy
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+bool nng_aio_busy(nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_aio_busy()` function returns true if the
+_aio_ is currently busy performing an asynchronous I/O
+operation or is executing a completion callback.
+
+If no operation has been started, or the operation has
+been completed or canceled, and any callback has been
+executed, then it returns false.
+
+This is the same test used internally by
+[`nng_aio_wait()`][nng_aio_wait].
+
+> [!IMPORTANT]
+> Care should be taken to ensure that the _aio_ object is not
+> freed when using this function. The caller is responsible for
+> coordinating any use of this with any reuse of the _aio_.
+
+## RETURN VALUES
+
+True if the _aio_ is busy, false otherwise.
+
+## SEE ALSO
+
+[nng_aio_abort][nng_aio_abort],
+[nng_aio_alloc][nng_aio_alloc],
+[nng_aio_wait][nng_aio_wait]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_cancel.md b/docs/reference/src/aio/nng_aio_cancel.md
new file mode 100644
index 00000000..e3b53d93
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_cancel.md
@@ -0,0 +1,39 @@
+# nng_aio_cancel
+
+## NAME
+
+nng_aio_cancel --- cancel asynchronous I/O operation
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void nng_aio_cancel(nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_aio_cancel()` function aborts an operation previously started
+with the handle _aio_.
+If the operation is aborted, then the callback
+for the handle will be called, and the function
+[`nng_aio_result()`][nng_aio_result] will return the error `NNG_ECANCELED`.
+
+This function does not wait for the operation to be fully aborted, but
+returns immediately.
+
+If no operation is currently in progress (either because it has already
+finished, or no operation has been started yet), then this function
+has no effect.
+
+This function is the same as calling
+[`nng_aio_abort()`][nng_aio_abort] with the error `NNG_ECANCELED`.
+
+## SEE ALSO
+
+[nng_aio_abort][nng_aio_abort],
+[nng_aio_alloc][nng_aio_alloc],
+[nng_aio_result][nng_aio_result]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_count.md b/docs/reference/src/aio/nng_aio_count.md
new file mode 100644
index 00000000..1bd06e94
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_count.md
@@ -0,0 +1,46 @@
+# nng_aio_count
+
+## NAME
+
+nng_aio_count --- return number of bytes transferred
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+size_t nng_aio_count(nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_aio_count()` returns the number of bytes transferred by the
+asynchronous operation associated with the handle _aio_.
+
+Some asynchronous operations do not provide meaningful data for this
+function; for example operations that establish connections do not
+transfer user data (they may transfer protocol data though) -- in this case
+this function will generally return zero.
+
+This function is most useful when used with operations that make use of
+of a scatter/gather vector (set by [`nng_aio_set_iov()`][nng_aio_set_iov]).
+
+> [!NOTE]
+> The return value from this function is undefined if the operation
+> has not completed yet.
+> Either call this from the handle's completion callback,
+> or after waiting for the operation to complete with
+> [`nng_aio_wait()`][nng_aio_wait].
+
+## RETURN VALUES
+
+The number of bytes transferred by the operation.
+
+## SEE ALSO
+
+[nng_aio_alloc][nng_aio_alloc],
+[nng_aio_result][nng_aio_result],
+[nng_aio_set_iov][nng_aio_set_iov],
+[nng_aio_wait][nng_aio_wait]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_free.md b/docs/reference/src/aio/nng_aio_free.md
new file mode 100644
index 00000000..500ec2a6
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_free.md
@@ -0,0 +1,36 @@
+# nng_aio_free
+
+## NAME
+
+nng_aio_free --- free asynchronous I/O handle
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void nng_aio_free(nng_aio *aio);
+void nng_aio_reap(nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_aio_free()` function frees an allocated asynchronous I/O handle.
+If any operation is in progress, the operation is canceled, and the
+caller is blocked until the operation is completely canceled, to ensure
+that it is safe to deallocate the handle and any associated resources.
+(This is done by implicitly calling [`nng_aio_stop()`][nng_aio_stop].)
+
+The `nng_aio_reap()` function is the same as `nng_aio_free()`, but does
+its work in a background thread.
+This can be useful to discard the _aio_ object from within the callback for the _aio_.
+
+> [!IMPORTANT]
+> Once either of these functions are called, the _aio_ object is invalid and must not be used again.
+
+## SEE ALSO
+
+[nng_aio_alloc][nng_aio_alloc],
+[nng_aio_stop][nng_aio_stop]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_get_msg.md b/docs/reference/src/aio/nng_aio_get_msg.md
new file mode 100644
index 00000000..33b07981
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_get_msg.md
@@ -0,0 +1,32 @@
+# nng_aio_get_msg
+
+## NAME
+
+nng_aio_get_msg --- get message from asynchronous receive
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+nng_msg *nng_aio_get_msg(nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_aio_get_msg()` function gets any message stored in _aio_ as
+either a result of a successful receive
+(see [`nng_recv_aio()`][nng_recv_aio])
+or that was previously stored with
+[`nng_aio_set_msg()`][nng_aio_set_msg].
+
+> [!IMPORTANT]
+> The _aio_ must not have an operation in progress.
+
+## SEE ALSO
+
+[nng_aio_set_msg][nng_aio_set_msg],
+[nng_recv_aio][nng_recv_aio],
+[Messages][msg]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_get_output.md b/docs/reference/src/aio/nng_aio_get_output.md
new file mode 100644
index 00000000..a7a82f56
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_get_output.md
@@ -0,0 +1,42 @@
+# nng_aio_get_output
+
+## NAME
+
+nng_aio_get_output --- return output result
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void *nng_aio_get_output(nng_aio *aio, unsigned int index);
+```
+
+## DESCRIPTION
+
+The `nng_aio_get_output()` function returns the output result at _index_
+resulting from the asynchronous operation associated with _aio_.
+
+The type and semantics of output parameters are determined by specific
+operations.
+
+> [!NOTE]
+> If the _index_ does not correspond to a defined output for the operation,
+> or the operation did not succeed, then the return value will be `NULL`.
+
+> [!IMPORTANT]
+> It is an error to call this function while the _aio_ is currently
+> in use by an active asynchronous operation, or if no operation has been
+> performed using the _aio_ yet.
+
+## RETURN VALUES
+
+The *index*th output from the operation, or `NULL`.
+
+## SEE ALSO
+
+[nng_aio_alloc][nng_aio_alloc],
+[nng_aio_set_output](../aio_provider/nng_aio_set_output.md),
+[nng_aio_result][nng_aio_result]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_result.md b/docs/reference/src/aio/nng_aio_result.md
new file mode 100644
index 00000000..16cede6a
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_result.md
@@ -0,0 +1,48 @@
+# nng_aio_result
+
+## NAME
+
+nng_aio_result --- return result of asynchronous operation
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+int nng_aio_result(nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_aio_result()` returns the result of the operation associated
+with the handle _aio_.
+If the operation was successful, then 0 is returned.
+Otherwise a non-zero error code is returned.
+
+> [!NOTE]
+> The return value from this function is undefined if the operation
+> has not completed yet.
+> Either call this from the handle's completion
+> callback, or after waiting for the operation to complete with
+> [`nng_aio_wait()`][nng_aio_wait].
+
+## RETURN VALUES
+
+The result of the operation, either zero on success, or an error
+number on failure.
+
+## ERRORS
+
+- `NNG_ETIMEDOUT`: The operation timed out.
+- `NNG_ECANCELED`: The operation was canceled.
+
+Various other return values are possible depending on the operation.
+
+## SEE ALSO
+
+[nng_aio_abort][nng_aio_abort],
+[nng_aio_alloc][nng_aio_alloc],
+[nng_aio_wait][nng_aio_wait],
+[nng_strerror](../util/nng_strerror.md)
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_set_input.md b/docs/reference/src/aio/nng_aio_set_input.md
new file mode 100644
index 00000000..d09ba05f
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_set_input.md
@@ -0,0 +1,44 @@
+# nng_aio_set_input
+
+## NAME
+
+nng_aio_set_input --- set input parameter
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param);
+```
+
+## DESCRIPTION
+
+The `nng_aio_set_input()` function sets the input parameter at _index_
+to _param_ for the asynchronous operation associated with _aio_.
+
+The type and semantics of input parameters are determined by specific
+operations; the caller must supply appropriate inputs for the operation
+to be performed.
+
+The valid values of _index_ range from zero (0) to three (3), as no operation
+currently defined can accept more than four parameters.
+(This limit could increase in the future.)
+
+> [!NOTE]
+> If the _index_ does not correspond to a defined input for the operation,
+> then this function will have no effect.
+
+> [!IMPORTANT]
+> It is an error to call this function while the _aio_ is currently
+> in use by an active asynchronous operation.
+
+An input parameter set with this function may be retrieved later with
+the [`nng_aio_get_input()`][nng_aio_get_input] function.
+
+## SEE ALSO
+
+[nng_aio_alloc][nng_aio_alloc],
+[nng_aio_get_input][nng_aio_get_input]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_set_iov.md b/docs/reference/src/aio/nng_aio_set_iov.md
new file mode 100644
index 00000000..b8f1a0b5
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_set_iov.md
@@ -0,0 +1,42 @@
+# nng_aio_set_iov()
+
+## NAME
+
+nng_aio_set_iov --- set scatter/gather vector
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov);
+```
+
+## DESCRIPTION
+
+The `nng_aio_set_iov()` function sets a {{i:scatter/gather}} vector _iov_ on the handle _aio_.
+
+The _iov_ is a pointer to an array of _niov_ [`nng_iov`][nng_iov]
+structures, which have the following definition:
+
+```c
+typedef struct nng_iov {
+    void * iov_buf;
+    size_t iov_len;
+};
+```
+
+The _iov_ is copied into storage in the _aio_ itself, so that callers may use stack allocated `nng_iov` structures.
+The values pointed to by the `iov_buf` members are _not_ copied by this function though.
+
+A maximum of four (4) `nng_iov` members may be supplied.
+
+## RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+## ERRORS
+
+- `NNG_EINVAL`: Value of specified _niov_ is too large.
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_set_msg.md b/docs/reference/src/aio/nng_aio_set_msg.md
new file mode 100644
index 00000000..5b4c0e00
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_set_msg.md
@@ -0,0 +1,30 @@
+# nng_aio_set_msg()
+
+## NAME
+
+nng_aio_set_msg --- set message for asynchronous send
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void nng_aio_set_msg(nng_aio *aio, nng_msg *msg);
+```
+
+## DESCRIPTION
+
+The `nng_aio_set_msg()` function sets the message that will be used
+for an asynchronous send operation (see
+[`nng_send_aio()`][nng_send_aio]).
+
+> [!IMPORTANT]
+> The _aio_ must not have an operation in progress.
+
+## SEE ALSO
+
+[nng_aio_get_msg][nng_aio_get_msg],
+[nng_send_aio][nng_send_aio],
+[Messages][msg]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_set_timeout.md b/docs/reference/src/aio/nng_aio_set_timeout.md
new file mode 100644
index 00000000..f4b18a58
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_set_timeout.md
@@ -0,0 +1,55 @@
+# nng_aio_set_timeout
+
+## NAME
+
+nng_aio_set_timeout --- set asynchronous I/O timeout
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+typedef int nng_duration;
+void nng_aio_set_timeout(nng_aio *aio, nng_duration timeout);
+
+typedef uint64_t nng_time;
+void nng_aio_set_expire(nng_aio *aio, nng_time expiration);
+```
+
+## DESCRIPTION
+
+The `nng_aio_set_timeout()` function sets a {{ii:timeout}}
+for the asynchronous operation associated with _aio_.
+This causes a timer to be started when the operation is actually started.
+If the timer expires before the operation is completed, then it is
+aborted with an error of `NNG_ETIMEDOUT`.
+The _timeout_ is specified as a relative number of milliseconds.
+
+If the timeout is {{i:`NNG_DURATION_INFINITE`}}, then no timeout is used.
+If the timeout is {{i:`NNG_DURATION_DEFAULT`}}, then a "default" or socket-specific
+timeout is used.
+(This is frequently the same as `NNG_DURATION_INFINITE`.)
+
+The `nng_aio_set_expire()` function is similar to `nng_aio_set_timeout()`, but sets
+an absolute expiration time based on the system clock. The _expiration_
+is expressed as a number of milliseconds since some point in the past.
+The [`nng_clock()`](../util/nng_clock.md) function can be used to determine
+the current value of the clock.
+
+> [!TIP]
+> As most operations involve some context switching, it is usually a good
+> idea to allow at least a few tens of milliseconds before timing them out --
+> a too small timeout might not allow the operation to properly begin before
+> giving up!
+
+The value of _timeout_ set for the _aio_ is persistent, so that if the
+handle is reused for future operations, it will have the same relative
+or absolute timeout.
+
+## SEE ALSO
+
+[nng_aio_cancel][nng_aio_cancel],
+[nng_aio_result][nng_aio_result],
+[nng_clock][nng_clock]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_stop.md b/docs/reference/src/aio/nng_aio_stop.md
new file mode 100644
index 00000000..01e328b1
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_stop.md
@@ -0,0 +1,40 @@
+# nng_aio_stop
+
+## NAME
+
+nng_aio_stop - stop asynchronous I/O operation
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void nng_aio_stop(nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_aio_stop()` function stops the asynchronous I/O operation
+associated with _aio_ by aborting with `NNG_ECANCELED`, and then waits
+for it to complete or to be completely aborted, and for the
+callback associated with the _aio_ to have completed executing.
+
+Further calls to
+[`nng_aio_begin()`][nng_aio_begin] using this _aio_ will return `false`.
+
+It is safe to call this for an _aio_, even when no operation is currently
+pending for it.
+
+> [!TIP]
+> When multiple asynchronous I/O handles are in use and need to be
+> shut down, it is safest to stop all of them, before deallocating any of
+> them with [`nng_aio_free()`][nng_aio_free], particularly if the callbacks
+> might attempt to reschedule additional operations.
+
+## SEE ALSO
+
+[nng_aio_cancel][nng_aio_cancel],
+[nng_aio_free][nng_aio_free],
+[nng_aio_wait][nng_aio_wait]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/aio/nng_aio_wait.md b/docs/reference/src/aio/nng_aio_wait.md
new file mode 100644
index 00000000..f3d1e384
--- /dev/null
+++ b/docs/reference/src/aio/nng_aio_wait.md
@@ -0,0 +1,35 @@
+# nng_aio_wait
+
+## NAME
+
+nng_aio_wait --- wait for asynchronous I/O operation
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void nng_aio_wait(nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_aio_wait()` function waits for an asynchronous I/O operation
+to complete.
+If the operation has not been started, or has already
+completed, then it returns immediately.
+
+If a callback was set with _aio_ when it was allocated, then this
+function will not be called until the callback has completed.
+
+> [!IMPORTANT]
+> This function should never be called from a function that itself
+> is a callback of an [`nng_aio`][aio], either this one or any other.
+> Doing so may result in a deadlock.
+
+## SEE ALSO
+
+[nng_aio_abort][nng_aio_abort],
+[nng_aio_busy][nng_aio_busy]
+
+{{#include ../refs.md}}