23 files changed, 133 insertions, 50 deletions
diff --git a/docs/reference/src/api/aio/index.md b/docs/reference/src/api/aio/index.md
new file mode 100644
index 00000000..4c49ff78
--- /dev/null
+++ b/docs/reference/src/api/aio/index.md
@@ -0,0 +1,74 @@
+# Interfaces for 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.md),
+and destroyed using [`nng_aio_free()`](nng_aio_free.md).
+
+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.md)), as well setting a maximum
+timeout for them to complete within
+(see [`nng_aio_set_timeout()`](nng_aio_set_timeout.md)).
+
+## Waiting for Completion
+
+It is also possible to initiate an asynchronous operation, and wait for it to
+complete [`nng_aio_wait()`](nng_aio_wait.md).
+
+> [!IMPORTANT]
+> Applications must never call [`nng_aio_wait()`](nng_aio_wait.md) or
+> [`nng_aio_stop()`](nng_aio_stop.md) from a callback registered to
+> an `nng_aio` object. Doing so can lead to a deadlock.
+
+## See Also
+
+[nng_aio_abort()](nng_aio_abort.md),
+[nng_aio_alloc()](nng_aio_alloc.md),
+[nng_aio_cancel()](nng_aio_cancel.md),
+[nng_aio_count()](nng_aio_count.md),
+[nng_aio_free()](nng_aio_free.md),
+[nng_aio_get_input()](nng_aio_get_input.md),
+[nng_aio_get_msg()](nng_aio_get_msg.md),
+[nng_aio_get_output()](nng_aio_get_output.md),
+[nng_aio_result()](nng_aio_result.md),
+[nng_aio_set_input()](nng_aio_set_input.md),
+[nng_aio_set_iov()](nng_aio_set_iov.md),
+[nng_aio_set_msg()](nng_aio_set_msg.md),
+[nng_aio_set_timeout()](nng_aio_set_timeout.md),
+[nng_aio_stop()](nng_aio_stop.md),
+[nng_aio_wait()](nng_aio_wait.md)
diff --git a/docs/reference/src/api/nng_aio_abort.md b/docs/reference/src/api/aio/nng_aio_abort.md
index 4f4b8773..09e0fd2e 100644
--- a/docs/reference/src/api/nng_aio_abort.md
+++ b/docs/reference/src/api/aio/nng_aio_abort.md
@@ -32,5 +32,4 @@ has no effect.
 
 [nng_aio_alloc()](nng_aio_alloc.md),
 [nng_aio_cancel()](nng_aio_cancel.md),
-[nng_aio_result()](nng_aio_result.md),
-[nng_aio](nng_aio.md)
+[nng_aio_result()](nng_aio_result.md)
diff --git a/docs/reference/src/api/nng_aio_alloc.md b/docs/reference/src/api/aio/nng_aio_alloc.md
index 4acb45aa..1f3f6be8 100644
--- a/docs/reference/src/api/nng_aio_alloc.md
+++ b/docs/reference/src/api/aio/nng_aio_alloc.md
@@ -32,7 +32,7 @@ It will be called with the argument _arg_.
 > thread can be used, along with a [condition variable](nng_cv_alloc.md)
 > which can be signaled by the callback.
 
-Asynchronous I/O operations all take an [`nng_aio`](nng_aio.md)
+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.
@@ -71,6 +71,4 @@ This function returns 0 on success, and non-zero otherwise.
 [nng_aio_set_msg()](nng_aio_set_msg.md),
 [nng_aio_set_timeout()](nng_aio_set_timeout.md),
 [nng_aio_stop()](nng_aio_stop.md),
-[nng_aio_wait()](nng_aio_wait.md),
-[nng_strerror()](nng_strerror.md),
-[nng_aio](nng_aio.md)
+[nng_aio_wait()](nng_aio_wait.md)
diff --git a/docs/reference/src/api/nng_aio_busy.md b/docs/reference/src/api/aio/nng_aio_busy.md
index f5a1003b..2a794a83 100644
--- a/docs/reference/src/api/nng_aio_busy.md
+++ b/docs/reference/src/api/aio/nng_aio_busy.md
@@ -38,5 +38,4 @@ True if the _aio_ is busy, false otherwise.
 
 [nng_aio_abort()](nng_aio_abort.md),
 [nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_wait(3)](nng_aio_wait.md),
