aio: nng_aio_defer replaced by nng_aio_start

This represents an API change, and we remove the nng_aio_begin
function as well, introducing the lightweight nng_aio_reset instead.

6 files changed, 55 insertions, 89 deletions

diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 65ecac55..36117614 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -160,11 +160,11 @@ The following functions are used in the asynchronous model:
 |===
 // |xref:nng_aio_abort.3.adoc[nng_aio_abort()]|abort asynchronous I/O operation
 // |xref:nng_aio_alloc.3.adoc[nng_aio_alloc()]|allocate asynchronous I/O handle
-|xref:nng_aio_begin.3.adoc[nng_aio_begin()]|begin asynchronous I/O operation
+|xref:nng_aio_reset.3.adoc[nng_aio_reset()]|reset asynchronous I/O operation
 // |xref:nng_aio_busy.3.adoc[nng_aio_busy()]|test if asynchronous I/O is busy
 // |xref:nng_aio_cancel.3.adoc[nng_aio_cancel()]|cancel asynchronous I/O operation
 // |xref:nng_aio_count.3.adoc[nng_aio_count()]|return number of bytes transferred
-|xref:nng_aio_defer.3.adoc[nng_aio_defer()]|defer asynchronous I/O operation
+|xref:nng_aio_start.3.adoc[nng_aio_start()]|start asynchronous I/O operation
 |xref:nng_aio_finish.3.adoc[nng_aio_finish()]|finish asynchronous I/O operation
 // |xref:nng_aio_free.3.adoc[nng_aio_free()]|free asynchronous I/O handle
 |xref:nng_aio_get_input.3.adoc[nng_aio_get_input()]|return input parameter
diff --git a/docs/man/nng_aio_begin.3.adoc b/docs/man/nng_aio_begin.3.adoc
deleted file mode 100644
index 30a73648..00000000
--- a/docs/man/nng_aio_begin.3.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-= nng_aio_begin(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_begin - begin asynchronous I/O operation
-
-== SYNOPSIS
-
-[source, 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
-by the caller asynchronously.
-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 xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] is called for the _aio_
-exactly once, when the operation is complete or canceled.
-
-NOTE: 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
-
-[horizontal]
-`true`:: The operation has been started.
-`false`:: The operation cannot be started.
-
-== 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_defer.3.adoc[nng_aio_defer(3)],
-xref:nng_aio_finish.3.adoc[nng_aio_finish(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_finish.3.adoc b/docs/man/nng_aio_finish.3.adoc
index 91ad188e..bb0791b8 100644
--- a/docs/man/nng_aio_finish.3.adoc
+++ b/docs/man/nng_aio_finish.3.adoc
@@ -52,9 +52,9 @@ None.
 
 [.text-left]
 xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)],
-xref:nng_aio_begin.3.adoc[nng_aio_begin(3)],
+xref:nng_aio_reset.3.adoc[nng_aio_reset(3)],
 xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)],
-xref:nng_aio_defer.3.adoc[nng_aio_defer(3)],
+xref:nng_aio_start.3.adoc[nng_aio_start(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_reset.3.adoc b/docs/man/nng_aio_reset.3.adoc
new file mode 100644
index 00000000..cb0feec0
--- /dev/null
+++ b/docs/man/nng_aio_reset.3.adoc
@@ -0,0 +1,42 @@
+= nng_aio_reset(3)
+//
+// Copyright 2024 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_reset - reset asynchronous I/O operation
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+void nng_aio_reset(nng_aio *aio);
+----
+
+== DESCRIPTION
+
+The `nng_aio_reset()` is used by providers to reset certain fields in the _aio_.
+This should be done before performing any operations on _aio_.
+
+NOTE: 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
+
+[.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_start.3.adoc[nng_aio_start(3)],
+xref:nng_aio_finish.3.adoc[nng_aio_finish(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_defer.3.adoc b/docs/man/nng_aio_start.3.adoc
index 5664a6df..82dbde23 100644
--- a/docs/man/nng_aio_defer.3.adoc
+++ b/docs/man/nng_aio_start.3.adoc
@@ -1,6 +1,6 @@
-= nng_aio_defer(3)
+= nng_aio_start(3)
 //
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2024 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
@@ -11,7 +11,7 @@
 
 == NAME
 
-nng_aio_defer - defer asynchronous I/O operation
+nng_aio_start - start asynchronous I/O operation
 
 == SYNOPSIS
 
@@ -21,18 +21,18 @@ nng_aio_defer - defer asynchronous I/O operation
 
 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);
+void nng_aio_start(nng_aio *aio, nng_aio_cancelfn fn, void *arg);
 ----
 
 == DESCRIPTION
 
-The `nng_aio_defer()` function marks operation associated with _aio_ as
+The `nng_aio_started()` function marks operation associated with _aio_ as
 being deferred for asynchronous completion, and also registers a cancellation
 function _fn_ and associated argument _arg_, thereby
 permitting the operation to be canceled.
 
 If the _aio_ is being canceled, the cancellation routine _fn_ will be called
-with the _aio_, the _arg_ specified by `nng_aio_defer()`, and an error
+with the _aio_, the _arg_ specified by `nng_aio_start()`, and an error
 value in _err_, which is the reason that the operation is being canceled.
 
 The operation may not be cancelable; for example it may have already been
@@ -56,17 +56,9 @@ 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 should not bother to call `nng_aio_defer()`,
+deferred, the provider should not bother to call `nng_aio_start()`,
 although it is harmless if it does.
 
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
 == SEE ALSO
 
 [.text-left]
diff --git a/docs/man/nng_http_handler_alloc.3http.adoc b/docs/man/nng_http_handler_alloc.3http.adoc
index 7795bbf5..9291fd56 100644
--- a/docs/man/nng_http_handler_alloc.3http.adoc
+++ b/docs/man/nng_http_handler_alloc.3http.adoc
@@ -98,11 +98,7 @@ then a generic 500 response will be created and
 sent, if possible, and the connection will be closed.
 
 The _aio_ may be scheduled for deferred completion using the
-xref:nng_aio_defer.3.adoc[`nng_aio_defer()`] function.
-
-NOTE: The callback function should *NOT* call
-xref:nng_aio_begin.3.adoc[`nng_aio_begin()`],
-as that will already have been done by the server framework.
+xref:nng_aio_start.3.adoc[`nng_aio_start()`] function.
 
 === Directory Handler
 
@@ -181,7 +177,7 @@ These functions return 0 on success, and non-zero otherwise.
 == SEE ALSO
 
 [.text-left]
-xref:nng_aio_defer.3.adoc[nng_aio_defer(3)],
+xref:nng_aio_start.3.adoc[nng_aio_start(3)],
 xref:nng_aio_finish.3.adoc[nng_aio_finish(3)],
 xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)],
 xref:nng_aio_set_output.3.adoc[nng_aio_set_output(3)],