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/SUMMARY.md | 47 +++++++------ 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 | 35 ++++++++++ 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/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 ++++++++++ docs/reference/src/api/index.md | 17 ++++- docs/reference/src/api/nng_aio_abort.md | 36 ---------- docs/reference/src/api/nng_aio_alloc.md | 76 ---------------------- docs/reference/src/api/nng_aio_begin.md | 47 ------------- docs/reference/src/api/nng_aio_busy.md | 42 ------------ docs/reference/src/api/nng_aio_cancel.md | 38 ----------- docs/reference/src/api/nng_aio_count.md | 46 ------------- docs/reference/src/api/nng_aio_defer.md | 59 ----------------- docs/reference/src/api/nng_aio_finish.md | 41 ------------ docs/reference/src/api/nng_aio_free.md | 35 ---------- docs/reference/src/api/nng_aio_get_input.md | 35 ---------- docs/reference/src/api/nng_aio_get_msg.md | 31 --------- docs/reference/src/api/nng_aio_get_output.md | 41 ------------ docs/reference/src/api/nng_aio_result.md | 46 ------------- docs/reference/src/api/nng_aio_set_input.md | 43 ------------ docs/reference/src/api/nng_aio_set_iov.md | 45 ------------- docs/reference/src/api/nng_aio_set_msg.md | 29 --------- docs/reference/src/api/nng_aio_set_output.md | 37 ----------- docs/reference/src/api/nng_aio_set_timeout.md | 54 --------------- docs/reference/src/api/nng_aio_stop.md | 40 ------------ docs/reference/src/api/nng_aio_wait.md | 34 ---------- docs/reference/src/protocols/bus.md | 58 +++++++++++++++++ docs/reference/src/protocols/index.md | 1 + docs/reference/src/transports/index.md | 5 ++ docs/reference/src/transports/tcp.md | 74 +++++++++++++++++++++ 48 files changed, 1100 insertions(+), 880 deletions(-) create mode 100644 docs/reference/src/api/aio/index.md create mode 100644 docs/reference/src/api/aio/nng_aio_abort.md create mode 100644 docs/reference/src/api/aio/nng_aio_alloc.md create mode 100644 docs/reference/src/api/aio/nng_aio_busy.md create mode 100644 docs/reference/src/api/aio/nng_aio_cancel.md create mode 100644 docs/reference/src/api/aio/nng_aio_count.md create mode 100644 docs/reference/src/api/aio/nng_aio_free.md create mode 100644 docs/reference/src/api/aio/nng_aio_get_msg.md create mode 100644 docs/reference/src/api/aio/nng_aio_get_output.md create mode 100644 docs/reference/src/api/aio/nng_aio_result.md create mode 100644 docs/reference/src/api/aio/nng_aio_set_input.md create mode 100644 docs/reference/src/api/aio/nng_aio_set_iov.md create mode 100644 docs/reference/src/api/aio/nng_aio_set_msg.md create mode 100644 docs/reference/src/api/aio/nng_aio_set_timeout.md create mode 100644 docs/reference/src/api/aio/nng_aio_stop.md create mode 100644 docs/reference/src/api/aio/nng_aio_wait.md 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 delete mode 100644 docs/reference/src/api/nng_aio_abort.md delete mode 100644 docs/reference/src/api/nng_aio_alloc.md delete mode 100644 docs/reference/src/api/nng_aio_begin.md delete mode 100644 docs/reference/src/api/nng_aio_busy.md delete mode 100644 docs/reference/src/api/nng_aio_cancel.md delete mode 100644 docs/reference/src/api/nng_aio_count.md delete mode 100644 docs/reference/src/api/nng_aio_defer.md delete mode 100644 docs/reference/src/api/nng_aio_finish.md delete mode 100644 docs/reference/src/api/nng_aio_free.md delete mode 100644 docs/reference/src/api/nng_aio_get_input.md delete mode 100644 docs/reference/src/api/nng_aio_get_msg.md delete mode 100644 docs/reference/src/api/nng_aio_get_output.md delete mode 100644 docs/reference/src/api/nng_aio_result.md delete mode 100644 docs/reference/src/api/nng_aio_set_input.md delete mode 100644 docs/reference/src/api/nng_aio_set_iov.md delete mode 100644 docs/reference/src/api/nng_aio_set_msg.md delete mode 100644 docs/reference/src/api/nng_aio_set_output.md delete mode 100644 docs/reference/src/api/nng_aio_set_timeout.md delete mode 100644 docs/reference/src/api/nng_aio_stop.md delete mode 100644 docs/reference/src/api/nng_aio_wait.md create mode 100644 docs/reference/src/protocols/bus.md create mode 100644 docs/reference/src/protocols/index.md create mode 100644 docs/reference/src/transports/index.md create mode 100644 docs/reference/src/transports/tcp.md (limited to 'docs/reference') diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index c99877c1..4ae2c79b 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -20,30 +20,29 @@ - [Asynchronous I/O](./api/aio/index.md) - - [nng_aio](api/nng_aio.md) - - [nng_aio_abort](api/nng_aio_abort.md) - - [nng_aio_alloc](api/nng_aio_alloc.md) - - [nng_aio_busy](api/nng_aio_busy.md) - - [nng_aio_cancel](api/nng_aio_cancel.md) - - [nng_aio_count](api/nng_aio_count.md) - - [nng_aio_free](api/nng_aio_free.md) - - [nng_aio_get_msg](api/nng_aio_get_msg.md) - - [nng_aio_get_output](api/nng_aio_get_output.md) - - [nng_aio_result](api/nng_aio_result.md) - - [nng_aio_set_input](api/nng_aio_set_input.md) - - [nng_aio_set_iov](api/nng_aio_set_iov.md) - - [nng_aio_set_msg](api/nng_aio_set_msg.md) - - [nng_aio_set_timeout](api/nng_aio_set_timeout.md) - - [nng_aio_stop](api/nng_aio_stop.md) - - [nng_aio_wait](api/nng_aio_wait.md) - - - [Asynchronous I/O for Providers](api/aio_provider.md) - - - [nng_aio_begin](api/nng_aio_begin.md) - - [nng_aio_defer](api/nng_aio_defer.md) - - [nng_aio_finish](api/nng_aio_finish.md) - - [nng_aio_get_input](api/nng_aio_get_input.md) - - [nng_aio_set_output](api/nng_aio_set_output.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 for Providers](api/aio_provider/index.md) + + - [nng_aio_begin](api/aio_provider/nng_aio_begin.md) + - [nng_aio_defer](api/aio_provider/nng_aio_defer.md) + - [nng_aio_finish](api/aio_provider/nng_aio_finish.md) + - [nng_aio_get_input](api/aio_provider/nng_aio_get_input.md) + - [nng_aio_set_output](api/aio_provider/nng_aio_set_output.md) - [General Purpose Functions](api/general.md) diff --git a/docs/reference/src/api/aio/index.md b/docs/reference/src/api/aio/index.md new file mode 100644 index 00000000..4c49ff78 --- /dev/null +++ b/docs/reference/src/api/aio/index.md @@ -0,0 +1,74 @@ +# Interfaces for 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 new file mode 100644 index 00000000..09e0fd2e --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_abort.md @@ -0,0 +1,35 @@ +# 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 new file mode 100644 index 00000000..1f3f6be8 --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_alloc.md @@ -0,0 +1,74 @@ +# 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 new file mode 100644 index 00000000..2a794a83 --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_busy.md @@ -0,0 +1,41 @@ +# 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(3)](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 new file mode 100644 index 00000000..63cad987 --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_cancel.md @@ -0,0 +1,37 @@ +# 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 new file mode 100644 index 00000000..a4da3c64 --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_count.md @@ -0,0 +1,44 @@ +# 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 new file mode 100644 index 00000000..c558535d --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_free.md @@ -0,0 +1,35 @@ +# 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), +[nng_aio](nng_aio.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 new file mode 100644 index 00000000..55f712db --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_get_msg.md @@ -0,0 +1,30 @@ +# 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), +[nng_msg](nng_msg.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 new file mode 100644 index 00000000..d25c1c20 --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_get_output.md @@ -0,0 +1,40 @@ +# 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 new file mode 100644 index 00000000..fe6688fd --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_result.md @@ -0,0 +1,46 @@ +# 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()](nng_strerror.md), +[nng_aio](nng_aio.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 new file mode 100644 index 00000000..1b3e0883 --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_set_input.md @@ -0,0 +1,42 @@ +# 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 new file mode 100644 index 00000000..0c33153d --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_set_iov.md @@ -0,0 +1,40 @@ +# 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 new file mode 100644 index 00000000..24ba9f60 --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_set_msg.md @@ -0,0 +1,28 @@ +# 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), +[nng_msg](nng_msg.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 new file mode 100644 index 00000000..b0bab9ab --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_set_timeout.md @@ -0,0 +1,53 @@ +# 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()`](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_duration](nng_duration) diff --git a/docs/reference/src/api/aio/nng_aio_stop.md b/docs/reference/src/api/aio/nng_aio_stop.md new file mode 100644 index 00000000..8ac32a76 --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_stop.md @@ -0,0 +1,39 @@ +# 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 new file mode 100644 index 00000000..52f5671e --- /dev/null +++ b/docs/reference/src/api/aio/nng_aio_wait.md @@ -0,0 +1,33 @@ +# 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`](nng_aio.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/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) diff --git a/docs/reference/src/api/index.md b/docs/reference/src/api/index.md index 0d1089e3..1541b541 100644 --- a/docs/reference/src/api/index.md +++ b/docs/reference/src/api/index.md @@ -1,8 +1,23 @@ # API Reference -This section documents the functions and data structures that make up +This chapter documents the functions and data structures that make up the _NNG_ programming interface. > [!NOTE] > Interfaces not documented here are not considered public or stable, > and they may be removed or altered in incompatible ways at any time. + +We have organized the reference material along general functional areas. +They are: + +- [Asynchronous I/O](aio/index.md) +- [Asynchronous I/O for Providers](aio_provider/index.md) +- General Utility Functions +- Scalability Protocol Sockets +- Scalability Protocol Contexts +- Concurrency / Multi-threading +- HTTP Server +- HTTP Client +- Streaming API +- Statistics API +- Legacy Compatibility diff --git a/docs/reference/src/api/nng_aio_abort.md b/docs/reference/src/api/nng_aio_abort.md deleted file mode 100644 index 4f4b8773..00000000 --- a/docs/reference/src/api/nng_aio_abort.md +++ /dev/null @@ -1,36 +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), -[nng_aio](nng_aio.md) diff --git a/docs/reference/src/api/nng_aio_alloc.md b/docs/reference/src/api/nng_aio_alloc.md deleted file mode 100644 index 4acb45aa..00000000 --- a/docs/reference/src/api/nng_aio_alloc.md +++ /dev/null @@ -1,76 +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`](nng_aio.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), -[nng_strerror()](nng_strerror.md), -[nng_aio](nng_aio.md) diff --git a/docs/reference/src/api/nng_aio_begin.md b/docs/reference/src/api/nng_aio_begin.md deleted file mode 100644 index da817091..00000000 --- a/docs/reference/src/api/nng_aio_begin.md +++ /dev/null @@ -1,47 +0,0 @@ -# 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_alloc()](nng_aio_alloc.md), -[nng_aio_cancel()](nng_aio_cancel.md), -[nng_aio_defer()](nng_aio_defer.md), -[nng_aio_finish()](nng_aio_finish.md), -[nng_aio_result()](nng_aio_result.md), -[nng_aio](nng_aio.md) diff --git a/docs/reference/src/api/nng_aio_busy.md b/docs/reference/src/api/nng_aio_busy.md deleted file mode 100644 index f5a1003b..00000000 --- a/docs/reference/src/api/nng_aio_busy.md +++ /dev/null @@ -1,42 +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(3)](nng_aio_wait.md), -[nng_aio](nng_aio.md) diff --git a/docs/reference/src/api/nng_aio_cancel.md b/docs/reference/src/api/nng_aio_cancel.md deleted file mode 100644 index 1bb8869e..00000000 --- a/docs/reference/src/api/nng_aio_cancel.md +++ /dev/null @@ -1,38 +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), -[nng_aio](nng_aio.md) diff --git a/docs/reference/src/api/nng_aio_count.md b/docs/reference/src/api/nng_aio_count.md deleted file mode 100644 index 2ce22786..00000000 --- a/docs/reference/src/api/nng_aio_count.md +++ /dev/null @@ -1,46 +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 - -[.text-left] -[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), -[nng_aio](nng_aio) diff --git a/docs/reference/src/api/nng_aio_defer.md b/docs/reference/src/api/nng_aio_defer.md deleted file mode 100644 index 6b634f42..00000000 --- a/docs/reference/src/api/nng_aio_defer.md +++ /dev/null @@ -1,59 +0,0 @@ -# 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()](nng_aio_alloc.md), -[nng_aio_cancel()](nng_aio_cancel.md), -[nng_aio_finish()](nng_aio_finish.md), -[nng_aio](nng_aio.md) diff --git a/docs/reference/src/api/nng_aio_finish.md b/docs/reference/src/api/nng_aio_finish.md deleted file mode 100644 index 48a52151..00000000 --- a/docs/reference/src/api/nng_aio_finish.md +++ /dev/null @@ -1,41 +0,0 @@ -# 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()`](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_alloc()](nng_aio_alloc.md), -[nng_aio_begin()](nng_aio_begin.md), -[nng_aio_cancel()](nng_aio_cancel.md), -[nng_aio_defer()](nng_aio_defer.md), -[nng_aio_result()](nng_aio_result.md), -[nng_aio](nng_aio.md) diff --git a/docs/reference/src/api/nng_aio_free.md b/docs/reference/src/api/nng_aio_free.md deleted file mode 100644 index c558535d..00000000 --- a/docs/reference/src/api/nng_aio_free.md +++ /dev/null @@ -1,35 +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), -[nng_aio](nng_aio.md) diff --git a/docs/reference/src/api/nng_aio_get_input.md b/docs/reference/src/api/nng_aio_get_input.md deleted file mode 100644 index 192c82d3..00000000 --- a/docs/reference/src/api/nng_aio_get_input.md +++ /dev/null @@ -1,35 +0,0 @@ -# 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()](nng_aio_alloc.md), -[nng_aio_get_output()](nng_aio_get_output.md), -[nng_aio_set_input()](nng_aio_set_input.md), -[nng_aio](nng_aio.md) diff --git a/docs/reference/src/api/nng_aio_get_msg.md b/docs/reference/src/api/nng_aio_get_msg.md deleted file mode 100644 index 70e18be9..00000000 --- a/docs/reference/src/api/nng_aio_get_msg.md +++ /dev/null @@ -1,31 +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), -[nng_aio](nng_aio.md), -[nng_msg](nng_msg.md) diff --git a/docs/reference/src/api/nng_aio_get_output.md b/docs/reference/src/api/nng_aio_get_output.md deleted file mode 100644 index 8f0a10a4..00000000 --- a/docs/reference/src/api/nng_aio_get_output.md +++ /dev/null @@ -1,41 +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()](nng_aio_set_output.md), -[nng_aio_result()](nng_aio_result.md), -[nng_aio](nng_aio.md), diff --git a/docs/reference/src/api/nng_aio_result.md b/docs/reference/src/api/nng_aio_result.md deleted file mode 100644 index fe6688fd..00000000 --- a/docs/reference/src/api/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()](nng_strerror.md), -[nng_aio](nng_aio.md), diff --git a/docs/reference/src/api/nng_aio_set_input.md b/docs/reference/src/api/nng_aio_set_input.md deleted file mode 100644 index 739489ad..00000000 --- a/docs/reference/src/api/nng_aio_set_input.md +++ /dev/null @@ -1,43 +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()](nng_aio_get_input.md), -[nng_aio](nng_aio.md) diff --git a/docs/reference/src/api/nng_aio_set_iov.md b/docs/reference/src/api/nng_aio_set_iov.md deleted file mode 100644 index 4093b5e3..00000000 --- a/docs/reference/src/api/nng_aio_set_iov.md +++ /dev/null @@ -1,45 +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. - -## SEE ALSO - -[nng_aio](nng_aio), -[nng_iov](nng_iov) diff --git a/docs/reference/src/api/nng_aio_set_msg.md b/docs/reference/src/api/nng_aio_set_msg.md deleted file mode 100644 index eb0bd4ed..00000000 --- a/docs/reference/src/api/nng_aio_set_msg.md +++ /dev/null @@ -1,29 +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), -[nng_aio](nng_aio.md), -[nng_msg](nng_msg.md) diff --git a/docs/reference/src/api/nng_aio_set_output.md b/docs/reference/src/api/nng_aio_set_output.md deleted file mode 100644 index c3c86440..00000000 --- a/docs/reference/src/api/nng_aio_set_output.md +++ /dev/null @@ -1,37 +0,0 @@ -# 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)](nng_aio_get_output.md), -[nng_aio](nng_aio.md) diff --git a/docs/reference/src/api/nng_aio_set_timeout.md b/docs/reference/src/api/nng_aio_set_timeout.md deleted file mode 100644 index e8643570..00000000 --- a/docs/reference/src/api/nng_aio_set_timeout.md +++ /dev/null @@ -1,54 +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()`](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_aio](nng_aio), -[nng_duration](nng_duration) diff --git a/docs/reference/src/api/nng_aio_stop.md b/docs/reference/src/api/nng_aio_stop.md deleted file mode 100644 index 4cfe41b6..00000000 --- a/docs/reference/src/api/nng_aio_stop.md +++ /dev/null @@ -1,40 +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), -[nng_aio](nng_aio.md), diff --git a/docs/reference/src/api/nng_aio_wait.md b/docs/reference/src/api/nng_aio_wait.md deleted file mode 100644 index 2cddcb29..00000000 --- a/docs/reference/src/api/nng_aio_wait.md +++ /dev/null @@ -1,34 +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`](nng_aio.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), -[nng_aio](nng_aio.md) diff --git a/docs/reference/src/protocols/bus.md b/docs/reference/src/protocols/bus.md new file mode 100644 index 00000000..8583ed65 --- /dev/null +++ b/docs/reference/src/protocols/bus.md @@ -0,0 +1,58 @@ +# BUS Protocol + +{{hi:protocol, _BUS_}} +The {{i:_BUS_ protocol}} provides for building mesh networks where +every peer is connected to every other peer. +In this protocol, each message sent by a node is sent to every one of +its directly connected peers. + +> [!TIP] +> Messages are only sent to directly connected peers. +> This means that in the event that a peer is connected indirectly, it will not +> receive messages. +> When using this protocol to build mesh networks, it +> is therefore important that a _fully-connected_ mesh network be constructed. + +All message delivery in this pattern is {{i:best-effort}}, which means that +peers may not receive messages. +Furthermore, delivery may occur to some, +all, or none of the directly connected peers. +(Messages are not delivered when peer nodes are unable to receive.) +Hence, send operations will never block; instead if the +message cannot be delivered for any reason it is discarded. + +> [!TIP] +> In order to minimize the likelihood of message loss, this protocol +> should not be used for high throughput communications. +> Furthermore, the more traffic _in aggregate_ that occurs across the topology, +> the more likely that message loss is to occur. + +## Socket Operations + +The [`nng_bus0_open()`](../api/nng_bus_open.md) functions create a bus socket. +This socket may be used to send and receive messages. +Sending messages will attempt to deliver to each directly connected peer. + +## Protocol Versions + +Only version 0 of this protocol is supported. +(At the time of writing, no other versions of this protocol have been defined.) + +## Protocol Options + +The _BUS_ protocol has no protocol-specific options. + +## Protocol Headers + +When using a _BUS_ socket in [raw mode](../overview/raw.md), received messages will +contain the incoming [pipe](../api/nng_pipe.md) ID as the sole element in the header. +If a message containing such a header is sent using a raw _BUS_ socket, then, +the message will be delivered to all connected pipes _except_ the one +identified in the header. +This behavior is intended for use with [device](../api/nng_device.md) +configurations consisting of just a single socket. +Such configurations are useful in the creation of rebroadcasters, and this +capability prevents a message from being routed back to its source. +If no header is present, then a message is sent to all connected pipes. + +When using normal (cooked mode) _BUS_ sockets, no message headers are present. diff --git a/docs/reference/src/protocols/index.md b/docs/reference/src/protocols/index.md new file mode 100644 index 00000000..8d9f7317 --- /dev/null +++ b/docs/reference/src/protocols/index.md @@ -0,0 +1 @@ +# Protocols diff --git a/docs/reference/src/transports/index.md b/docs/reference/src/transports/index.md new file mode 100644 index 00000000..c7d74d80 --- /dev/null +++ b/docs/reference/src/transports/index.md @@ -0,0 +1,5 @@ +# Transports + +This chapter provides information about the various transports that _NNG_ supports. +Transports may be thought of as different underlying communications +technologies, such as TCP, Websockets, and so forth. diff --git a/docs/reference/src/transports/tcp.md b/docs/reference/src/transports/tcp.md new file mode 100644 index 00000000..54e36b67 --- /dev/null +++ b/docs/reference/src/transports/tcp.md @@ -0,0 +1,74 @@ +# TCP transport + +{{hi: transport, _tcp_}} +The {{i:_tcp_ transport}} provides communication support between +sockets across a {{i:TCP/IP}} network. + +Both IPv4 and IPv6 are supported when the underlying platform also supports it. + +This transport is built-in, so no extra steps to use it should be necessary. + +## URI Format + +{{hi:URI, `tcp://`}} +This transport uses URIs using the scheme `tcp://`, followed by +an IP address or hostname, followed by a colon and finally a +TCP port number.{{hi:port number, TCP}} +For example, to contact port 80 on the localhost either of the following URIs +could be used: `tcp://127.0.0.1:80` or `tcp://localhost:80`. + +A URI may be restricted to IPv6 using the scheme `tcp6://`, and may +be restricted to IPv4 using the scheme `tcp4://`. + +> [!NOTE] +> Specifying `tcp6://` may not prevent IPv4 hosts from being used with +> IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with +> listeners. +> The details of this varies across operating systems. + +> [!NOTE] +> Both `tcp6://` and `tcp4://` are specific to _NNG_, and might not +> be understood by other implementations. + +> [!TIP] +> We recommend using either numeric IP addresses, or names that are +> specific to either IPv4 or IPv6 to prevent confusion and surprises. + +When specifying IPv6 addresses, the address must be enclosed in +square brackets (`[]`) to avoid confusion with the final colon +separating the port. + +For example, the same port 80 on the IPv6 loopback address (`::1`) would +be specified as `tcp://[::1]:80`. + +The special value of 0 ({{i:`INADDR_ANY`}}) +can be used for a listener to indicate that it should listen on all +interfaces on the host. +A short-hand for this form is to either omit the address, or specify +the asterisk (`*`) character. +For example, the following three URIs are all equivalent, +and could be used to listen to port 9999 on the host: + +1. `tcp://0.0.0.0:9999` +2. `tcp://*:9999` +3. `tcp://:9999` + +The entire URI must be less than `NNG_MAXADDRLEN` bytes long. + +## Socket Address + +When using an [`nng_sockaddr`](../api/nng_sockaddr.md) structure, +the actual structure is either of type +[`nng_sockaddr_in`](../api/nng_sockaddr_in.md) (for IPv4) or +[`nng_sockaddr_in6`](../api/nng_sockaddr_in6.md) (for IPv6). + +## Transport Options + +The following transport options are supported by this transport, +where supported by the underlying platform. + +- [`NNG_OPT_LOCADDR`](../api/nng_options.md#NNG_OPT_LOCADDR) +- [`NNG_OPT_REMADDR`](../api/nng_options.md#NNG_OPT_REMADDR) +- [`NNG_OPT_TCP_KEEPALIVE`](../api/nng_tcp_options.md#NNG_OPT_TCP_KEEPALIVE) +- [`NNG_OPT_TCP_NODELAY`](../api/nng_tcp_options.md#NNG_OPT_TCP_NODELAY) +- [`NNG_OPT_URL`](../api/nng_options.md#NNG_OPT_URL) -- cgit v1.2.3-70-g09d2