-[nng_aio](nng_aio.md)
+[nng_aio_wait(3)](nng_aio_wait.md)
diff --git a/docs/reference/src/api/nng_aio_cancel.md b/docs/reference/src/api/aio/nng_aio_cancel.md
index 1bb8869e..63cad987 100644
--- a/docs/reference/src/api/nng_aio_cancel.md
+++ b/docs/reference/src/api/aio/nng_aio_cancel.md
@@ -34,5 +34,4 @@ This function is the same as calling
 
 [nng_aio_abort()](nng_aio_abort.md),
 [nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_result()](nng_aio_result.md),
-[nng_aio](nng_aio.md)
+[nng_aio_result()](nng_aio_result.md)
diff --git a/docs/reference/src/api/nng_aio_count.md b/docs/reference/src/api/aio/nng_aio_count.md
index 2ce22786..a4da3c64 100644
--- a/docs/reference/src/api/nng_aio_count.md
+++ b/docs/reference/src/api/aio/nng_aio_count.md
@@ -38,9 +38,7 @@ The number of bytes transferred by the operation.
 
 ## SEE ALSO
 
-[.text-left]
 [nng_aio_alloc()](nng_aio_alloc.md),
 [nng_aio_result()](nng_aio_result.md),
 [nng_aio_set_iov()](nng_aio_set_iov.md),
-[nng_aio_wait()](nng_aio_wait.md),
-[nng_aio](nng_aio)
+[nng_aio_wait()](nng_aio_wait.md)
diff --git a/docs/reference/src/api/nng_aio_free.md b/docs/reference/src/api/aio/nng_aio_free.md
index c558535d..c558535d 100644
--- a/docs/reference/src/api/nng_aio_free.md
+++ b/docs/reference/src/api/aio/nng_aio_free.md
diff --git a/docs/reference/src/api/nng_aio_get_msg.md b/docs/reference/src/api/aio/nng_aio_get_msg.md
index 70e18be9..55f712db 100644
--- a/docs/reference/src/api/nng_aio_get_msg.md
+++ b/docs/reference/src/api/aio/nng_aio_get_msg.md
@@ -27,5 +27,4 @@ or that was previously stored with
 
 [nng_aio_set_msg()](nng_aio_set_msg.md),
 [nng_recv_aio()](nng_recv_aio.md),
-[nng_aio](nng_aio.md),
 [nng_msg](nng_msg.md)
diff --git a/docs/reference/src/api/nng_aio_get_output.md b/docs/reference/src/api/aio/nng_aio_get_output.md
index 8f0a10a4..d25c1c20 100644
--- a/docs/reference/src/api/nng_aio_get_output.md
+++ b/docs/reference/src/api/aio/nng_aio_get_output.md
@@ -36,6 +36,5 @@ The _index_&zwj;th output from the operation, or `NULL`.
 ## SEE ALSO
 
 [nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_set_output()](nng_aio_set_output.md),
-[nng_aio_result()](nng_aio_result.md),
-[nng_aio](nng_aio.md),
+[nng_aio_set_output()](../aio_provider/nng_aio_set_output.md),
+[nng_aio_result()](nng_aio_result.md)
diff --git a/docs/reference/src/api/nng_aio_result.md b/docs/reference/src/api/aio/nng_aio_result.md
index fe6688fd..fe6688fd 100644
--- a/docs/reference/src/api/nng_aio_result.md
+++ b/docs/reference/src/api/aio/nng_aio_result.md
diff --git a/docs/reference/src/api/nng_aio_set_input.md b/docs/reference/src/api/aio/nng_aio_set_input.md
index 739489ad..1b3e0883 100644
--- a/docs/reference/src/api/nng_aio_set_input.md
+++ b/docs/reference/src/api/aio/nng_aio_set_input.md
@@ -39,5 +39,4 @@ the [`nng_aio_get_input()`](nng_aio_get_input.md) function.
 ## SEE ALSO
 
 [nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_get_input()](nng_aio_get_input.md),
-[nng_aio](nng_aio.md)
+[nng_aio_get_input()](../aio_provider/nng_aio_get_input.md)
diff --git a/docs/reference/src/api/nng_aio_set_iov.md b/docs/reference/src/api/aio/nng_aio_set_iov.md
index 4093b5e3..0c33153d 100644
--- a/docs/reference/src/api/nng_aio_set_iov.md
+++ b/docs/reference/src/api/aio/nng_aio_set_iov.md
@@ -38,8 +38,3 @@ This function returns 0 on success, and non-zero otherwise.
 ## ERRORS
 
 - `NNG_EINVAL`: Value of specified _niov_ is too large.
