diff options
| -rw-r--r-- | docs/ref/SUMMARY.md | 5 | ||||
| -rw-r--r-- | docs/ref/api/aio/aio_cancel.md | 95 | ||||
| -rw-r--r-- | docs/ref/api/aio/nng_aio.md (renamed from docs/man/nng_aio.5.adoc) | 61 |
3 files changed, 80 insertions, 81 deletions
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 5813961d..a2572715 100644 --- a/docs/ref/SUMMARY.md +++ b/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) diff --git a/docs/ref/api/aio/aio_cancel.md b/docs/ref/api/aio/aio_cancel.md index 8d4e904b..118c9b5a 100644 --- a/docs/ref/api/aio/aio_cancel.md +++ b/docs/ref/api/aio/aio_cancel.md @@ -1,55 +1,54 @@ -= nng_aio_abort(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. -// +# 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 diff --git a/docs/man/nng_aio.5.adoc b/docs/ref/api/aio/nng_aio.md index d2b10324..0fdb6ca1 100644 --- a/docs/man/nng_aio.5.adoc +++ b/docs/ref/api/aio/nng_aio.md @@ -1,58 +1,49 @@ -= nng_aio(5) -// -// 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. -// +# 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 |