From 1ad7f88e0c58285c9e1cad9448d5a1fcfa7a07f1 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Thu, 26 Dec 2024 14:10:09 -0800 Subject: 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. --- docs/man/libnng.3.adoc | 4 +- docs/man/nng_aio_begin.3.adoc | 64 ------------------------ docs/man/nng_aio_defer.3.adoc | 78 ------------------------------ docs/man/nng_aio_finish.3.adoc | 4 +- docs/man/nng_aio_reset.3.adoc | 42 ++++++++++++++++ docs/man/nng_aio_start.3.adoc | 70 +++++++++++++++++++++++++++ docs/man/nng_http_handler_alloc.3http.adoc | 8 +-- 7 files changed, 118 insertions(+), 152 deletions(-) delete mode 100644 docs/man/nng_aio_begin.3.adoc delete mode 100644 docs/man/nng_aio_defer.3.adoc create mode 100644 docs/man/nng_aio_reset.3.adoc create mode 100644 docs/man/nng_aio_start.3.adoc (limited to 'docs/man') 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. -// Copyright 2018 Capitar IT Group BV -// -// 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 - -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_defer.3.adoc b/docs/man/nng_aio_defer.3.adoc deleted file mode 100644 index 5664a6df..00000000 --- a/docs/man/nng_aio_defer.3.adoc +++ /dev/null @@ -1,78 +0,0 @@ -= nng_aio_defer(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// 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_defer - defer asynchronous I/O operation - -== SYNOPSIS - -[source, c] ----- -#include - -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, 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 -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 -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 xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] is called, with the -error code specified by _err_. - -IMPORTANT: It is mandatory that I/O providers call -xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] -*EXACTLY ONCE* when they are finished with the operation. - -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. - -NOTE: 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 should not bother to call `nng_aio_defer()`, -although it is harmless if it does. - -== 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_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. +// +// 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 + +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_start.3.adoc b/docs/man/nng_aio_start.3.adoc new file mode 100644 index 00000000..82dbde23 --- /dev/null +++ b/docs/man/nng_aio_start.3.adoc @@ -0,0 +1,70 @@ += nng_aio_start(3) +// +// Copyright 2024 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_start - start asynchronous I/O operation + +== SYNOPSIS + +[source, c] +---- +#include + +typedef void (*nng_aio_cancelfn)(nng_aio *aio, void *arg, int err); + +void nng_aio_start(nng_aio *aio, nng_aio_cancelfn fn, void *arg); +---- + +== DESCRIPTION + +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_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 +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 xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] is called, with the +error code specified by _err_. + +IMPORTANT: It is mandatory that I/O providers call +xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] +*EXACTLY ONCE* when they are finished with the operation. + +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. + +NOTE: 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 should not bother to call `nng_aio_start()`, +although it is harmless if it does. + +== 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_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_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)], -- cgit v1.2.3-70-g09d2