-
-## SEE ALSO
-
-[nng_aio](nng_aio),
-[nng_iov](nng_iov)
diff --git a/docs/reference/src/api/nng_aio_set_msg.md b/docs/reference/src/api/aio/nng_aio_set_msg.md
index eb0bd4ed..24ba9f60 100644
--- a/docs/reference/src/api/nng_aio_set_msg.md
+++ b/docs/reference/src/api/aio/nng_aio_set_msg.md
@@ -25,5 +25,4 @@ for an asynchronous send operation (see
 
 [nng_aio_get_msg()](nng_aio_get_msg.md),
 [nng_send_aio()](nng_send_aio.md),
-[nng_aio](nng_aio.md),
 [nng_msg](nng_msg.md)
diff --git a/docs/reference/src/api/nng_aio_set_timeout.md b/docs/reference/src/api/aio/nng_aio_set_timeout.md
index e8643570..b0bab9ab 100644
--- a/docs/reference/src/api/nng_aio_set_timeout.md
+++ b/docs/reference/src/api/aio/nng_aio_set_timeout.md
@@ -50,5 +50,4 @@ or absolute timeout.
 
 [nng_aio_cancel()](nng_aio_cancel.md),
 [nng_aio_result()](nng_aio_result.md),
-[nng_aio](nng_aio),
 [nng_duration](nng_duration)
diff --git a/docs/reference/src/api/nng_aio_stop.md b/docs/reference/src/api/aio/nng_aio_stop.md
index 4cfe41b6..8ac32a76 100644
--- a/docs/reference/src/api/nng_aio_stop.md
+++ b/docs/reference/src/api/aio/nng_aio_stop.md
@@ -36,5 +36,4 @@ pending for it.
 [nng_aio_cancel()](nng_aio_cancel.md),
 [nng_aio_free()](nng_aio_free.md),
 [nng_aio_begin()](nng_aio_begin.md),
-[nng_aio_wait()](nng_aio-wait.md),
-[nng_aio](nng_aio.md),
+[nng_aio_wait()](nng_aio-wait.md)
diff --git a/docs/reference/src/api/nng_aio_wait.md b/docs/reference/src/api/aio/nng_aio_wait.md
index 2cddcb29..52f5671e 100644
--- a/docs/reference/src/api/nng_aio_wait.md
+++ b/docs/reference/src/api/aio/nng_aio_wait.md
@@ -30,5 +30,4 @@ function will not be called until the callback has completed.
 ## SEE ALSO
 
 [nng_aio_abort()](nng_aio_abort.md),
-[nng_aio_busy()](nng_aio_busy.md),
-[nng_aio](nng_aio.md)
+[nng_aio_busy()](nng_aio_busy.md)
diff --git a/docs/reference/src/api/aio_provider/index.md b/docs/reference/src/api/aio_provider/index.md
new file mode 100644
index 00000000..75a47358
--- /dev/null
+++ b/docs/reference/src/api/aio_provider/index.md
@@ -0,0 +1,21 @@
+# Asynchronous I/O for Providers
+
+I/O providers perform the operations that are linked to
+an [`nng_aio`](../aio/index.md) object, on behalf of applications
+that submit requests for the same operations.
+
+Most applications will not use the functions listed here.
+Applications that implement their own HTTP handler functions, or
+custom transport providers, might make use of these functions.
+
+In addition to these functions, I/O providers may utilize the
+other consumer functions for [Aysnchronous I/O](../aio/index.md).
+
+## See Also
+
+[nng_aio_begin()](nng_aio_begin.md),
+[nng_aio_defer()](nng_aio_defer.md),
+[nng_aio_finish()](nng_aio_finish.md),
+[nng_aio_get_input()](nng_aio_get_input.md),
+[nng_aio_set_output()](nng_aio_set_output.md),
+[Asynchronous I/O](../aio/index.md)
diff --git a/docs/reference/src/api/nng_aio_begin.md b/docs/reference/src/api/aio_provider/nng_aio_begin.md
index da817091..8e342b26 100644
--- a/docs/reference/src/api/nng_aio_begin.md
+++ b/docs/reference/src/api/aio_provider/nng_aio_begin.md
@@ -39,9 +39,6 @@ exactly once, when the operation is complete or canceled.
 
 ## SEE ALSO
 
-[nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_cancel()](nng_aio_cancel.md),
+[nng_aio_cancel()](../aio/nng_aio_cancel.md),
 [nng_aio_defer()](nng_aio_defer.md),
-[nng_aio_finish()](nng_aio_finish.md),
-[nng_aio_result()](nng_aio_result.md),
-[nng_aio](nng_aio.md)
+[nng_aio_finish()](nng_aio_finish.md)
diff --git a/docs/reference/src/api/nng_aio_defer.md b/docs/reference/src/api/aio_provider/nng_aio_defer.md
index 6b634f42..93d84769 100644
--- a/docs/reference/src/api/nng_aio_defer.md
+++ b/docs/reference/src/api/aio_provider/nng_aio_defer.md
@@ -53,7 +53,6 @@ error code specified by _err_.
 
 ## SEE ALSO
 
-[nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_cancel()](nng_aio_cancel.md),
-[nng_aio_finish()](nng_aio_finish.md),
-[nng_aio](nng_aio.md)
+[nng_aio_alloc()](../aio/nng_aio_alloc.md),
+[nng_aio_cancel()](../aio/nng_aio_cancel.md),
+[nng_aio_finish()](nng_aio_finish.md)
diff --git a/docs/reference/src/api/nng_aio_finish.md b/docs/reference/src/api/aio_provider/nng_aio_finish.md
index 48a52151..61b1ca42 100644
--- a/docs/reference/src/api/nng_aio_finish.md
+++ b/docs/reference/src/api/aio_provider/nng_aio_finish.md
@@ -16,7 +16,7 @@ void nng_aio_finish(nng_aio *aio, int err);
 
 The `nng_aio_finish()` function marks operation associated with _aio_ as
 complete, with the status _err_.
-This will be the result returned by [`nng_aio_result()`](nng_aio_result.md).
+This will be the result returned by [`nng_aio_result()`](../aio/nng_aio_result.md).
 
 This function causes the callback associated with the _aio_ to called.
 
@@ -33,9 +33,7 @@ This function causes the callback associated with the _aio_ to called.
 
 ## SEE ALSO
 
-[nng_aio_alloc()](nng_aio_alloc.md),
 [nng_aio_begin()](nng_aio_begin.md),
 [nng_aio_cancel()](nng_aio_cancel.md),
 [nng_aio_defer()](nng_aio_defer.md),
-[nng_aio_result()](nng_aio_result.md),
-[nng_aio](nng_aio.md)
+[nng_aio_result()](../aio/nng_aio_result.md)
diff --git a/docs/reference/src/api/nng_aio_get_input.md b/docs/reference/src/api/aio_provider/nng_aio_get_input.md
index 192c82d3..28ecb797 100644
--- a/docs/reference/src/api/nng_aio_get_input.md
+++ b/docs/reference/src/api/aio_provider/nng_aio_get_input.md
@@ -29,7 +29,6 @@ Value previously set, or `NULL`.
 
 ## SEE ALSO
 
-[nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_get_output()](nng_aio_get_output.md),
-[nng_aio_set_input()](nng_aio_set_input.md),
-[nng_aio](nng_aio.md)
+[nng_aio_alloc()](../aio/nng_aio_alloc.md),
+[nng_aio_get_output()](../aio/nng_aio_get_output.md),
+[nng_aio_set_input()](../aio/nng_aio_set_input.md)
diff --git a/docs/reference/src/api/nng_aio_set_output.md b/docs/reference/src/api/aio_provider/nng_aio_set_output.md
index c3c86440..6a79e429 100644
--- a/docs/reference/src/api/nng_aio_set_output.md
+++ b/docs/reference/src/api/aio_provider/nng_aio_set_output.md
@@ -33,5 +33,4 @@ the [`nng_aio_get_output()`](nng_aio_get_output.md) function.
 
 ## SEE ALSO
 
-[nng_aio_get_output(3)](nng_aio_get_output.md),
-[nng_aio](nng_aio.md)
+[nng_aio_get_output(3)](../aio/nng_aio_get_output.md)
diff --git a/docs/reference/src/api/index.md b/docs/reference/src/api/index.md
index 0d1089e3..1541b541 100644
--- a/docs/reference/src/api/index.md
+++ b/docs/reference/src/api/index.md
@@ -1,8 +1,23 @@
 # API Reference
 
-This section documents the functions and data structures that make up
+This chapter documents the functions and data structures that make up
 the _NNG_ programming interface.
 
 > [!NOTE]
 > Interfaces not documented here are not considered public or stable,
 > and they may be removed or altered in incompatible ways at any time.
+
+We have organized the reference material along general functional areas.
+They are:
+
+- [Asynchronous I/O](aio/index.md)
+- [Asynchronous I/O for Providers](aio_provider/index.md)
+- General Utility Functions
+- Scalability Protocol Sockets
+- Scalability Protocol Contexts
+- Concurrency / Multi-threading
+- HTTP Server
+- HTTP Client
+- Streaming API
+- Statistics API
+- Legacy Compatibility