From 7b34141bbb774c3a97c8f983fd2f5d460eeffbae Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 30 Mar 2024 20:58:59 -0700 Subject: I/O provider reorg --- docs/reference/src/SUMMARY.md | 12 ++--- 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/iop/index.md | 23 +++++++++ docs/reference/src/iop/nng_aio_begin.md | 46 +++++++++++++++++ docs/reference/src/iop/nng_aio_defer.md | 60 ++++++++++++++++++++++ docs/reference/src/iop/nng_aio_finish.md | 41 +++++++++++++++ docs/reference/src/iop/nng_aio_get_input.md | 36 +++++++++++++ docs/reference/src/iop/nng_aio_set_output.md | 38 ++++++++++++++ docs/reference/src/refs.md | 15 ++++++ docs/reference/src/tran/index.md | 4 +- docs/reference/src/util/index.md | 10 ++-- 16 files changed, 273 insertions(+), 244 deletions(-) delete mode 100644 docs/reference/src/api/aio_provider/index.md delete mode 100644 docs/reference/src/api/aio_provider/nng_aio_begin.md delete mode 100644 docs/reference/src/api/aio_provider/nng_aio_defer.md delete mode 100644 docs/reference/src/api/aio_provider/nng_aio_finish.md delete mode 100644 docs/reference/src/api/aio_provider/nng_aio_get_input.md delete mode 100644 docs/reference/src/api/aio_provider/nng_aio_set_output.md create mode 100644 docs/reference/src/iop/index.md create mode 100644 docs/reference/src/iop/nng_aio_begin.md create mode 100644 docs/reference/src/iop/nng_aio_defer.md create mode 100644 docs/reference/src/iop/nng_aio_finish.md create mode 100644 docs/reference/src/iop/nng_aio_get_input.md create mode 100644 docs/reference/src/iop/nng_aio_set_output.md diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index 48fdc8df..fe9913f2 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -87,13 +87,13 @@ - [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) + - [I/O Provider API](iop/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) + - [nng_aio_begin](iop/nng_aio_begin.md) + - [nng_aio_defer](iop/nng_aio_defer.md) + - [nng_aio_finish](iop/nng_aio_finish.md) + - [nng_aio_get_input](iop/nng_aio_get_input.md) + - [nng_aio_set_output](iop/nng_aio_set_output.md) - [Utility Functions](util/index.md) diff --git a/docs/reference/src/api/aio_provider/index.md b/docs/reference/src/api/aio_provider/index.md deleted file mode 100644 index 8fcaeeb0..00000000 --- a/docs/reference/src/api/aio_provider/index.md +++ /dev/null @@ -1,21 +0,0 @@ -# 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 deleted file mode 100644 index 59f21112..00000000 --- a/docs/reference/src/api/aio_provider/nng_aio_begin.md +++ /dev/null @@ -1,44 +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_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 deleted file mode 100644 index e7782761..00000000 --- a/docs/reference/src/api/aio_provider/nng_aio_defer.md +++ /dev/null @@ -1,58 +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](../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 deleted file mode 100644 index 215f6716..00000000 --- a/docs/reference/src/api/aio_provider/nng_aio_finish.md +++ /dev/null @@ -1,39 +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()`](../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](../aio/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 deleted file mode 100644 index 598a5a47..00000000 --- a/docs/reference/src/api/aio_provider/nng_aio_get_input.md +++ /dev/null @@ -1,34 +0,0 @@ -# nng_aio_get_input - -## 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()`](../aio/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 deleted file mode 100644 index 11761352..00000000 --- a/docs/reference/src/api/aio_provider/nng_aio_set_output.md +++ /dev/null @@ -1,36 +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()`](../aio/nng_aio_get_output.md) function. - -## SEE ALSO - -[nng_aio_get_output](../aio/nng_aio_get_output.md) diff --git a/docs/reference/src/iop/index.md b/docs/reference/src/iop/index.md new file mode 100644 index 00000000..677ac347 --- /dev/null +++ b/docs/reference/src/iop/index.md @@ -0,0 +1,23 @@ +# 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], +[nng_aio_defer][nng_aio_defer], +[nng_aio_finish][nng_aio_finish], +[nng_aio_get_input][nng_aio_get_input], +[nng_aio_set_output][nng_aio_set_output], +[Asynchronous I/O][aio] + +{{#include ../refs.md}} diff --git a/docs/reference/src/iop/nng_aio_begin.md b/docs/reference/src/iop/nng_aio_begin.md new file mode 100644 index 00000000..39f8cc4b --- /dev/null +++ b/docs/reference/src/iop/nng_aio_begin.md @@ -0,0 +1,46 @@ +# 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] 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][nng_aio_cancel], +[nng_aio_defer][nng_aio_defer], +[nng_aio_finish][nng_aio_finish] + +{{#include ../refs.md}} diff --git a/docs/reference/src/iop/nng_aio_defer.md b/docs/reference/src/iop/nng_aio_defer.md new file mode 100644 index 00000000..df43d7ca --- /dev/null +++ b/docs/reference/src/iop/nng_aio_defer.md @@ -0,0 +1,60 @@ +# 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] is called, with the +error code specified by _err_. + +> [!IMPORTANT] +> It is mandatory that I/O providers call [`nng_aio_finish()`][nng_aio_finish] _*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], +[nng_aio_cancel][nng_aio_cancel], +[nng_aio_finish][nng_aio_finish] + +{{#include ../refs.md}} diff --git a/docs/reference/src/iop/nng_aio_finish.md b/docs/reference/src/iop/nng_aio_finish.md new file mode 100644 index 00000000..da922f76 --- /dev/null +++ b/docs/reference/src/iop/nng_aio_finish.md @@ -0,0 +1,41 @@ +# 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]. + +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], +[nng_aio_cancel][nng_aio_cancel], +[nng_aio_defer][nng_aio_defer], +[nng_aio_result][nng_aio_result] + +{{#include ../refs.md}} diff --git a/docs/reference/src/iop/nng_aio_get_input.md b/docs/reference/src/iop/nng_aio_get_input.md new file mode 100644 index 00000000..28f798bd --- /dev/null +++ b/docs/reference/src/iop/nng_aio_get_input.md @@ -0,0 +1,36 @@ +# nng_aio_get_input + +## 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]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], +[nng_aio_get_output][nng_aio_get_output], +[nng_aio_set_input][nng_aio_set_input] + +{{#include ../refs.md}} diff --git a/docs/reference/src/iop/nng_aio_set_output.md b/docs/reference/src/iop/nng_aio_set_output.md new file mode 100644 index 00000000..568d765d --- /dev/null +++ b/docs/reference/src/iop/nng_aio_set_output.md @@ -0,0 +1,38 @@ +# 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] function. + +## SEE ALSO + +[nng_aio_get_output][nng_aio_get_output] + +{{#include ../refs.md}} diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md index 5c67ab09..44dd69a3 100644 --- a/docs/reference/src/refs.md +++ b/docs/reference/src/refs.md @@ -27,6 +27,13 @@ [sub]: ../proto/sub.md [surveyor]: ../proto/surveyor.md + + +[inproc]: ../tran/inproc.md +[ipc]: ../tran/ipc.md +[tls]: ../tran/tls.md +[tcp]: ../tran/tcp.md + [nng_bus_open]: ../sock/nng_bus_open.md @@ -99,6 +106,14 @@ [nng_aio_stop]: ../aio/nng_aio_stop.md [nng_aio_wait]: ../aio/nng_aio_wait.md + + +[nng_aio_begin]: ../iop/nng_aio_begin.md +[nng_aio_defer]: ../iop/nng_aio_defer.md +[nng_aio_finish]: ../iop/nng_aio_finish.md +[nng_aio_get_input]: ../iop/nng_aio_get_input.md +[nng_aio_set_output]: ../iop/nng_aio_set_output.md + [nng_cv_alloc]: ../thr/nng_cv_alloc.md diff --git a/docs/reference/src/tran/index.md b/docs/reference/src/tran/index.md index 2e61d68d..cec3ae04 100644 --- a/docs/reference/src/tran/index.md +++ b/docs/reference/src/tran/index.md @@ -10,4 +10,6 @@ The [{{i:*inproc* transport}}][inproc] provides {{i: intra-process}} communicati ## TCP -The [{{i:*tcp* transport}}][tcp] provides communication over {{i:TCP/IP}} networks. +The {{hi:*tcp* transport}}[_tcp_ transport][tcp] provides communication over {{i:TCP/IP}} networks. + +{{#include ../refs.md}} diff --git a/docs/reference/src/util/index.md b/docs/reference/src/util/index.md index 0d7db007..3a91f69c 100644 --- a/docs/reference/src/util/index.md +++ b/docs/reference/src/util/index.md @@ -2,10 +2,10 @@ # See Also -[nng_alloc()][nng_alloc], -[nng_clock()][nng_clock], -[nng_free()][nng_free], -[nng_random()][nng_random], -[nng_version()][nng_version] +[nng_alloc][nng_alloc], +[nng_clock][nng_clock], +[nng_free][nng_free], +[nng_random][nng_random], +[nng_version][nng_version] {{#include ../refs.md}} -- cgit v1.2.3-70-g09d2