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/SUMMARY.md | 34 +++++----- 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 +++++++++++ docs/reference/src/api/aio/index.md | 74 ---------------------- docs/reference/src/api/aio/nng_aio_abort.md | 35 ----------- docs/reference/src/api/aio/nng_aio_alloc.md | 74 ---------------------- docs/reference/src/api/aio/nng_aio_busy.md | 41 ------------ docs/reference/src/api/aio/nng_aio_cancel.md | 37 ----------- docs/reference/src/api/aio/nng_aio_count.md | 44 ------------- docs/reference/src/api/aio/nng_aio_free.md | 34 ---------- docs/reference/src/api/aio/nng_aio_get_msg.md | 30 --------- docs/reference/src/api/aio/nng_aio_get_output.md | 40 ------------ docs/reference/src/api/aio/nng_aio_result.md | 46 -------------- docs/reference/src/api/aio/nng_aio_set_input.md | 42 ------------- docs/reference/src/api/aio/nng_aio_set_iov.md | 40 ------------ docs/reference/src/api/aio/nng_aio_set_msg.md | 28 --------- docs/reference/src/api/aio/nng_aio_set_timeout.md | 53 ---------------- docs/reference/src/api/aio/nng_aio_stop.md | 39 ------------ docs/reference/src/api/aio/nng_aio_wait.md | 33 ---------- docs/reference/src/api/context.md | 1 - docs/reference/src/chapter_1.md | 1 - docs/reference/src/refs.md | 18 ++++++ 36 files changed, 755 insertions(+), 709 deletions(-) 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 delete mode 100644 docs/reference/src/api/aio/index.md delete mode 100644 docs/reference/src/api/aio/nng_aio_abort.md delete mode 100644 docs/reference/src/api/aio/nng_aio_alloc.md delete mode 100644 docs/reference/src/api/aio/nng_aio_busy.md delete mode 100644 docs/reference/src/api/aio/nng_aio_cancel.md delete mode 100644 docs/reference/src/api/aio/nng_aio_count.md delete mode 100644 docs/reference/src/api/aio/nng_aio_free.md delete mode 100644 docs/reference/src/api/aio/nng_aio_get_msg.md delete mode 100644 docs/reference/src/api/aio/nng_aio_get_output.md delete mode 100644 docs/reference/src/api/aio/nng_aio_result.md delete mode 100644 docs/reference/src/api/aio/nng_aio_set_input.md delete mode 100644 docs/reference/src/api/aio/nng_aio_set_iov.md delete mode 100644 docs/reference/src/api/aio/nng_aio_set_msg.md delete mode 100644 docs/reference/src/api/aio/nng_aio_set_timeout.md delete mode 100644 docs/reference/src/api/aio/nng_aio_stop.md delete mode 100644 docs/reference/src/api/aio/nng_aio_wait.md delete mode 100644 docs/reference/src/api/context.md delete mode 100644 docs/reference/src/chapter_1.md (limited to 'docs/reference') diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index 4816be30..48fdc8df 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -69,23 +69,23 @@ - [nng_ctx_set](ctx/nng_ctx_set.md) - [nng_ctx_setopt](ctx/nng_ctx_setopt.md) - - [Asynchronous I/O](./api/aio/index.md) - - - [nng_aio_abort](api/aio/nng_aio_abort.md) - - [nng_aio_alloc](api/aio/nng_aio_alloc.md) - - [nng_aio_busy](api/aio/nng_aio_busy.md) - - [nng_aio_cancel](api/aio/nng_aio_cancel.md) - - [nng_aio_count](api/aio/nng_aio_count.md) - - [nng_aio_free](api/aio/nng_aio_free.md) - - [nng_aio_get_msg](api/aio/nng_aio_get_msg.md) - - [nng_aio_get_output](api/aio/nng_aio_get_output.md) - - [nng_aio_result](api/aio/nng_aio_result.md) - - [nng_aio_set_input](api/aio/nng_aio_set_input.md) - - [nng_aio_set_iov](api/aio/nng_aio_set_iov.md) - - [nng_aio_set_msg](api/aio/nng_aio_set_msg.md) - - [nng_aio_set_timeout](api/aio/nng_aio_set_timeout.md) - - [nng_aio_stop](api/aio/nng_aio_stop.md) - - [nng_aio_wait](api/aio/nng_aio_wait.md) + - [Asynchronous I/O](aio/index.md) + + - [nng_aio_abort](aio/nng_aio_abort.md) + - [nng_aio_alloc](aio/nng_aio_alloc.md) + - [nng_aio_busy](aio/nng_aio_busy.md) + - [nng_aio_cancel](aio/nng_aio_cancel.md) + - [nng_aio_count](aio/nng_aio_count.md) + - [nng_aio_free](aio/nng_aio_free.md) + - [nng_aio_get_msg](aio/nng_aio_get_msg.md) + - [nng_aio_get_output](aio/nng_aio_get_output.md) + - [nng_aio_result](aio/nng_aio_result.md) + - [nng_aio_set_input](aio/nng_aio_set_input.md) + - [nng_aio_set_iov](aio/nng_aio_set_iov.md) + - [nng_aio_set_msg](aio/nng_aio_set_msg.md) + - [nng_aio_set_timeout](aio/nng_aio_set_timeout.md) + - [nng_aio_stop](aio/nng_aio_stop.md) + - [nng_aio_wait](aio/nng_aio_wait.md) - [Asynchronous I/O for Providers](api/aio_provider/index.md) 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}} diff --git a/docs/reference/src/api/aio/index.md b/docs/reference/src/api/aio/index.md deleted file mode 100644 index 84c6d6e1..00000000 --- a/docs/reference/src/api/aio/index.md +++ /dev/null @@ -1,74 +0,0 @@ -# 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.md), -and destroyed using [`nng_aio_free()`](nng_aio_free.md). - -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.md)), as well setting a maximum -timeout for them to complete within -(see [`nng_aio_set_timeout()`](nng_aio_set_timeout.md)). - -## Waiting for Completion - -It is also possible to initiate an asynchronous operation, and wait for it to -complete [`nng_aio_wait()`](nng_aio_wait.md). - -> [!IMPORTANT] -> Applications must never call [`nng_aio_wait()`](nng_aio_wait.md) or -> [`nng_aio_stop()`](nng_aio_stop.md) from a callback registered to -> an `nng_aio` object. Doing so can lead to a deadlock. - -## See Also - -[nng_aio_abort](nng_aio_abort.md), -[nng_aio_alloc](nng_aio_alloc.md), -[nng_aio_cancel](nng_aio_cancel.md), -[nng_aio_count](nng_aio_count.md), -[nng_aio_free](nng_aio_free.md), -[nng_aio_get_input](nng_aio_get_input.md), -[nng_aio_get_msg](nng_aio_get_msg.md), -[nng_aio_get_output](nng_aio_get_output.md), -[nng_aio_result](nng_aio_result.md), -[nng_aio_set_input](nng_aio_set_input.md), -[nng_aio_set_iov](nng_aio_set_iov.md), -[nng_aio_set_msg](nng_aio_set_msg.md), -[nng_aio_set_timeout](nng_aio_set_timeout.md), -[nng_aio_stop](nng_aio_stop.md), -[nng_aio_wait](nng_aio_wait.md) diff --git a/docs/reference/src/api/aio/nng_aio_abort.md b/docs/reference/src/api/aio/nng_aio_abort.md deleted file mode 100644 index a94ffd30..00000000 --- a/docs/reference/src/api/aio/nng_aio_abort.md +++ /dev/null @@ -1,35 +0,0 @@ -# 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.md) -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.md), -[nng_aio_cancel](nng_aio_cancel.md), -[nng_aio_result](nng_aio_result.md) diff --git a/docs/reference/src/api/aio/nng_aio_alloc.md b/docs/reference/src/api/aio/nng_aio_alloc.md deleted file mode 100644 index 5636f398..00000000 --- a/docs/reference/src/api/aio/nng_aio_alloc.md +++ /dev/null @@ -1,74 +0,0 @@ -# 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.md) -> 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.md), [`nng_aio_count()`](nng_aio_count.md), -and [`nng_aio_get_output()`](nng_aio_get_output.md). - -It is possible to wait synchronously for an otherwise asynchronous operation -by using the function [`nng_aio_wait()`](nng_aio_wait.md). -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.md). - -## 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.md), -[nng_aio_cancel](nng_aio_cancel.md), -[nng_aio_count](nng_aio_count.md), -[nng_aio_free](nng_aio_free.md), -[nng_aio_get_input](nng_aio_get_input.md), -[nng_aio_get_msg](nng_aio_get_msg.md), -[nng_aio_get_output](nng_aio_get_output.md), -[nng_aio_result](nng_aio_result.md), -[nng_aio_set_input](nng_aio_set_input.md), -[nng_aio_set_iov](nng_aio_set_iov.md), -[nng_aio_set_msg](nng_aio_set_msg.md), -[nng_aio_set_timeout](nng_aio_set_timeout.md), -[nng_aio_stop](nng_aio_stop.md), -[nng_aio_wait](nng_aio_wait.md) diff --git a/docs/reference/src/api/aio/nng_aio_busy.md b/docs/reference/src/api/aio/nng_aio_busy.md deleted file mode 100644 index 826247fa..00000000 --- a/docs/reference/src/api/aio/nng_aio_busy.md +++ /dev/null @@ -1,41 +0,0 @@ -# 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.md). - -> [!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.md), -[nng_aio_alloc](nng_aio_alloc.md), -[nng_aio_wait](nng_aio_wait.md) diff --git a/docs/reference/src/api/aio/nng_aio_cancel.md b/docs/reference/src/api/aio/nng_aio_cancel.md deleted file mode 100644 index c523bf52..00000000 --- a/docs/reference/src/api/aio/nng_aio_cancel.md +++ /dev/null @@ -1,37 +0,0 @@ -# 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.md) 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.md) with the error `NNG_ECANCELED`. - -## SEE ALSO - -[nng_aio_abort](nng_aio_abort.md), -[nng_aio_alloc](nng_aio_alloc.md), -[nng_aio_result](nng_aio_result.md) diff --git a/docs/reference/src/api/aio/nng_aio_count.md b/docs/reference/src/api/aio/nng_aio_count.md deleted file mode 100644 index ae844da0..00000000 --- a/docs/reference/src/api/aio/nng_aio_count.md +++ /dev/null @@ -1,44 +0,0 @@ -# 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.md)). - -> [!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.md). - -## RETURN VALUES - -The number of bytes transferred by the operation. - -## SEE ALSO - -[nng_aio_alloc](nng_aio_alloc.md), -[nng_aio_result](nng_aio_result.md), -[nng_aio_set_iov](nng_aio_set_iov.md), -[nng_aio_wait](nng_aio_wait.md) diff --git a/docs/reference/src/api/aio/nng_aio_free.md b/docs/reference/src/api/aio/nng_aio_free.md deleted file mode 100644 index ba400bba..00000000 --- a/docs/reference/src/api/aio/nng_aio_free.md +++ /dev/null @@ -1,34 +0,0 @@ -# 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.md).) - -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.md), -[nng_aio_stop](nng_aio_stop.md) diff --git a/docs/reference/src/api/aio/nng_aio_get_msg.md b/docs/reference/src/api/aio/nng_aio_get_msg.md deleted file mode 100644 index e77b7810..00000000 --- a/docs/reference/src/api/aio/nng_aio_get_msg.md +++ /dev/null @@ -1,30 +0,0 @@ -# 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.md)) -or that was previously stored with -[`nng_aio_set_msg()`](nng_aio_set_msg.md). - -> [!IMPORTANT] -> The _aio_ must not have an operation in progress. - -## SEE ALSO - -[nng_aio_set_msg](nng_aio_set_msg.md), -[nng_recv_aio](nng_recv_aio.md), -[Messages](../msg/index.md) diff --git a/docs/reference/src/api/aio/nng_aio_get_output.md b/docs/reference/src/api/aio/nng_aio_get_output.md deleted file mode 100644 index 9983696f..00000000 --- a/docs/reference/src/api/aio/nng_aio_get_output.md +++ /dev/null @@ -1,40 +0,0 @@ -# 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.md), -[nng_aio_set_output](../aio_provider/nng_aio_set_output.md), -[nng_aio_result](nng_aio_result.md) diff --git a/docs/reference/src/api/aio/nng_aio_result.md b/docs/reference/src/api/aio/nng_aio_result.md deleted file mode 100644 index 21038719..00000000 --- a/docs/reference/src/api/aio/nng_aio_result.md +++ /dev/null @@ -1,46 +0,0 @@ -# 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.md). - -## 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.md), -[nng_aio_alloc](nng_aio_alloc.md), -[nng_aio_wait](nng_aio_wait.md), -[nng_strerror](../util/nng_strerror.md) diff --git a/docs/reference/src/api/aio/nng_aio_set_input.md b/docs/reference/src/api/aio/nng_aio_set_input.md deleted file mode 100644 index baf9587a..00000000 --- a/docs/reference/src/api/aio/nng_aio_set_input.md +++ /dev/null @@ -1,42 +0,0 @@ -# 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.md) function. - -## SEE ALSO - -[nng_aio_alloc](nng_aio_alloc.md), -[nng_aio_get_input](../aio_provider/nng_aio_get_input.md) diff --git a/docs/reference/src/api/aio/nng_aio_set_iov.md b/docs/reference/src/api/aio/nng_aio_set_iov.md deleted file mode 100644 index 0c33153d..00000000 --- a/docs/reference/src/api/aio/nng_aio_set_iov.md +++ /dev/null @@ -1,40 +0,0 @@ -# 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.md) -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. diff --git a/docs/reference/src/api/aio/nng_aio_set_msg.md b/docs/reference/src/api/aio/nng_aio_set_msg.md deleted file mode 100644 index c9b5c03a..00000000 --- a/docs/reference/src/api/aio/nng_aio_set_msg.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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.md)). - -> [!IMPORTANT] -> The _aio_ must not have an operation in progress. - -## SEE ALSO - -[nng_aio_get_msg](nng_aio_get_msg.md), -[nng_send_aio](nng_send_aio.md), -[Messages](../msg/index.md) diff --git a/docs/reference/src/api/aio/nng_aio_set_timeout.md b/docs/reference/src/api/aio/nng_aio_set_timeout.md deleted file mode 100644 index 34daa6f4..00000000 --- a/docs/reference/src/api/aio/nng_aio_set_timeout.md +++ /dev/null @@ -1,53 +0,0 @@ -# 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 `NNG_DURATION_INFINITE`, then no timeout is used. -If the timeout is `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.md), -[nng_aio_result](nng_aio_result.md), -[nng_clock](../util/nng_clock.md) diff --git a/docs/reference/src/api/aio/nng_aio_stop.md b/docs/reference/src/api/aio/nng_aio_stop.md deleted file mode 100644 index 7838eda2..00000000 --- a/docs/reference/src/api/aio/nng_aio_stop.md +++ /dev/null @@ -1,39 +0,0 @@ -# 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.md) 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.md), particularly if the callbacks -> might attempt to reschedule additional operations. - -## SEE ALSO - -[nng_aio_cancel](nng_aio_cancel.md), -[nng_aio_free](nng_aio_free.md), -[nng_aio_begin](nng_aio_begin.md), -[nng_aio_wait](nng_aio-wait.md) diff --git a/docs/reference/src/api/aio/nng_aio_wait.md b/docs/reference/src/api/aio/nng_aio_wait.md deleted file mode 100644 index 76198ca1..00000000 --- a/docs/reference/src/api/aio/nng_aio_wait.md +++ /dev/null @@ -1,33 +0,0 @@ -# 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`](index.md), either this one or any other. -> Doing so may result in a deadlock. - -## SEE ALSO - -[nng_aio_abort](nng_aio_abort.md), -[nng_aio_busy](nng_aio_busy.md) diff --git a/docs/reference/src/api/context.md b/docs/reference/src/api/context.md deleted file mode 100644 index 6131b985..00000000 --- a/docs/reference/src/api/context.md +++ /dev/null @@ -1 +0,0 @@ -# Context Functions diff --git a/docs/reference/src/chapter_1.md b/docs/reference/src/chapter_1.md deleted file mode 100644 index b743fda3..00000000 --- a/docs/reference/src/chapter_1.md +++ /dev/null @@ -1 +0,0 @@ -# Chapter 1 diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md index 4c954596..5c67ab09 100644 --- a/docs/reference/src/refs.md +++ b/docs/reference/src/refs.md @@ -81,6 +81,24 @@ [nng_ctx_set]: ../ctx/nng_ctx_set.md [nng_ctx_setopt]: ../ctx/nng_ctx_setopt.md + + +[nng_aio_abort]: ../aio/nng_aio_abort.md +[nng_aio_alloc]: ../aio/nng_aio_alloc.md +[nng_aio_busy]: ../aio/nng_aio_busy.md +[nng_aio_cancel]: ../aio/nng_aio_cancel.md +[nng_aio_count]: ../aio/nng_aio_count.md +[nng_aio_free]: ../aio/nng_aio_free.md +[nng_aio_get_msg]: ../aio/nng_aio_get_msg.md +[nng_aio_get_output]: ../aio/nng_aio_get_output.md +[nng_aio_result]: ../aio/nng_aio_result.md +[nng_aio_set_input]: ../aio/nng_aio_set_input.md +[nng_aio_set_iov]: ../aio/nng_aio_set_iov.md +[nng_aio_set_msg]: ../aio/nng_aio_set_msg.md +[nng_aio_set_timeout]: ../aio/nng_aio_set_timeout.md +[nng_aio_stop]: ../aio/nng_aio_stop.md +[nng_aio_wait]: ../aio/nng_aio_wait.md + [nng_cv_alloc]: ../thr/nng_cv_alloc.md -- cgit v1.2.3-70-g09d2