Conversion of nng_aio to mdbook in progress

docs/ref/SUMMARY.md

@@ -13,6 +13,11 @@
     - [nng_msg_header](./api/msg/nng_msg_header.md)
     - [nng_msg_pipe](./api/msg/nng_msg_pipe.md)
 
+  - [Asynchronous I/O Operations](./api/aio/index.md)
+
+    - [nng_aio](./api/aio/nng_aio.md)
+    - [aio_cancel](./api/aio/aio_cancel.md)
+
   - [Threading and Synchronization](./api/thr/index.md)
 
     - [nng_cv](./api/thr/nng_cv.md)

docs/ref/api/aio/aio_cancel.md

@@ -1,55 +1,54 @@
-= nng_aio_abort(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <[email protected]>
-// Copyright 2018 Capitar IT Group BV <[email protected]>
-//
-// 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.
-//
+# aio_cancel
 
-== NAME
+## NAME
 
-nng_aio_abort - abort asynchronous I/O operation
+aio_cancel --- canceling asynchronous I/O
 
-== SYNOPSIS
+## SYNOPSIS
 
-[source, c]
-----
+```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
-xref:nng_aio_result.3.adoc[`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.
-
-== 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.7.adoc[nng(7)]
+void nng_aio_cancel(nng_aio *aio);
+void nng_aio_stop(nng_aio *aio);
+```
+
+## DESCRIPTION
+
+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`][nng_aio_result] will return _err_.
+
+The {{i:`nng_aio_cancel`}} function acts like `nng_aio_abort`, but uses the error code
+{{i:`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`][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`][nng_aio_free],
+> particularly if the callbacks might attempt to reschedule further operations.
+
+## SEE ALSO
+
+[nng_aio][nng_aio],
+[nng_aio_result][nng_aio_result],
+[nng_aio_free][nng_aio_free]
+
+[nng_aio]: TODO.md
+[nng_aio_begin]: TODO.md
+[nng_aio_result]: TODO.md
+[nng_aio_free]: TODO.md

docs/man/nng_aio.5.adoc → docs/ref/api/aio/nng_aio.md

@@ -1,58 +1,49 @@
-= nng_aio(5)
-//
-// Copyright 2018 Staysail Systems, Inc. <[email protected]>
-// Copyright 2018 Capitar IT Group BV <[email protected]>
-//
-// 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.
-//
+# nng_aio
 
-== NAME
+## NAME
 
 nng_aio - asynchronous I/O handle
 
-== SYNOPSIS
+## SYNOPSIS
 
-[source, c]
-----
+```c
 #include <nng/nng.h>
 
 typedef struct nng_aio nng_aio;
-----
+```
 
-== DESCRIPTION
+## DESCRIPTION
 
-An `nng_aio`(((aio))) is an opaque structure used in conjunction with
-((asynchronous I/O)) operations.
+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.
+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 xref:nng_aio_cancel.3.adoc[`nng_aio_cancel()`]), as well setting a maximum
+(see [`nng_aio_cancel`][aio_cancel]), as well setting a maximum
 timeout for them to complete within
-(see xref:nng_aio_set_timeout.3.adoc[`nng_aio_set_timeout()`]).
+(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 xref:nng_aio_wait.3.adoc[`nng_aio_wait()`].
+complete using [`nng_aio_wait`][nng_aio_wait].
 
-These structures are created using the xref:nng_aio_alloc.3.adoc[`nng_aio_alloc()`],
-and destroyed using xref:nng_aio_free.3.adoc[`nng_aio_free()`].
+These structures are created using [`nng_aio_alloc`][nng_aio_alloc],
+and destroyed using [`nng_aio_free`][nng_aio_free].
 
-== SEE ALSO
+## 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_cancel.3.adoc[nng_aio_cancel(3)],
+[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)],
@@ -62,9 +53,13 @@ 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)]
+-->
+
+[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