From 8f42f78490fd14b2e6d46d09ec395fbdad5495ce Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 19 Oct 2024 09:40:15 -0700 Subject: Conversion of nng_aio to mdbook in progress --- docs/ref/api/aio/aio_cancel.md | 95 +++++++++++++++++++++--------------------- docs/ref/api/aio/nng_aio.md | 65 +++++++++++++++++++++++++++++ 2 files changed, 112 insertions(+), 48 deletions(-) create mode 100644 docs/ref/api/aio/nng_aio.md (limited to 'docs/ref/api') 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. -// 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. -// +# aio_cancel -== NAME +## NAME -nng_aio_abort - abort asynchronous I/O operation +aio_cancel --- canceling asynchronous I/O -== SYNOPSIS +## SYNOPSIS -[source, c] ----- +```c #include 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/ref/api/aio/nng_aio.md b/docs/ref/api/aio/nng_aio.md new file mode 100644 index 00000000..0fdb6ca1 --- /dev/null +++ b/docs/ref/api/aio/nng_aio.md @@ -0,0 +1,65 @@ +# nng_aio + +## NAME + +nng_aio - asynchronous I/O handle + +## SYNOPSIS + +```c +#include + +typedef struct nng_aio nng_aio; +``` + +## DESCRIPTION + +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. +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 [`nng_aio_cancel`][aio_cancel]), as well setting a maximum +timeout for them to complete within +(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 [`nng_aio_wait`][nng_aio_wait]. + +These structures are created using [`nng_aio_alloc`][nng_aio_alloc], +and destroyed using [`nng_aio_free`][nng_aio_free]. + +## SEE ALSO + +[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] + + + +[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 -- cgit v1.2.3-70-g09d2