From 88b32e652e07a195a21d9acf4c394c5cad3a472c Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Thu, 4 Apr 2024 22:03:45 -0700 Subject: I/O provider pages. --- docs/man/nng_aio_begin.3.adoc | 64 ----------------------------- docs/man/nng_aio_defer.3.adoc | 78 ------------------------------------ docs/man/nng_aio_finish.3.adoc | 60 --------------------------- docs/man/nng_aio_get_input.3.adoc | 53 ------------------------ docs/man/nng_aio_set_output.3.adoc | 60 --------------------------- docs/ref/aio/nng_aio_set_iov.adoc | 1 - docs/ref/aio/nng_aio_set_msg.adoc | 1 - docs/ref/iop/nng_aio_begin.adoc | 37 +++++++++++++++++ docs/ref/iop/nng_aio_defer.adoc | 42 +++++++++++++++++++ docs/ref/iop/nng_aio_finish.adoc | 31 ++++++++++++++ docs/ref/iop/nng_aio_get_input.adoc | 27 +++++++++++++ docs/ref/iop/nng_aio_set_output.adoc | 30 ++++++++++++++ 12 files changed, 167 insertions(+), 317 deletions(-) delete mode 100644 docs/man/nng_aio_begin.3.adoc delete mode 100644 docs/man/nng_aio_defer.3.adoc delete mode 100644 docs/man/nng_aio_finish.3.adoc delete mode 100644 docs/man/nng_aio_get_input.3.adoc delete mode 100644 docs/man/nng_aio_set_output.3.adoc create mode 100644 docs/ref/iop/nng_aio_begin.adoc create mode 100644 docs/ref/iop/nng_aio_defer.adoc create mode 100644 docs/ref/iop/nng_aio_finish.adoc create mode 100644 docs/ref/iop/nng_aio_get_input.adoc create mode 100644 docs/ref/iop/nng_aio_set_output.adoc diff --git a/docs/man/nng_aio_begin.3.adoc b/docs/man/nng_aio_begin.3.adoc deleted file mode 100644 index 30a73648..00000000 --- a/docs/man/nng_aio_begin.3.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= nng_aio_begin(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_begin - begin asynchronous I/O operation - -== SYNOPSIS - -[source, 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 -by the caller asynchronously. -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 xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] is called for the _aio_ -exactly once, when the operation is complete or canceled. - -NOTE: 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 - -[horizontal] -`true`:: The operation has been started. -`false`:: The operation cannot be started. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], -xref:nng_aio_defer.3.adoc[nng_aio_defer(3)], -xref:nng_aio_finish.3.adoc[nng_aio_finish(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_defer.3.adoc b/docs/man/nng_aio_defer.3.adoc deleted file mode 100644 index 5664a6df..00000000 --- a/docs/man/nng_aio_defer.3.adoc +++ /dev/null @@ -1,78 +0,0 @@ -= nng_aio_defer(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_defer - defer asynchronous I/O operation - -== SYNOPSIS - -[source, 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, and also registers a cancellation -function _fn_ and associated argument _arg_, thereby -permitting the operation to be canceled. - -If the _aio_ is being 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. - -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 xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] is called, with the -error code specified by _err_. - -IMPORTANT: It is mandatory that I/O providers call -xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] -*EXACTLY ONCE* when they are finished with the operation. - -NOTE: 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. - -NOTE: 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 should not bother to call `nng_aio_defer()`, -although it is harmless if it does. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], -xref:nng_aio_finish.3.adoc[nng_aio_finish(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_finish.3.adoc b/docs/man/nng_aio_finish.3.adoc deleted file mode 100644 index 91ad188e..00000000 --- a/docs/man/nng_aio_finish.3.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_aio_finish(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_finish - finish asynchronous I/O operation - -== SYNOPSIS - -[source, 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 -xref:nng_aio_result.3.adoc[`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 they *must not* perform any further accesses -to the _aio_. - -NOTE: 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. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_begin.3.adoc[nng_aio_begin(3)], -xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], -xref:nng_aio_defer.3.adoc[nng_aio_defer(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_get_input.3.adoc b/docs/man/nng_aio_get_input.3.adoc deleted file mode 100644 index 204ec435..00000000 --- a/docs/man/nng_aio_get_input.3.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= nng_aio_get_input(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_get_input - return input parameter - -== SYNOPSIS - -[source, 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 -xref:nng_aio_set_input.3.adoc[`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. -(This limit could increase in the future.) -If the index supplied is outside of this range, -or of the input parameter was not previously set, then `NULL` is returned. - -== RETURN VALUES - -Value previously set, or `NULL`. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], -xref:nng_aio_set_input.3.adoc[nng_aio_set_input(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_set_output.3.adoc b/docs/man/nng_aio_set_output.3.adoc deleted file mode 100644 index 67f8ac66..00000000 --- a/docs/man/nng_aio_set_output.3.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_aio_set_output(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_set_output - set output result - -== SYNOPSIS - -[source, 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. -(This limit could increase in the future.) - -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 xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`] function. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_finish.3.adoc[nng_aio_finish(3)], -xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/aio/nng_aio_set_iov.adoc b/docs/ref/aio/nng_aio_set_iov.adoc index b4938fcc..2db39ad8 100644 --- a/docs/ref/aio/nng_aio_set_iov.adoc +++ b/docs/ref/aio/nng_aio_set_iov.adoc @@ -43,7 +43,6 @@ This function returns 0 on success, and non-zero otherwise. ### See Also -[.text-left] xref:nng_aio_count.adoc[nng_aio_count], xref:nng_aio_result.adoc[nng_aio_result], xref:nng_iov.5.adoc[nng_iov] diff --git a/docs/ref/aio/nng_aio_set_msg.adoc b/docs/ref/aio/nng_aio_set_msg.adoc index 7dc06841..f808c69f 100644 --- a/docs/ref/aio/nng_aio_set_msg.adoc +++ b/docs/ref/aio/nng_aio_set_msg.adoc @@ -17,7 +17,6 @@ The `nng_aio_set_msg` function sets the message that will be used for an asynchr ### See Also -[.text-left] xref:nng_aio_get_msg.adoc[nng_aio_get_msg], xref:../sock/nng_send_aio.adoc[nng_send_aio], xref:nng_msg.adoc[nng_msg] diff --git a/docs/ref/iop/nng_aio_begin.adoc b/docs/ref/iop/nng_aio_begin.adoc new file mode 100644 index 00000000..a634063c --- /dev/null +++ b/docs/ref/iop/nng_aio_begin.adoc @@ -0,0 +1,37 @@ +## 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 by the caller asynchronously. +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 xref:nng_aio_finish.adoc[`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 + +[horizontal] +`true`:: The operation has been started. +`false`:: The operation cannot be started. + +### See Also + +xref:nng_aio_defer.adoc[nng_aio_defer], +xref:nng_aio_finish.adoc[nng_aio_finish] diff --git a/docs/ref/iop/nng_aio_defer.adoc b/docs/ref/iop/nng_aio_defer.adoc new file mode 100644 index 00000000..7dc3918f --- /dev/null +++ b/docs/ref/iop/nng_aio_defer.adoc @@ -0,0 +1,42 @@ +## 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 the operation associated with _aio_ as 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 for cancellation. + +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 xref:nng_aio_finish.adoc[`nng_aio_finish`] is called, with the error code specified by _err_. + +IMPORTANT: It is mandatory that I/O providers call xref:nng_aio_finish.adoc[`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 thread-safe. +This will usually involve the use of locks or other synchronization primitives. + +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. + + +TIP: When completing an operation synchronously, calling `nng_aio_defer` is unnecessary. + +### See Also + +xref:../aio/nng_aio_cancel.adoc[nng_aio_cancel], +xref:nng_aio_finish.adoc[nng_aio_finish], +xref:../aio/nng_aio_result.adoc[nng_aio_result] diff --git a/docs/ref/iop/nng_aio_finish.adoc b/docs/ref/iop/nng_aio_finish.adoc new file mode 100644 index 00000000..77622fd5 --- /dev/null +++ b/docs/ref/iop/nng_aio_finish.adoc @@ -0,0 +1,31 @@ +## 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 xref:nng_aio_result.adoc[`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 they *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 + +xref:nng_aio_begin.adoc[nng_aio_begin], +xref:../aio/nng_aio_cancel.adoc[nng_aio_cancel], +xref:nng_aio_defer.adoc[nng_aio_defer], +xref:../aio/nng_aio_result.adoc[nng_aio_result] diff --git a/docs/ref/iop/nng_aio_get_input.adoc b/docs/ref/iop/nng_aio_get_input.adoc new file mode 100644 index 00000000..83d1d86d --- /dev/null +++ b/docs/ref/iop/nng_aio_get_input.adoc @@ -0,0 +1,27 @@ +## 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 xref:../aio/nng_aio_set_input.adoc[`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 of the input parameter was not previously set, then `NULL` is returned. + +### Return Values + +Value previously set, or `NULL`. + +### See Also + +xref:../aio/nng_aio_set_input.adoc[nng_aio_set_input], +xref:nng_aio_set_output.adoc[nng_aio_set_output] diff --git a/docs/ref/iop/nng_aio_set_output.adoc b/docs/ref/iop/nng_aio_set_output.adoc new file mode 100644 index 00000000..fc9c90a2 --- /dev/null +++ b/docs/ref/iop/nng_aio_set_output.adoc @@ -0,0 +1,30 @@ +## 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. +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 xref:nng_aio_get_output.adoc[`nng_aio_get_output`] function. + + +### See Also + +xref:nng_aio_get_input.adoc[nng_aio_get_inpput], +xref:../aio/nng_aio_get_output.adoc[nng_aio_get_output] -- cgit v1.2.3-70-g09d2