From b4fa69e7a6ef540e7d6a918c88f2816fff6c0cf0 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 24 Mar 2024 21:46:35 -0700 Subject: Organization and content --- docs/reference/src/api/aio_provider/index.md | 21 ++++++++ .../src/api/aio_provider/nng_aio_begin.md | 44 ++++++++++++++++ .../src/api/aio_provider/nng_aio_defer.md | 58 ++++++++++++++++++++++ .../src/api/aio_provider/nng_aio_finish.md | 39 +++++++++++++++ .../src/api/aio_provider/nng_aio_get_input.md | 34 +++++++++++++ .../src/api/aio_provider/nng_aio_set_output.md | 36 ++++++++++++++ 6 files changed, 232 insertions(+) create mode 100644 docs/reference/src/api/aio_provider/index.md create mode 100644 docs/reference/src/api/aio_provider/nng_aio_begin.md create mode 100644 docs/reference/src/api/aio_provider/nng_aio_defer.md create mode 100644 docs/reference/src/api/aio_provider/nng_aio_finish.md create mode 100644 docs/reference/src/api/aio_provider/nng_aio_get_input.md create mode 100644 docs/reference/src/api/aio_provider/nng_aio_set_output.md (limited to 'docs/reference/src/api/aio_provider') diff --git a/docs/reference/src/api/aio_provider/index.md b/docs/reference/src/api/aio_provider/index.md new file mode 100644 index 00000000..75a47358 --- /dev/null +++ b/docs/reference/src/api/aio_provider/index.md @@ -0,0 +1,21 @@ +# Asynchronous I/O for Providers + +I/O providers perform the operations that are linked to +an [`nng_aio`](../aio/index.md) object, on behalf of applications +that submit requests for the same operations. + +Most applications will not use the functions listed here. +Applications that implement their own HTTP handler functions, or +custom transport providers, might make use of these functions. + +In addition to these functions, I/O providers may utilize the +other consumer functions for [Aysnchronous I/O](../aio/index.md). + +## See Also + +[nng_aio_begin()](nng_aio_begin.md), +[nng_aio_defer()](nng_aio_defer.md), +[nng_aio_finish()](nng_aio_finish.md), +[nng_aio_get_input()](nng_aio_get_input.md), +[nng_aio_set_output()](nng_aio_set_output.md), +[Asynchronous I/O](../aio/index.md) diff --git a/docs/reference/src/api/aio_provider/nng_aio_begin.md b/docs/reference/src/api/aio_provider/nng_aio_begin.md new file mode 100644 index 00000000..8e342b26 --- /dev/null +++ b/docs/reference/src/api/aio_provider/nng_aio_begin.md @@ -0,0 +1,44 @@ +# nng_aio_begin() + +## NAME + +nng_aio_begin --- begin asynchronous I/O operation + +## SYNOPSIS + +```c +#include + +bool nng_aio_begin(nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_aio_begin()` function is called by the I/O provider to indicate that +it is going to process the operation. + +The function may return `false`, indicating that the _aio_ has been closed. +In this case the provider should abandon the operation and do nothing else. + +This operation should be called at the start of any I/O operation, and must +be called not more than once for a given I/O operation on a given _aio_. + +Once this function is called, if `true` is returned, then the provider MUST +guarantee that [`nng_aio_finish()`](nng_aio_finish.md) is called for the _aio_ +exactly once, when the operation is complete or canceled. + +> [!TIP] +> This function is only for I/O providers (those actually performing +> the operation such as HTTP handler functions or transport providers); ordinary +> users of the _aio_ should not call this function. + +## RETURN VALUES + +- `true`: The operation has been started. +- `false`: The operation cannot be started. + +## SEE ALSO + +[nng_aio_cancel()](../aio/nng_aio_cancel.md), +[nng_aio_defer()](nng_aio_defer.md), +[nng_aio_finish()](nng_aio_finish.md) diff --git a/docs/reference/src/api/aio_provider/nng_aio_defer.md b/docs/reference/src/api/aio_provider/nng_aio_defer.md new file mode 100644 index 00000000..93d84769 --- /dev/null +++ b/docs/reference/src/api/aio_provider/nng_aio_defer.md @@ -0,0 +1,58 @@ +# nng_aio_defer() + +## NAME + +nng_aio_defer --- defer asynchronous I/O operation + +## SYNOPSIS + +```c +#include + +typedef void (*nng_aio_cancelfn)(nng_aio *aio, void *arg, int err); + +void nng_aio_defer(nng_aio *aio, nng_aio_cancelfn fn, void *arg); +``` + +## DESCRIPTION + +The `nng_aio_defer()` function marks operation associated with _aio_ as +being deferred for asynchronous completion, registering a cancellation +function _fn_ and associated argument _arg_. +This permits the operation to be canceled. + +If the _aio_ is canceled, the cancellation routine _fn_ will be called +with the _aio_, the _arg_ specified by `nng_aio_defer()`, and an error +value in _err_, which is the reason that the operation is being canceled. + +At any given time, the operation may not be cancelable. +For example it may have already been +completed, or be in a state where it is no longer possible to unschedule it. +In this case, the _cancelfn_ should just return without making any changes. + +If the cancellation routine successfully canceled the operation, it should +ensure that [`nng_aio_finish()`](nng_aio_finish.md) is called, with the +error code specified by _err_. + +> [!IMPORTANT] +> It is mandatory that I/O providers call [`nng_aio_finish()`](nng_aio_finish.md) _*exactly once*_ when they are finished with the operation. + +> [!IMPORTANT] +> Care must be taken to ensure that cancellation and completion of +> the routine are multi-thread safe. This will usually involve the use +> of locks or other synchronization primitives. + +> [!TIP] +> For operations that complete synchronously, without any need to be +> deferred, the provider need not call `nng_aio_defer()`. + +> [!TIP] +> This function is only for I/O providers (those actually performing +> the operation such as HTTP handler functions or transport providers); ordinary +> users of the _aio_ should not call this function. + +## SEE ALSO + +[nng_aio_alloc()](../aio/nng_aio_alloc.md), +[nng_aio_cancel()](../aio/nng_aio_cancel.md), +[nng_aio_finish()](nng_aio_finish.md) diff --git a/docs/reference/src/api/aio_provider/nng_aio_finish.md b/docs/reference/src/api/aio_provider/nng_aio_finish.md new file mode 100644 index 00000000..61b1ca42 --- /dev/null +++ b/docs/reference/src/api/aio_provider/nng_aio_finish.md @@ -0,0 +1,39 @@ +# nng_aio_finish() + +## NAME + +nng_aio_finish --- finish asynchronous I/O operation + +## SYNOPSIS + +```c +#include + +void nng_aio_finish(nng_aio *aio, int err); +``` + +## DESCRIPTION + +The `nng_aio_finish()` function marks operation associated with _aio_ as +complete, with the status _err_. +This will be the result returned by [`nng_aio_result()`](../aio/nng_aio_result.md). + +This function causes the callback associated with the _aio_ to called. + +> [!IMPORTANT] +> It is mandatory that operation providers call this function +> _exactly once_ when they are finished with the operation. +> After calling this function, the provider _must not_ perform any +> further accesses to the _aio_. + +> [!TIP] +> This function is only for I/O providers (those actually performing +> the operation such as HTTP handler functions or transport providers); ordinary +> users of the _aio_ should not have any need for this function. + +## SEE ALSO + +[nng_aio_begin()](nng_aio_begin.md), +[nng_aio_cancel()](nng_aio_cancel.md), +[nng_aio_defer()](nng_aio_defer.md), +[nng_aio_result()](../aio/nng_aio_result.md) diff --git a/docs/reference/src/api/aio_provider/nng_aio_get_input.md b/docs/reference/src/api/aio_provider/nng_aio_get_input.md new file mode 100644 index 00000000..28ecb797 --- /dev/null +++ b/docs/reference/src/api/aio_provider/nng_aio_get_input.md @@ -0,0 +1,34 @@ +# nng_aio_get_input(3) + +## NAME + +nng_aio_get_input --- return input parameter + +## SYNOPSIS + +```c +#include + +void *nng_aio_get_input(nng_aio *aio, unsigned int index); +``` + +## DESCRIPTION + +The `nng_aio_get_input()` function returns the value of the input parameter +previously set at _index_ on _aio_ with the +[`nng_aio_set_input()`](nng_aio_set_input.md) function. + +The valid values of _index_ range from zero (0) to three (3), as no operation +currently defined can accept more than four parameters. +If the index supplied is outside of this range, +or if the input parameter was not previously set, then `NULL` is returned. + +## RETURN VALUES + +Value previously set, or `NULL`. + +## SEE ALSO + +[nng_aio_alloc()](../aio/nng_aio_alloc.md), +[nng_aio_get_output()](../aio/nng_aio_get_output.md), +[nng_aio_set_input()](../aio/nng_aio_set_input.md) diff --git a/docs/reference/src/api/aio_provider/nng_aio_set_output.md b/docs/reference/src/api/aio_provider/nng_aio_set_output.md new file mode 100644 index 00000000..6a79e429 --- /dev/null +++ b/docs/reference/src/api/aio_provider/nng_aio_set_output.md @@ -0,0 +1,36 @@ +# nng_aio_set_output() + +## NAME + +nng_aio_set_output --- set output result + +## SYNOPSIS + +```c +#include + +void nng_aio_set_output(nng_aio *aio, unsigned int index, void *result); +``` + +## DESCRIPTION + +The `nng_aio_set_output()` function sets the output result at _index_ +to _result_ for the asynchronous operation associated with _aio_. + +The type and semantics of output results are determined by specific +operations; the operation must supply appropriate output results when +the operation completes successfully. + +The valid values of _index_ range from zero (0) to three (3), as no operation +currently defined can return more than four results. + +> [!NOTE] +> Note that attempts to set results with an _index_ greater than +> three (3) will be ignored. + +An output result set with this function may be retrieved later with +the [`nng_aio_get_output()`](nng_aio_get_output.md) function. + +## SEE ALSO + +[nng_aio_get_output(3)](../aio/nng_aio_get_output.md) -- cgit v1.2.3-70-g09d2