docs: AIO chapter (consumer only) converted to mdbook.

18 files changed, 312 insertions, 800 deletions

diff --git a/docs/man/nng_aio_alloc.3.adoc b/docs/man/nng_aio_alloc.3.adoc
deleted file mode 100644
index 6a424e3b..00000000
--- a/docs/man/nng_aio_alloc.3.adoc
+++ /dev/null
@@ -1,88 +0,0 @@
-= nng_aio_alloc(3)
-//
-// Copyright 2022 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_aio_alloc - allocate asynchronous I/O handle
-
-== SYNOPSIS
-
-[source, 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 ((asynchronous I/O))
-operations, and stores a pointer to it in __aiop__.
-The handle is initialized with a completion ((callback)) of _callb_,
-which will be executed when an associated asynchronous operation finishes.
-It will be called with the argument _arg_.
-
-NOTE: 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 xref:nng_cv_alloc.3supp.adoc[condition variable]
-which can be signaled by the callback.
-
-Asynchronous I/O operations all take an xref:nng_aio.5.adoc[`nng_aio`]
-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
-xref:nng_aio_result.3.adoc[`nng_aio_result()`],
-xref:nng_aio_count.3.adoc[`nng_aio_count()`],
-and xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`].
-
-It is possible to wait synchronously for an otherwise asynchronous operation
-by using the function xref:nng_aio_wait.3.adoc[`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
-xref:nng_aio_wait.3.adoc[`nng_aio_wait()`].
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient free memory to perform the operation.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_abort.3.adoc[nng_aio_abort(3)],
-xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)],
-xref:nng_aio_count.3.adoc[nng_aio_count(3)],
-xref:nng_aio_free.3.adoc[nng_aio_free(3)],
-xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)],
-xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)],
-xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)],
-xref:nng_aio_result.3.adoc[nng_aio_result(3)],
-xref:nng_aio_set_input.3.adoc[nng_aio_set_input(3)],
-xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)],
-xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)],
-xref:nng_aio_set_timeout.3.adoc[nng_aio_set_timeout(3)],
-xref:nng_aio_stop.3.adoc[nng_aio_stop(3)],
-xref:nng_aio_wait.3.adoc[nng_aio_wait(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_aio_busy.3.adoc b/docs/man/nng_aio_busy.3.adoc
deleted file mode 100644
index 4aaf09b5..00000000
--- a/docs/man/nng_aio_busy.3.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-= nng_aio_busy(3)
-//
-// Copyright 2022 Staysail Systems, Inc. <info@staysail.tech>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_aio_busy - test if asynchronous I/O is busy
-
-== SYNOPSIS
-
-[source, 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
-xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]
-
-NOTE: 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.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_abort.3.adoc[nng_aio_abort(3)],
-xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)],
-xref:nng_aio_wait.3.adoc[nng_aio_wait(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_aio_count.3.adoc b/docs/man/nng_aio_count.3.adoc
deleted file mode 100644
index daf97710..00000000
--- a/docs/man/nng_aio_count.3.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-= nng_aio_count(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_aio_count - return number of bytes transferred
-
-== SYNOPSIS
-
-[source, 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 xref:nng_aio_set_iov.3.adoc[`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
-xref:nng_aio_wait.3.adoc[`nng_aio_wait()`].
-
-== RETURN VALUES
-
-The number of bytes transferred by the operation.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)],
-xref:nng_aio_result.3.adoc[nng_aio_result(3)],
-xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)],
-xref:nng_aio_wait.3.adoc[nng_aio_wait(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_aio_free.3.adoc b/docs/man/nng_aio_free.3.adoc
deleted file mode 100644
index c2528633..00000000
--- a/docs/man/nng_aio_free.3.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-= nng_aio_free(3)
-//
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_aio_free - free asynchronous I/O handle
-
-== SYNOPSIS
-
-[source, 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 xref:nng_aio_stop.3.adoc[`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.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)],
-xref:nng_aio_stop.3.adoc[nng_aio_stop(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_aio_get_msg.3.adoc b/docs/man/nng_aio_get_msg.3.adoc
deleted file mode 100644
index c4205658..00000000
--- a/docs/man/nng_aio_get_msg.3.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-= nng_aio_get_msg(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_aio_get_msg - get message from asynchronous receive
-
-== SYNOPSIS
-
-[source, 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 xref:nng_recv_aio.3.adoc[`nng_recv_aio()`])
-or that was previously stored with xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`].
-
-IMPORTANT: The xref:nng_aio.5.adoc[`nng_aio`] must not have an operation in progress.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)],
-xref:nng_recv_aio.3.adoc[nng_recv_aio(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng_msg.5.adoc[nng_msg(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_aio_get_output.3.adoc b/docs/man/nng_aio_get_output.3.adoc
deleted file mode 100644
index 4dfd67c3..00000000
--- a/docs/man/nng_aio_get_output.3.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-= nng_aio_get_output(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_aio_get_output - return output result
-
-== SYNOPSIS
-
-[source, 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 result of the operation, or `NULL`.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)],
-xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)],
-xref:nng_aio_set_input.3.adoc[nng_aio_set_input(3)],
-xref:nng_aio_result.3.adoc[nng_aio_result(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_aio_result.3.adoc b/docs/man/nng_aio_result.3.adoc
deleted file mode 100644
index e1886a6e..00000000
--- a/docs/man/nng_aio_result.3.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-= nng_aio_result(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_aio_result - return result of asynchronous operation
-
-== SYNOPSIS
-
-[source, 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
-xref:nng_aio_wait.3.adoc[`nng_aio_wait()`].
-
-== RETURN VALUES
-
-The result of the operation, either zero on success, or an error
-number on failure.
-
-== ERRORS
-
-[horizontal]
-`NNG_ETIMEDOUT`:: The operation timed out.
-`NNG_ECANCELED`:: The operation was canceled.
-
-Various other return values are possible depending on the operation.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_abort.3.adoc[nng_aio_abort(3)],
-xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)],
-xref:nng_aio_wait.3.adoc[nng_aio_wait(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_aio_set_input.3.adoc b/docs/man/nng_aio_set_input.3.adoc
deleted file mode 100644
index 37cf3cdd..00000000
--- a/docs/man/nng_aio_set_input.3.adoc
+++ /dev/null
@@ -1,63 +0,0 @@
-= nng_aio_set_input(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_aio_set_input - set input parameter
-
-== SYNOPSIS
-
-[source, 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 xref:nng_aio_get_input.3.adoc[`nng_aio_get_input()`] function.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)],
-xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)],
-xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)],
-xref:nng_aio_result.3.adoc[nng_aio_result(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_aio_set_iov.3.adoc b/docs/man/nng_aio_set_iov.3.adoc
deleted file mode 100644
index 83128011..00000000
--- a/docs/man/nng_aio_set_iov.3.adoc
+++ /dev/null
@@ -1,67 +0,0 @@
-= nng_aio_set_iov(3)
-//
-// Copyright 2021 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_aio_set_iov - set scatter/gather vector
-
-== SYNOPSIS
-
-[source,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 ((scatter/gather)) vector _iov_ on the handle _aio_.
-
-The _iov_ is a pointer to an array of _niov_ xref:nng_iov.5.adoc[`nng_iov`]
-structures, which have the following definition:
-
-[source,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.
-
-NOTE: Earlier versions of the library could accept longer scatter-gather lists.
-However, no known consumers have ever needed a scatter-gather list longer than 4 vectors.
-As a result, the implementation limit was reduced, and heap allocations which could fail were removed.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_EINVAL`:: Value of specified _niov_ is too large.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)],
-xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)],
-xref:nng_aio_count.3.adoc[nng_aio_count(3)],
-xref:nng_aio_result.3.adoc[nng_aio_result(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng_iov.5.adoc[nng_iov(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_aio_set_msg.3.adoc b/docs/man/nng_aio_set_msg.3.adoc
deleted file mode 100644
index e0ea3e46..00000000
--- a/docs/man/nng_aio_set_msg.3.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-= nng_aio_set_msg(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_aio_set_msg - set message for asynchronous send
-
-== SYNOPSIS
-
-[source, 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 xref:nng_send_aio.3.adoc[`nng_send_aio()`]).
-
-IMPORTANT: The xref:nng_aio.5.adoc[`nng_aio`] must not have an operation in progress.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)],
-xref:nng_send_aio.3.adoc[nng_send_aio(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng_msg.5.adoc[nng_msg(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_aio_set_timeout.3.adoc b/docs/man/nng_aio_set_timeout.3.adoc
deleted file mode 100644
index a82b0c83..00000000
--- a/docs/man/nng_aio_set_timeout.3.adoc
+++ /dev/null
@@ -1,74 +0,0 @@
-= nng_aio_set_timeout(3)
-//
-// Copyright 2023 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_aio_set_timeout - set asynchronous I/O timeout
-
-== SYNOPSIS
-
-[source, 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 _timeout_(((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 `NNG_DURATION_INFINITE`, then no timeout is used.
-If the timeout is `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 xref:nng_clock.3supp.adoc[`nng_clock()`] 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 multiple operations, they will have the same relative
-timeout.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)],
-xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)],
-xref:nng_aio_result.3.adoc[nng_aio_result(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng_duration.5.adoc[nng_duration(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_aio_wait.3.adoc b/docs/man/nng_aio_wait.3.adoc
deleted file mode 100644
index acac6fdf..00000000
--- a/docs/man/nng_aio_wait.3.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-= nng_aio_wait(3)
-//
-// Copyright 2023 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_aio_wait - wait for asynchronous I/O operation
-
-== SYNOPSIS
-
-[source, 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 xref:nng_aio.5.adoc[`aio`], either this one or any other.
-Doing so may result in a deadlock.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_abort.3.adoc[nng_aio_abort(3)],
-xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)],
-xref:nng_aio_busy.3.adoc[nng_aio_busy(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md
index 5b79644a..ed3e1233 100644
--- a/docs/ref/SUMMARY.md
+++ b/docs/ref/SUMMARY.md
@@ -14,10 +14,7 @@
 
   - [URLs](./api/url.md)
 
-  - [Asynchronous Operations](./api/aio/index.md)
-
-    - [nng_aio](./api/aio/nng_aio.md)
-    - [aio_cancel](./api/aio/aio_cancel.md)
+  - [Asynchronous I/O](./api/aio.md)
 
   - [Synchronization](./api/synch.md)
 
diff --git a/docs/ref/api/aio.md b/docs/ref/api/aio.md
new file mode 100644
index 00000000..230744e8
--- /dev/null
+++ b/docs/ref/api/aio.md
@@ -0,0 +1,287 @@
+# Asynchronous Operations
+
+In order to obtain significant scalability, with low-latency, and minimal
+overheads, _NNG_ supports performing operations asynchronously.
+
+One way that applications can perform work asynchronously and concurrently
+is by using [threads][thread], but threads carry significant resource overheads
+and frequently there are limits on the number that can easily be created.
+
+Additionally, with most network applications, the flow of execution will spend
+the bulk of its time waiting for traffic from a peer.
+
+For these kinds of applications, it is far more efficient to use asynchronous operations
+using the mechanisms described in this chapter.
+
+> [!TIP]
+> To get the highest performance with the least overhead, applications should use
+> asynchronous operations described in this chapter whenever possible.
+
+## Asynchronous I/O Handle
+
+```c
+typedef struct nng_aio nng_aio;
+```
+
+An {{i:`nng_aio`}}{{hi:aio}} is an opaque structure used in conjunction with
+{{i:asynchronous I/O}} operations.
+Every asynchronous operation uses one of these structures, each of which
+can only be used with a single operation at a time.
+
+Asynchronous operations are performed without blocking calling application threads.
+Instead the application registers a callback function to be executed
+when the operation is complete (whether successfully or not).
+This callback will be executed exactly once.
+
+The asynchronous I/O framework also supports [cancellation][`nng_aio_cancel`] of
+operations that are already in progress as well setting a maximum
+[timeout][`nng_aio_set_timeout`] for them to complete.
+
+It is also possible to initiate an asynchronous operation, and [wait][`nng_aio_wait`] for it to
+complete, creating a synchronous flow from an asynchronous one.
+
+## Create Handle
+
+```c
+int nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg);
+```
+
+The {{i:`nng_aio_alloc`}} function creates an [`nng_aio`] object, with the
+{{i:callback}} _callb_ taking the argument _arg_, and returns it in _aiop_.
+
+If this succeeds, the function returns zero. Otherwise it may return [`NNG_ENOMEM`].
+
+> [!TIP]
+> The _arg_ should normally be a structure that contains a pointer to the _aiop_,
+> or from which it can be located. This allows _callb_ to check the handle for
+> success using [`nng_aio_result`], as well access other properties of _aiop_.
+
+> [!TIP]
+> The _callb_ may be executed on another [thread], so it may be necessary to use
+> [synchronization] methods in _callb_ to avoid data races.
+
+## Destroy Handle
+
+```c
+void nng_aio_free(nng_aio *aio);
+void nng_aio_reap(nng_aio *aio);
+```
+
+The {{i:`nng_aio_free`}} handle destroys the handle _aio_, waiting for any operations
+and associated callbacks to complete before doing so.
+
+The {{i:`nng_aio_reap`}} handle destroys the handle _aio_ asynchronously, using a _reaper_
+[thread] to do so. It does not wait for the object to be destroyed. Thus this function
+is safe to call from _aio_'s own callback.
+
+> [!NOTE]
+> The `nng_aio_free` function must never be called from an _aio_ callback.
+> Use `nng_aio_reap` instead if an object must be destroyed from a callback.
+
+## Cancellation
+
+```c
+void nng_aio_abort(nng_aio *aio, int err);
+void nng_aio_cancel(nng_aio *aio);
+void nng_aio_stop(nng_aio *aio);
+```
+
+These functions are used to stop a previously submitted asynchronous
+I/O operation. The operation may be canceled, or may continue to
+completion. If no operation is in progress (perhaps because it has
+already completed), then these operations have no effect.
+If the operation is successfully canceled or aborted, then the callback
+will still be called.
+
+The {{i:`nng_aio_abort`}} function aborts the operation associated with _aio_
+and returns immediately without waiting. If cancellation was successful,
+then [`nng_aio_result`] will return _err_.
+
+The {{i:`nng_aio_cancel`}} function acts like `nng_aio_abort`, but uses the error code
+[`NNG_ECANCELED`]{{hi:`NNG_ECANCELED`}}.
+
+The {{i:`nng_aio_stop`}} function aborts the _aio_ operation with [`NNG_ECANCELED`],
+and then waits the operation and any associated callback to complete.
+This function also marks _aio_ itself permanently stopped, so that any
+new operations scheduled by I/O providers using [`nng_aio_begin`]
+return false. Thus this function should be used to teardown operations.
+
+> [!TIP]
+> When multiple asynchronous I/O handles are in use and need to be
+> deallocated, it is safest to stop all of them using `nng_aio_stop`,
+> before deallocating any of them with [`nng_aio_free`],
+> particularly if the callbacks might attempt to reschedule further operations.
+
+## Set Timeout
+
+```c
+void nng_aio_set_timeout(nng_aio *aio, nng_duration timeout);
+void nng_aio_set_expire(nng_aio *aio, nng_time expiration);
+```
+
+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][`nng_aio_abort`] with an error of `NNG_ETIMEDOUT`.
+The _timeout_ [duration][time] is specified as a relative number of milliseconds.
+
+If the timeout is [`NNG_DURATION_INFINITE`], then no timeout is used.
+If the timeout is [`NNG_DURATION_DEFAULT`], then a "default" or socket-specific
+timeout is used.
+(This is frequently the same as [`NNG_DURATION_INFINITE`].)
+
+The {{i:`nng_aio_set_expire`}} function is similar to `nng_aio_set_timeout`, but sets
+an expiration time based on the system clock. The _expiration_
+[time] is a clock timestamp, such as would be returned by [`nng_clock`].
+
+## Wait for Completion
+
+```c
+void nng_aio_wait(nng_aio *aio);
+```
+
+The {{i:`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]
+> The `nng_aio_wait` function should never be called from a function that itself
+> is a callback of an [`nng_aio`], either this one or any other.
+> Doing so may result in a deadlock.
+
+## Test for Completion
+
+```c
+bool nng_aio_busy(nng_aio *aio);
+```
+
+The {{i:`nng_aio_busy`}} function returns `true` if the _aio_ is currently busy performing an
+operation or is executing a completion callback. Otherwise it return `false`.
+This is the same test used internally by [`nng_aio_wait`].
+
+> [!IMPORTANT]
+> The caller is responsible for coordinating any use of this with any reuse of the _aio_.
+> Because the _aio_ can be reused use of this function can be racy.
+
+## Result of Operation
+
+```c
+int nng_aio_result(nng_aio *aio);
+size_t nng_aio_count(nng_aio *aio);
+```
+
+The {{i:`nng_aio_result`}} function 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, such as [`NNG_ECANCELED`] or [`NNG_ETIMEDOUT`], is returned.
+
+For operations that transfer data, {{i:`nng_aio_count`}} returns the
+number of bytes transferred by the operation associated with the handle _aio_.
+Operations that do not transfer data, or do not keep a count, may return zero for this function.
+
+> [!NOTE]
+> The return value from these functions is undefined if the operation has not completed yet.
+> Either call these from the handle's completion callback, or after waiting for the
+> operation to complete with [`nng_aio_wait`].
+
+## Messages
+
+```c
+nng_msg *nng_aio_get_msg(nng_aio *aio);
+void nng_aio_set_msg(nng_aio *aio, nng_msg *msg);
+```
+
+The {{i:`nng_aio_get_msg`}} and {{i:`nng_aio_set_msg`}} functions retrieve and store a [message]
+in _aio_.
+For example, if a function to receive data is called, that function can generally be expected
+to store a message on the asssociated _aio_, for the application to retrieve with
+`nng_aio_get_msg`.
+Conversely an application desiring to send a message _msg_ will store it in the _aio_ using
+`nng_aio_set_msg`. The function implementing the send operation will retrieve the message
+and arrange for it to be sent.
+
+### Message Ownership
+
+For send or transmit operations, the rule of thumb is that implementation of the operation
+is responsible for taking ownership of the message (and releasing resources when it is complete),
+if it will return success. If the operation will end in error, then the message will be
+retained and it is the consuming application's responsibility to dispose of the message.
+This allows an application the opportunity to reuse the message to try again, if it so desires.
+
+For receive operations, the implementation of the operation will set the message on the _aio_
+on success, and the consuming application hasa responsibility to retrieve and dispose of the
+message. Failure to do so will leak the message. If the operation does not complete successfully,
+then no message is stored on the _aio_.
+
+## I/O Vector
+
+```c
+typedef struct nng_iov {
+    void * iov_buf;
+    size_t iov_len;
+};
+
+int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov);
+```
+
+For some operations, the unit of data transferred is not a [message], but
+rather a stream of bytes.
+
+For these operations, an array of _niov_ {{i:`nng_iov`}} structures can be passed to
+the {{i:`nng_aio_set_iov`}} function to provide a scatter/gather array of
+elements describing the location (`iov_buf`) and length (`iov_len`) of data,
+to transfer.
+
+The _iov_ vector 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.
+
+> [!TIP]
+> Most functions using `nng_iov` do not guarantee to transfer all of the data that they
+> are requested to. To be sure that correct amount of data is transferred, as well as to
+> start an attempt to complete any partial transfer, check the amount of data transferred by
+> calling [`nng_aio_count`].
+
+## Inputs and Outputs
+
+```c
+void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param);
+void *nng_aio_get_output(nng_aio *aio, unsigned int index);
+```
+
+Asynchronous operations can take additional input parameters, and
+provide additional result outputs besides the [result][`nng_aio_result`] code.
+
+The `nng_aio_set_input` function sets the input parameter at _index_
+to _param_ for the operation associated with _aio_.
+
+The `nng_aio_get_output` function returns the output result at _index_
+for the operation associated with _aio_.
+
+The type and semantics of input parameters and output results are determined by specific
+operations. The documentation for the operation should provide details.
+
+The valid values of _index_ range from zero (0) to three (3), as no operation
+currently defined can accept more than four parameters or return more than four additional
+results.
+
+> [!NOTE]
+> If the _index_ does not correspond to a defined input for the operation,
+> then `nng_aio_set_input` will have no effect, and `nng_aio_get_output` will
+> return `NULL`.
+
+> [!IMPORTANT]
+> It is an error to call this function while the _aio_ is currently
+> in use by an active asynchronous operation.
+
+## See Also
+
+[Synchronization][synchronization],
+[Threads][thread],
+[Time][time]
+
+{{#include ../xref.md}}
diff --git a/docs/ref/api/aio/index.md b/docs/ref/api/aio/index.md
deleted file mode 100644
index 1e9872e9..00000000
--- a/docs/ref/api/aio/index.md
+++ /dev/null
@@ -1 +0,0 @@
-# Asynchronous I/O Operations
diff --git a/docs/ref/api/aio/nng_aio.md b/docs/ref/api/aio/nng_aio.md
deleted file mode 100644
index 0fdb6ca1..00000000
--- a/docs/ref/api/aio/nng_aio.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# nng_aio
-
-## NAME
-
-nng_aio - asynchronous I/O handle
-
-## SYNOPSIS
-
-```c
-#include <nng/nng.h>
-
-typedef struct nng_aio nng_aio;
-```
-
-## DESCRIPTION
-
-An {{i:`nng_aio`}}{{hi:aio}} is an opaque structure used in conjunction with
-{{i:asynchronous I/O}} operations.
-Every asynchronous operation uses one of these structures, each of which
-can only be used with a single operation at a time.
-
-Asynchronous operations are performed without blocking calling application threads.
-Instead the application registers a callback function to be executed
-when the operation is complete (whether successfully or not).
-This callback will be executed exactly once.
-
-The asynchronous I/O framework also supports cancellation of
-operations that are already in progress
-(see [`nng_aio_cancel`][aio_cancel]), as well setting a maximum
-timeout for them to complete within
-(see [`nng_aio_set_timeout`][nng_aio_set_timeout]).
-
-It is also possible to initiate an asynchronous operation, and wait for it to
-complete using [`nng_aio_wait`][nng_aio_wait].
-
-These structures are created using [`nng_aio_alloc`][nng_aio_alloc],
-and destroyed using [`nng_aio_free`][nng_aio_free].
-
-## SEE ALSO
-
-[nng_aio_cancel][aio_cancel],
-[nng_aio_alloc][nng_aio_alloc],
-[nng_aio_free][nng_aio_free],
-[nng_aio_set_timeout][nng_aio_set_timeout]
-
-<!--
-xref:nng_aio_count.3.adoc[nng_aio_count(3)],
-xref:nng_aio_free.3.adoc[nng_aio_free(3)],
-xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)],
-xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)],
-xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)],
-xref:nng_aio_result.3.adoc[nng_aio_result(3)],
-xref:nng_aio_set_input.3.adoc[nng_aio_set_input(3)],
-xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)],
-xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)],
-xref:nng_aio_wait.3.adoc[nng_aio_wait(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
--->
-
-[aio_cancel]: nng_aio_cancel.md
-[nng_aio_alloc]: nng_aio_alloc.md
-[nng_aio_free]: nng_aio_free.md
-[nng_aio_set_timeout]: nng_aio_set_timeout.md
-[nng_aio_wait]: TODO.md
diff --git a/docs/ref/api/synch.md b/docs/ref/api/synch.md
index 82eee869..d56fb600 100644
--- a/docs/ref/api/synch.md
+++ b/docs/ref/api/synch.md
@@ -172,3 +172,9 @@ one thread (which may be chosen randomly).
 ```
 
 {{#include ../xref.md}}
+
+## See Also
+
+[Threads][thread],
+[Time][time],
+[Asynchronous I/O][aio]
diff --git a/docs/ref/xref.md b/docs/ref/xref.md
index d103a73b..3abf999c 100644
--- a/docs/ref/xref.md
+++ b/docs/ref/xref.md
@@ -56,8 +56,20 @@
 [`nng_send`]: /TODO.md
 [`nng_recv`]: /TODO.md
 [`nng_aio`]: /TODO.md
+[`nng_aio_alloc`]: /api/aio.md#create-handle
+[`nng_aio_free`]: /api/aio.md#destroy-handle
 [`nng_sleep_aio`]: /TODO.md
-[`nng_aio_cancel`]: /TODO.md
+[`nng_aio`]: /api/aio.md#asynchronous-i-o-handle
+[`nng_aio_cancel`]: /api/aio.md#cancellation
+[`nng_aio_abort`]: /api/aio.md#cancellation
+[`nng_aio_stop`]: /api/aio.md#cancellation
+[`nng_aio_wait`]: /api/api.md#wait-for-completion
+[`nng_aio_busy`]: /api/api.md#test-for-completion
+[`nng_aio_result`]: /api/api.md#result-of-operation
+[`nng_aio_count`]: /api/api.md#result-of-operation
+[`nng_aio_begin`]: /TODO.md
+[`nng_aio_finish`]: /TODO.md
+[`nng_aio_set_timeout`]: /TODO.md
 [`nng_opts_parse`]: /TODO.md
 
 <!-- Macros -->
@@ -131,12 +143,13 @@
 
 <!-- Concept index -->
 
-[aio]: /TODO.md
+[aio]: /api/aio.md
 [raw]: /TODO.md
 [pipe]: /TODO.md
 [socket]: /TODO.md
 [dialer]: /TODO.md
 [listener]: /TODO.md
+[message]: /api/msg.md
 [message-body]: /api/msg.md#message-body
 [message-header]: /api/msg.md#message-header
 [synchronization]: /api/synch.md
@@ -144,3 +157,6 @@
 [condvar]: /api/synch.md#condition-variable
 [thread]: /api/thread.md
 [statistic]: /api/stats.md
+[time]: /api/time.md
+[error]: /api/errors.md
+[duration]: /api/time.md#duration-type