From 0974ccc48f80ed4cf29ace7255341c2c1284f448 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 30 Mar 2024 20:44:29 -0700 Subject: Aio moved --- docs/reference/src/aio/index.md | 76 +++++++++++++++++++++++++++ docs/reference/src/aio/nng_aio_abort.md | 37 +++++++++++++ docs/reference/src/aio/nng_aio_alloc.md | 75 ++++++++++++++++++++++++++ docs/reference/src/aio/nng_aio_busy.md | 43 +++++++++++++++ docs/reference/src/aio/nng_aio_cancel.md | 39 ++++++++++++++ docs/reference/src/aio/nng_aio_count.md | 46 ++++++++++++++++ docs/reference/src/aio/nng_aio_free.md | 36 +++++++++++++ docs/reference/src/aio/nng_aio_get_msg.md | 32 +++++++++++ docs/reference/src/aio/nng_aio_get_output.md | 42 +++++++++++++++ docs/reference/src/aio/nng_aio_result.md | 48 +++++++++++++++++ docs/reference/src/aio/nng_aio_set_input.md | 44 ++++++++++++++++ docs/reference/src/aio/nng_aio_set_iov.md | 42 +++++++++++++++ docs/reference/src/aio/nng_aio_set_msg.md | 30 +++++++++++ docs/reference/src/aio/nng_aio_set_timeout.md | 55 +++++++++++++++++++ docs/reference/src/aio/nng_aio_stop.md | 40 ++++++++++++++ docs/reference/src/aio/nng_aio_wait.md | 35 ++++++++++++ 16 files changed, 720 insertions(+) create mode 100644 docs/reference/src/aio/index.md create mode 100644 docs/reference/src/aio/nng_aio_abort.md create mode 100644 docs/reference/src/aio/nng_aio_alloc.md create mode 100644 docs/reference/src/aio/nng_aio_busy.md create mode 100644 docs/reference/src/aio/nng_aio_cancel.md create mode 100644 docs/reference/src/aio/nng_aio_count.md create mode 100644 docs/reference/src/aio/nng_aio_free.md create mode 100644 docs/reference/src/aio/nng_aio_get_msg.md create mode 100644 docs/reference/src/aio/nng_aio_get_output.md create mode 100644 docs/reference/src/aio/nng_aio_result.md create mode 100644 docs/reference/src/aio/nng_aio_set_input.md create mode 100644 docs/reference/src/aio/nng_aio_set_iov.md create mode 100644 docs/reference/src/aio/nng_aio_set_msg.md create mode 100644 docs/reference/src/aio/nng_aio_set_timeout.md create mode 100644 docs/reference/src/aio/nng_aio_stop.md create mode 100644 docs/reference/src/aio/nng_aio_wait.md (limited to 'docs/reference/src/aio') diff --git a/docs/reference/src/aio/index.md b/docs/reference/src/aio/index.md new file mode 100644 index 00000000..665a91e3 --- /dev/null +++ b/docs/reference/src/aio/index.md @@ -0,0 +1,76 @@ +# Aysnchronous I/O + +_NNG_ provides rich support for {{i:asynchronous I/O}}. +This allows applications to achieve high levels of concurrency with a +minimum of fuss, optimized for the platform. + +Asynchronous I/O is performed without blocking calling application +threads, so they may continue to perform other work. + +## AIO Handles + +Applications create an `nng_aio` object with a function to call when +the operation is done (along with a pointer to application private data), +then submit the operation. + +These `nng_aio` objects are created using the [`nng_aio_alloc()`][nng_aio_alloc], +and destroyed using [`nng_aio_free()`][nng_aio_free]. + +The `nng_aio` object itself is declared like this: + +```c +#include + +typedef struct nng_aio nng_aio; +``` + +Every asynchronous operation uses its own instance an `nng_aio`, and each +`nng_aio` can only be used with a single operation at a time. + +> [!IMPORTANT] +> Attempting to submit an operation using an `nng_aio` that is already +> in use for another operation will crash the application. +> However, it is possible to submit another operation on the `nng_aio` from +> the callback associated with the same `nng_aio`. + +When the operation is complete, whether successfully +or otherwise, the callback function is executed. +The callback will be executed exactly once. + +## Cancellation + +The asynchronous I/O framework also supports cancellation of +operations that are already in progress +(see [`nng_aio_cancel()`][nng_aio_cancel]), as well setting a maximum +timeout for them to complete within +(see [`nng_aio_set_timeout()`][nng_aio_set_timeout]). + +## Waiting for Completion + +It is also possible to initiate an asynchronous operation, and wait for it to +complete [`nng_aio_wait()`][nng_aio_wait]. + +> [!IMPORTANT] +> Applications must never call [`nng_aio_wait()`][nng_aio_wait] or +> [`nng_aio_stop()`][nng_aio_stop] from a callback registered to +> an `nng_aio` object. Doing so can lead to a deadlock. + +## See Also + +[nng_aio_abort][nng_aio_abort], +[nng_aio_alloc][nng_aio_alloc], +[nng_aio_cancel][nng_aio_cancel], +[nng_aio_count][nng_aio_count], +[nng_aio_free][nng_aio_free], +[nng_aio_get_input][nng_aio_get_input], +[nng_aio_get_msg][nng_aio_get_msg], +[nng_aio_get_output][nng_aio_get_output], +[nng_aio_result][nng_aio_result], +[nng_aio_set_input][nng_aio_set_input], +[nng_aio_set_iov][nng_aio_set_iov], +[nng_aio_set_msg][nng_aio_set_msg], +[nng_aio_set_timeout][nng_aio_set_timeout], +[nng_aio_stop][nng_aio_stop], +[nng_aio_wait][nng_aio_wait] + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_abort.md b/docs/reference/src/aio/nng_aio_abort.md new file mode 100644 index 00000000..74804a5c --- /dev/null +++ b/docs/reference/src/aio/nng_aio_abort.md @@ -0,0 +1,37 @@ +# nng_aio_abort + +## NAME + +nng_aio_abort --- abort asynchronous I/O operation + +## SYNOPSIS + +```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 +[`nng_aio_result()`][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. + +## SEE ALSO + +[nng_aio_alloc][nng_aio_alloc], +[nng_aio_cancel][nng_aio_cancel], +[nng_aio_result][nng_aio_result] + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_alloc.md b/docs/reference/src/aio/nng_aio_alloc.md new file mode 100644 index 00000000..988f4bf2 --- /dev/null +++ b/docs/reference/src/aio/nng_aio_alloc.md @@ -0,0 +1,75 @@ +# nng_aio_alloc + +## NAME + +nng_aio_alloc --- allocate asynchronous I/O handle + +## SYNOPSIS + +```c +#include + +int nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg); +``` + +## DESCRIPTION + +The `nng_aio_alloc()` function allocates a handle for {{i:asynchronous I/O}} +operations, and stores a pointer to it in the location referenced by _aiop_. +The handle is initialized with a completion {{i:callback}} of _callb_, +which will be executed when an associated asynchronous operation finishes. +It will be called with the argument _arg_. + +> [!IMPORTANT] +> The callback _callb_ must not perform any blocking operations, and +> must complete its execution quickly. If _callb_ does block, this can +> lead ultimately to an apparent "hang" or deadlock in the application. +> This also means you should avoid operations such as allocating new objects, +> which also means opening or closing sockets, dialers, and so forth. + +> [!TIP] +> If more complex or blocking work needs to be performed by _callb_, a separate +> thread can be used, along with a [condition variable][nng_cv_alloc] +> which can be signaled by the callback. + +Asynchronous I/O operations all take an [`nng_aio`](index.md) +handle such as allocated by this function. +Such operations are usually started by a function that returns immediately. +The operation is then run asynchronously, and completes sometime later. +When that operation is complete, the callback supplied here is called, +and that callback is able to determine the result of the operation using +[`nng_aio_result()`][nng_aio_result], [`nng_aio_count()`][nng_aio_count], +and [`nng_aio_get_output()`][nng_aio_get_output]. + +It is possible to wait synchronously for an otherwise asynchronous operation +by using the function [`nng_aio_wait()`][nng_aio_wait]. +In that case, it is permissible for _callb_ and _arg_ to both be `NULL`. +Note that if these are `NULL`, then it will not be possible to determine when the +operation is complete except by calling the aforementioned +[`nng_aio_wait()`][nng_aio_wait]. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient free memory to perform the operation. + +## SEE ALSO + +[nng_aio_abort][nng_aio_abort], +[nng_aio_cancel][nng_aio_cancel], +[nng_aio_count][nng_aio_count], +[nng_aio_free][nng_aio_free], +[nng_aio_get_msg][nng_aio_get_msg], +[nng_aio_get_output][nng_aio_get_output], +[nng_aio_result][nng_aio_result], +[nng_aio_set_input][nng_aio_set_input], +[nng_aio_set_iov][nng_aio_set_iov], +[nng_aio_set_msg][nng_aio_set_msg], +[nng_aio_set_timeout][nng_aio_set_timeout], +[nng_aio_stop][nng_aio_stop], +[nng_aio_wait][nng_aio_wait] + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_busy.md b/docs/reference/src/aio/nng_aio_busy.md new file mode 100644 index 00000000..7aef17fb --- /dev/null +++ b/docs/reference/src/aio/nng_aio_busy.md @@ -0,0 +1,43 @@ +# nng_aio_busy + +## NAME + +nng_aio_busy --- test if asynchronous I/O is busy + +## SYNOPSIS + +```c +#include + +bool nng_aio_busy(nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_aio_busy()` function returns true if the +_aio_ is currently busy performing an asynchronous I/O +operation or is executing a completion callback. + +If no operation has been started, or the operation has +been completed or canceled, and any callback has been +executed, then it returns false. + +This is the same test used internally by +[`nng_aio_wait()`][nng_aio_wait]. + +> [!IMPORTANT] +> Care should be taken to ensure that the _aio_ object is not +> freed when using this function. The caller is responsible for +> coordinating any use of this with any reuse of the _aio_. + +## RETURN VALUES + +True if the _aio_ is busy, false otherwise. + +## SEE ALSO + +[nng_aio_abort][nng_aio_abort], +[nng_aio_alloc][nng_aio_alloc], +[nng_aio_wait][nng_aio_wait] + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_cancel.md b/docs/reference/src/aio/nng_aio_cancel.md new file mode 100644 index 00000000..e3b53d93 --- /dev/null +++ b/docs/reference/src/aio/nng_aio_cancel.md @@ -0,0 +1,39 @@ +# nng_aio_cancel + +## NAME + +nng_aio_cancel --- cancel asynchronous I/O operation + +## SYNOPSIS + +```c +#include + +void nng_aio_cancel(nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_aio_cancel()` 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 +[`nng_aio_result()`][nng_aio_result] will return the error `NNG_ECANCELED`. + +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. + +This function is the same as calling +[`nng_aio_abort()`][nng_aio_abort] with the error `NNG_ECANCELED`. + +## SEE ALSO + +[nng_aio_abort][nng_aio_abort], +[nng_aio_alloc][nng_aio_alloc], +[nng_aio_result][nng_aio_result] + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_count.md b/docs/reference/src/aio/nng_aio_count.md new file mode 100644 index 00000000..1bd06e94 --- /dev/null +++ b/docs/reference/src/aio/nng_aio_count.md @@ -0,0 +1,46 @@ +# nng_aio_count + +## NAME + +nng_aio_count --- return number of bytes transferred + +## SYNOPSIS + +```c +#include + +size_t nng_aio_count(nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_aio_count()` returns the number of bytes transferred by the +asynchronous operation associated with the handle _aio_. + +Some asynchronous operations do not provide meaningful data for this +function; for example operations that establish connections do not +transfer user data (they may transfer protocol data though) -- in this case +this function will generally return zero. + +This function is most useful when used with operations that make use of +of a scatter/gather vector (set by [`nng_aio_set_iov()`][nng_aio_set_iov]). + +> [!NOTE] +> The return value from this function is undefined if the operation +> has not completed yet. +> Either call this from the handle's completion callback, +> or after waiting for the operation to complete with +> [`nng_aio_wait()`][nng_aio_wait]. + +## RETURN VALUES + +The number of bytes transferred by the operation. + +## SEE ALSO + +[nng_aio_alloc][nng_aio_alloc], +[nng_aio_result][nng_aio_result], +[nng_aio_set_iov][nng_aio_set_iov], +[nng_aio_wait][nng_aio_wait] + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_free.md b/docs/reference/src/aio/nng_aio_free.md new file mode 100644 index 00000000..500ec2a6 --- /dev/null +++ b/docs/reference/src/aio/nng_aio_free.md @@ -0,0 +1,36 @@ +# nng_aio_free + +## NAME + +nng_aio_free --- free asynchronous I/O handle + +## SYNOPSIS + +```c +#include + +void nng_aio_free(nng_aio *aio); +void nng_aio_reap(nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_aio_free()` function frees an allocated asynchronous I/O handle. +If any operation is in progress, the operation is canceled, and the +caller is blocked until the operation is completely canceled, to ensure +that it is safe to deallocate the handle and any associated resources. +(This is done by implicitly calling [`nng_aio_stop()`][nng_aio_stop].) + +The `nng_aio_reap()` function is the same as `nng_aio_free()`, but does +its work in a background thread. +This can be useful to discard the _aio_ object from within the callback for the _aio_. + +> [!IMPORTANT] +> Once either of these functions are called, the _aio_ object is invalid and must not be used again. + +## SEE ALSO + +[nng_aio_alloc][nng_aio_alloc], +[nng_aio_stop][nng_aio_stop] + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_get_msg.md b/docs/reference/src/aio/nng_aio_get_msg.md new file mode 100644 index 00000000..33b07981 --- /dev/null +++ b/docs/reference/src/aio/nng_aio_get_msg.md @@ -0,0 +1,32 @@ +# nng_aio_get_msg + +## NAME + +nng_aio_get_msg --- get message from asynchronous receive + +## SYNOPSIS + +```c +#include + +nng_msg *nng_aio_get_msg(nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_aio_get_msg()` function gets any message stored in _aio_ as +either a result of a successful receive +(see [`nng_recv_aio()`][nng_recv_aio]) +or that was previously stored with +[`nng_aio_set_msg()`][nng_aio_set_msg]. + +> [!IMPORTANT] +> The _aio_ must not have an operation in progress. + +## SEE ALSO + +[nng_aio_set_msg][nng_aio_set_msg], +[nng_recv_aio][nng_recv_aio], +[Messages][msg] + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_get_output.md b/docs/reference/src/aio/nng_aio_get_output.md new file mode 100644 index 00000000..a7a82f56 --- /dev/null +++ b/docs/reference/src/aio/nng_aio_get_output.md @@ -0,0 +1,42 @@ +# nng_aio_get_output + +## NAME + +nng_aio_get_output --- return output result + +## SYNOPSIS + +```c +#include + +void *nng_aio_get_output(nng_aio *aio, unsigned int index); +``` + +## DESCRIPTION + +The `nng_aio_get_output()` function returns the output result at _index_ +resulting from the asynchronous operation associated with _aio_. + +The type and semantics of output parameters are determined by specific +operations. + +> [!NOTE] +> If the _index_ does not correspond to a defined output for the operation, +> or the operation did not succeed, then the return value will be `NULL`. + +> [!IMPORTANT] +> It is an error to call this function while the _aio_ is currently +> in use by an active asynchronous operation, or if no operation has been +> performed using the _aio_ yet. + +## RETURN VALUES + +The *index*th output from the operation, or `NULL`. + +## SEE ALSO + +[nng_aio_alloc][nng_aio_alloc], +[nng_aio_set_output](../aio_provider/nng_aio_set_output.md), +[nng_aio_result][nng_aio_result] + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_result.md b/docs/reference/src/aio/nng_aio_result.md new file mode 100644 index 00000000..16cede6a --- /dev/null +++ b/docs/reference/src/aio/nng_aio_result.md @@ -0,0 +1,48 @@ +# nng_aio_result + +## NAME + +nng_aio_result --- return result of asynchronous operation + +## SYNOPSIS + +```c +#include + +int nng_aio_result(nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_aio_result()` returns the result of the operation associated +with the handle _aio_. +If the operation was successful, then 0 is returned. +Otherwise a non-zero error code is returned. + +> [!NOTE] +> The return value from this function is undefined if the operation +> has not completed yet. +> Either call this from the handle's completion +> callback, or after waiting for the operation to complete with +> [`nng_aio_wait()`][nng_aio_wait]. + +## RETURN VALUES + +The result of the operation, either zero on success, or an error +number on failure. + +## ERRORS + +- `NNG_ETIMEDOUT`: The operation timed out. +- `NNG_ECANCELED`: The operation was canceled. + +Various other return values are possible depending on the operation. + +## SEE ALSO + +[nng_aio_abort][nng_aio_abort], +[nng_aio_alloc][nng_aio_alloc], +[nng_aio_wait][nng_aio_wait], +[nng_strerror](../util/nng_strerror.md) + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_set_input.md b/docs/reference/src/aio/nng_aio_set_input.md new file mode 100644 index 00000000..d09ba05f --- /dev/null +++ b/docs/reference/src/aio/nng_aio_set_input.md @@ -0,0 +1,44 @@ +# nng_aio_set_input + +## NAME + +nng_aio_set_input --- set input parameter + +## SYNOPSIS + +```c +#include + +void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param); +``` + +## DESCRIPTION + +The `nng_aio_set_input()` function sets the input parameter at _index_ +to _param_ for the asynchronous operation associated with _aio_. + +The type and semantics of input parameters are determined by specific +operations; the caller must supply appropriate inputs for the operation +to be performed. + +The valid values of _index_ range from zero (0) to three (3), as no operation +currently defined can accept more than four parameters. +(This limit could increase in the future.) + +> [!NOTE] +> If the _index_ does not correspond to a defined input for the operation, +> then this function will have no effect. + +> [!IMPORTANT] +> It is an error to call this function while the _aio_ is currently +> in use by an active asynchronous operation. + +An input parameter set with this function may be retrieved later with +the [`nng_aio_get_input()`][nng_aio_get_input] function. + +## SEE ALSO + +[nng_aio_alloc][nng_aio_alloc], +[nng_aio_get_input][nng_aio_get_input] + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_set_iov.md b/docs/reference/src/aio/nng_aio_set_iov.md new file mode 100644 index 00000000..b8f1a0b5 --- /dev/null +++ b/docs/reference/src/aio/nng_aio_set_iov.md @@ -0,0 +1,42 @@ +# nng_aio_set_iov() + +## NAME + +nng_aio_set_iov --- set scatter/gather vector + +## SYNOPSIS + +```c +#include + +int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov); +``` + +## DESCRIPTION + +The `nng_aio_set_iov()` function sets a {{i:scatter/gather}} vector _iov_ on the handle _aio_. + +The _iov_ is a pointer to an array of _niov_ [`nng_iov`][nng_iov] +structures, which have the following definition: + +```c +typedef struct nng_iov { + void * iov_buf; + size_t iov_len; +}; +``` + +The _iov_ is copied into storage in the _aio_ itself, so that callers may use stack allocated `nng_iov` structures. +The values pointed to by the `iov_buf` members are _not_ copied by this function though. + +A maximum of four (4) `nng_iov` members may be supplied. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_EINVAL`: Value of specified _niov_ is too large. + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_set_msg.md b/docs/reference/src/aio/nng_aio_set_msg.md new file mode 100644 index 00000000..5b4c0e00 --- /dev/null +++ b/docs/reference/src/aio/nng_aio_set_msg.md @@ -0,0 +1,30 @@ +# nng_aio_set_msg() + +## NAME + +nng_aio_set_msg --- set message for asynchronous send + +## SYNOPSIS + +```c +#include + +void nng_aio_set_msg(nng_aio *aio, nng_msg *msg); +``` + +## DESCRIPTION + +The `nng_aio_set_msg()` function sets the message that will be used +for an asynchronous send operation (see +[`nng_send_aio()`][nng_send_aio]). + +> [!IMPORTANT] +> The _aio_ must not have an operation in progress. + +## SEE ALSO + +[nng_aio_get_msg][nng_aio_get_msg], +[nng_send_aio][nng_send_aio], +[Messages][msg] + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_set_timeout.md b/docs/reference/src/aio/nng_aio_set_timeout.md new file mode 100644 index 00000000..f4b18a58 --- /dev/null +++ b/docs/reference/src/aio/nng_aio_set_timeout.md @@ -0,0 +1,55 @@ +# nng_aio_set_timeout + +## NAME + +nng_aio_set_timeout --- set asynchronous I/O timeout + +## SYNOPSIS + +```c +#include + +typedef int nng_duration; +void nng_aio_set_timeout(nng_aio *aio, nng_duration timeout); + +typedef uint64_t nng_time; +void nng_aio_set_expire(nng_aio *aio, nng_time expiration); +``` + +## DESCRIPTION + +The `nng_aio_set_timeout()` function sets a {{ii:timeout}} +for the asynchronous operation associated with _aio_. +This causes a timer to be started when the operation is actually started. +If the timer expires before the operation is completed, then it is +aborted with an error of `NNG_ETIMEDOUT`. +The _timeout_ is specified as a relative number of milliseconds. + +If the timeout is {{i:`NNG_DURATION_INFINITE`}}, then no timeout is used. +If the timeout is {{i:`NNG_DURATION_DEFAULT`}}, then a "default" or socket-specific +timeout is used. +(This is frequently the same as `NNG_DURATION_INFINITE`.) + +The `nng_aio_set_expire()` function is similar to `nng_aio_set_timeout()`, but sets +an absolute expiration time based on the system clock. The _expiration_ +is expressed as a number of milliseconds since some point in the past. +The [`nng_clock()`](../util/nng_clock.md) function can be used to determine +the current value of the clock. + +> [!TIP] +> As most operations involve some context switching, it is usually a good +> idea to allow at least a few tens of milliseconds before timing them out -- +> a too small timeout might not allow the operation to properly begin before +> giving up! + +The value of _timeout_ set for the _aio_ is persistent, so that if the +handle is reused for future operations, it will have the same relative +or absolute timeout. + +## SEE ALSO + +[nng_aio_cancel][nng_aio_cancel], +[nng_aio_result][nng_aio_result], +[nng_clock][nng_clock] + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_stop.md b/docs/reference/src/aio/nng_aio_stop.md new file mode 100644 index 00000000..01e328b1 --- /dev/null +++ b/docs/reference/src/aio/nng_aio_stop.md @@ -0,0 +1,40 @@ +# nng_aio_stop + +## NAME + +nng_aio_stop - stop asynchronous I/O operation + +## SYNOPSIS + +```c +#include + +void nng_aio_stop(nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_aio_stop()` function stops the asynchronous I/O operation +associated with _aio_ by aborting with `NNG_ECANCELED`, and then waits +for it to complete or to be completely aborted, and for the +callback associated with the _aio_ to have completed executing. + +Further calls to +[`nng_aio_begin()`][nng_aio_begin] using this _aio_ will return `false`. + +It is safe to call this for an _aio_, even when no operation is currently +pending for it. + +> [!TIP] +> When multiple asynchronous I/O handles are in use and need to be +> shut down, it is safest to stop all of them, before deallocating any of +> them with [`nng_aio_free()`][nng_aio_free], particularly if the callbacks +> might attempt to reschedule additional operations. + +## SEE ALSO + +[nng_aio_cancel][nng_aio_cancel], +[nng_aio_free][nng_aio_free], +[nng_aio_wait][nng_aio_wait] + +{{#include ../refs.md}} diff --git a/docs/reference/src/aio/nng_aio_wait.md b/docs/reference/src/aio/nng_aio_wait.md new file mode 100644 index 00000000..f3d1e384 --- /dev/null +++ b/docs/reference/src/aio/nng_aio_wait.md @@ -0,0 +1,35 @@ +# nng_aio_wait + +## NAME + +nng_aio_wait --- wait for asynchronous I/O operation + +## SYNOPSIS + +```c +#include + +void nng_aio_wait(nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_aio_wait()` function waits for an asynchronous I/O operation +to complete. +If the operation has not been started, or has already +completed, then it returns immediately. + +If a callback was set with _aio_ when it was allocated, then this +function will not be called until the callback has completed. + +> [!IMPORTANT] +> This function should never be called from a function that itself +> is a callback of an [`nng_aio`][aio], either this one or any other. +> Doing so may result in a deadlock. + +## SEE ALSO + +[nng_aio_abort][nng_aio_abort], +[nng_aio_busy][nng_aio_busy] + +{{#include ../refs.md}} -- cgit v1.2.3-70-g09d2