I/O provider reorg

6 files changed, 244 insertions, 0 deletions

diff --git a/docs/reference/src/iop/index.md b/docs/reference/src/iop/index.md
new file mode 100644
index 00000000..677ac347
--- /dev/null
+++ b/docs/reference/src/iop/index.md
@@ -0,0 +1,23 @@
+# 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],
+[nng_aio_defer][nng_aio_defer],
+[nng_aio_finish][nng_aio_finish],
+[nng_aio_get_input][nng_aio_get_input],
+[nng_aio_set_output][nng_aio_set_output],
+[Asynchronous I/O][aio]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/iop/nng_aio_begin.md b/docs/reference/src/iop/nng_aio_begin.md
new file mode 100644
index 00000000..39f8cc4b
--- /dev/null
+++ b/docs/reference/src/iop/nng_aio_begin.md
@@ -0,0 +1,46 @@
+# nng_aio_begin
+
+## NAME
+
+nng_aio_begin --- begin asynchronous I/O operation
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+bool nng_aio_begin(nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_aio_begin()` function is called by the I/O provider to indicate that
+it is going to process the operation.
+
+The function may return `false`, indicating that the _aio_ has been closed.
+In this case the provider should abandon the operation and do nothing else.
+
+This operation should be called at the start of any I/O operation, and must
+be called not more than once for a given I/O operation on a given _aio_.
+
+Once this function is called, if `true` is returned, then the provider MUST
+guarantee that [`nng_aio_finish()`][nng_aio_finish] is called for the _aio_
+exactly once, when the operation is complete or canceled.
+
+> [!TIP]
+> This function is only for I/O providers (those actually performing
+> the operation such as HTTP handler functions or transport providers); ordinary
+> users of the _aio_ should not call this function.
+
+## RETURN VALUES
+
+- `true`: The operation has been started.
+- `false`: The operation cannot be started.
+
+## SEE ALSO
+
+[nng_aio_cancel][nng_aio_cancel],
+[nng_aio_defer][nng_aio_defer],
+[nng_aio_finish][nng_aio_finish]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/iop/nng_aio_defer.md b/docs/reference/src/iop/nng_aio_defer.md
new file mode 100644
index 00000000..df43d7ca
--- /dev/null
+++ b/docs/reference/src/iop/nng_aio_defer.md
@@ -0,0 +1,60 @@
+# nng_aio_defer
+
+## NAME
+
+nng_aio_defer --- defer asynchronous I/O operation
+
+## SYNOPSIS
+
+```c
+#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);
+```
+
+## DESCRIPTION
+
+The `nng_aio_defer()` function marks operation associated with _aio_ as
+being deferred for asynchronous completion, registering a cancellation
+function _fn_ and associated argument _arg_.
+This permits the operation to be canceled.
+
+If the _aio_ is canceled, the cancellation routine _fn_ will be called
+with the _aio_, the _arg_ specified by `nng_aio_defer()`, and an error
+value in _err_, which is the reason that the operation is being canceled.
+
+At any given time, the operation may not be cancelable.
+For example it may have already been
+completed, or be in a state where it is no longer possible to unschedule it.
+In this case, the _cancelfn_ should just return without making any changes.
+
+If the cancellation routine successfully canceled the operation, it should
+ensure that [`nng_aio_finish()`][nng_aio_finish] is called, with the
+error code specified by _err_.
+
+> [!IMPORTANT]
+> It is mandatory that I/O providers call [`nng_aio_finish()`][nng_aio_finish] _*exactly once*_ when they are finished with the operation.
+
+> [!IMPORTANT]
+> 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.
+
+> [!TIP]
+> For operations that complete synchronously, without any need to be
+> deferred, the provider need not call `nng_aio_defer()`.
+
+> [!TIP]
+> This function is only for I/O providers (those actually performing
+> the operation such as HTTP handler functions or transport providers); ordinary
+> users of the _aio_ should not call this function.
+
+## SEE ALSO
+
+[nng_aio_alloc][nng_aio_alloc],
+[nng_aio_cancel][nng_aio_cancel],
+[nng_aio_finish][nng_aio_finish]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/iop/nng_aio_finish.md b/docs/reference/src/iop/nng_aio_finish.md
new file mode 100644
index 00000000..da922f76
--- /dev/null
+++ b/docs/reference/src/iop/nng_aio_finish.md
@@ -0,0 +1,41 @@
+# nng_aio_finish
+
+## NAME
+
+nng_aio_finish --- finish asynchronous I/O operation
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void nng_aio_finish(nng_aio *aio, int err);
+```
+
+## DESCRIPTION
+
+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].
+
+This function causes the callback associated with the _aio_ to called.
+
+> [!IMPORTANT]
+> It is mandatory that operation providers call this function
+> _exactly once_ when they are finished with the operation.
+> After calling this function, the provider _must not_ perform any
+> further accesses to the _aio_.
+
+> [!TIP]
+> This function is only for I/O providers (those actually performing
+> the operation such as HTTP handler functions or transport providers); ordinary
+> users of the _aio_ should not have any need for this function.
+
+## SEE ALSO
+
+[nng_aio_begin][nng_aio_begin],
+[nng_aio_cancel][nng_aio_cancel],
+[nng_aio_defer][nng_aio_defer],
+[nng_aio_result][nng_aio_result]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/iop/nng_aio_get_input.md b/docs/reference/src/iop/nng_aio_get_input.md
new file mode 100644
index 00000000..28f798bd
--- /dev/null
+++ b/docs/reference/src/iop/nng_aio_get_input.md
@@ -0,0 +1,36 @@
+# nng_aio_get_input
+
+## NAME
+
+nng_aio_get_input --- return input parameter
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void *nng_aio_get_input(nng_aio *aio, unsigned int index);
+```
+
+## DESCRIPTION
+
+The `nng_aio_get_input()` function returns the value of the input parameter
+previously set at _index_ on _aio_ with the
+[`nng_aio_set_input()`][nng_aio_set_input]function.
+
+The valid values of _index_ range from zero (0) to three (3), as no operation
+currently defined can accept more than four parameters.
+If the index supplied is outside of this range,
+or if the input parameter was not previously set, then `NULL` is returned.
+
+## RETURN VALUES
+
+Value previously set, or `NULL`.
+
+## SEE ALSO
+
+[nng_aio_alloc][nng_aio_alloc],
+[nng_aio_get_output][nng_aio_get_output],
+[nng_aio_set_input][nng_aio_set_input]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/iop/nng_aio_set_output.md b/docs/reference/src/iop/nng_aio_set_output.md
new file mode 100644
index 00000000..568d765d
--- /dev/null
+++ b/docs/reference/src/iop/nng_aio_set_output.md
@@ -0,0 +1,38 @@
+# nng_aio_set_output
+
+## NAME
+
+nng_aio_set_output --- set output result
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void nng_aio_set_output(nng_aio *aio, unsigned int index, void *result);
+```
+
+## DESCRIPTION
+
+The `nng_aio_set_output()` function sets the output result at _index_
+to _result_ for the asynchronous operation associated with _aio_.
+
+The type and semantics of output results are determined by specific
+operations; the operation must supply appropriate output results when
+the operation completes successfully.
+
+The valid values of _index_ range from zero (0) to three (3), as no operation
+currently defined can return more than four results.
+
+> [!NOTE]
+> Note that attempts to set results with an _index_ greater than
+> three (3) will be ignored.
+
+An output result set with this function may be retrieved later with
+the [`nng_aio_get_output()`][nng_aio_get_output] function.
+
+## SEE ALSO
+
+[nng_aio_get_output][nng_aio_get_output]
+
+{{#include ../refs.md}}