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/man/nng_aio.5.adoc | 70 ------------------------------- docs/ref/SUMMARY.md | 5 +++ docs/ref/api/aio/aio_cancel.md | 95 +++++++++++++++++++++--------------------- docs/ref/api/aio/nng_aio.md | 65 +++++++++++++++++++++++++++++ 4 files changed, 117 insertions(+), 118 deletions(-) delete mode 100644 docs/man/nng_aio.5.adoc create mode 100644 docs/ref/api/aio/nng_aio.md (limited to 'docs') diff --git a/docs/man/nng_aio.5.adoc b/docs/man/nng_aio.5.adoc deleted file mode 100644 index d2b10324..00000000 --- a/docs/man/nng_aio.5.adoc +++ /dev/null @@ -1,70 +0,0 @@ -= nng_aio(5) -// -// 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 - asynchronous I/O handle - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_aio nng_aio; ----- - -== DESCRIPTION - -An `nng_aio`(((aio))) is an opaque structure used in conjunction with -((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 xref:nng_aio_cancel.3.adoc[`nng_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()`]). - -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()`]. - -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()`]. - -== 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)], -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)], -xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], -xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], -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)] 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. -// 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