diff --git a/docs/man/nng_aio_alloc.3.adoc b/docs/man/nng_aio_alloc.3.adoc deleted file mode 100644 index 6a424e3bc..000000000 --- a/docs/man/nng_aio_alloc.3.adoc +++ /dev/null @@ -1,88 +0,0 @@ -= nng_aio_alloc(3) -// -// Copyright 2022 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_alloc - allocate asynchronous I/O handle - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg); ----- - -== DESCRIPTION - -The `nng_aio_alloc()` function allocates a handle for ((asynchronous I/O)) -operations, and stores a pointer to it in __aiop__. -The handle is initialized with a completion ((callback)) of _callb_, -which will be executed when an associated asynchronous operation finishes. -It will be called with the argument _arg_. - -NOTE: 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 xref:nng_cv_alloc.3supp.adoc[condition variable] -which can be signaled by the callback. - -Asynchronous I/O operations all take an xref:nng_aio.5.adoc[`nng_aio`] -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 -xref:nng_aio_result.3.adoc[`nng_aio_result()`], -xref:nng_aio_count.3.adoc[`nng_aio_count()`], -and xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`]. - -It is possible to wait synchronously for an otherwise asynchronous operation -by using the function xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. -In that case, it is permissible for _callb_ and _arg_ to both be `NULL`. -Note that if these are `NULL`, then it will not be possible to determine when the -operation is complete except by calling the aforementioned -xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. - -== SEE ALSO - -[.text-left] -xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], -xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], -xref:nng_aio_count.3.adoc[nng_aio_count(3)], -xref:nng_aio_free.3.adoc[nng_aio_free(3)], -xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)], -xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(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_set_input.3.adoc[nng_aio_set_input(3)], -xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], -xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], -xref:nng_aio_set_timeout.3.adoc[nng_aio_set_timeout(3)], -xref:nng_aio_stop.3.adoc[nng_aio_stop(3)], -xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_busy.3.adoc b/docs/man/nng_aio_busy.3.adoc deleted file mode 100644 index 4aaf09b53..000000000 --- a/docs/man/nng_aio_busy.3.adoc +++ /dev/null @@ -1,56 +0,0 @@ -= nng_aio_busy(3) -// -// Copyright 2022 Staysail Systems, Inc. -// -// 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_busy - test if asynchronous I/O is busy - -== SYNOPSIS - -[source, 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 -xref:nng_aio_wait.3.adoc[`nng_aio_wait()`] - -NOTE: 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. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_count.3.adoc b/docs/man/nng_aio_count.3.adoc deleted file mode 100644 index daf97710f..000000000 --- a/docs/man/nng_aio_count.3.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= nng_aio_count(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_count - return number of bytes transferred - -== SYNOPSIS - -[source, 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 xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`]). - -NOTE: The return value from this function is undefined if the operation -has not completed yet. -Either call this from the handle's completion callback, -or after waiting for the operation to complete with -xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. - -== RETURN VALUES - -The number of bytes transferred by the operation. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], -xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_free.3.adoc b/docs/man/nng_aio_free.3.adoc deleted file mode 100644 index c2528633e..000000000 --- a/docs/man/nng_aio_free.3.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= nng_aio_free(3) -// -// Copyright 2020 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_free - free asynchronous I/O handle - -== SYNOPSIS - -[source, 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 xref:nng_aio_stop.3.adoc[`nng_aio_stop()`].) - -The `nng_aio_reap()` function is the same as `nng_aio_free()`, but does -its work in a background thread. -This can be useful to discard the _aio_ object from within the callback for the _aio_. - -IMPORTANT: Once either of these functions are called, the _aio_ object is invalid and must not be used again. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_stop.3.adoc[nng_aio_stop(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_get_msg.3.adoc b/docs/man/nng_aio_get_msg.3.adoc deleted file mode 100644 index c4205658e..000000000 --- a/docs/man/nng_aio_get_msg.3.adoc +++ /dev/null @@ -1,49 +0,0 @@ -= nng_aio_get_msg(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_msg - get message from asynchronous receive - -== SYNOPSIS - -[source, 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 xref:nng_recv_aio.3.adoc[`nng_recv_aio()`]) -or that was previously stored with xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`]. - -IMPORTANT: The xref:nng_aio.5.adoc[`nng_aio`] must not have an operation in progress. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], -xref:nng_recv_aio.3.adoc[nng_recv_aio(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_get_output.3.adoc b/docs/man/nng_aio_get_output.3.adoc deleted file mode 100644 index 4dfd67c34..000000000 --- a/docs/man/nng_aio_get_output.3.adoc +++ /dev/null @@ -1,56 +0,0 @@ -= nng_aio_get_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_get_output - return output result - -== SYNOPSIS - -[source, 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 result of the operation, 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_result.3.adoc b/docs/man/nng_aio_result.3.adoc deleted file mode 100644 index e1886a6ee..000000000 --- a/docs/man/nng_aio_result.3.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nng_aio_result(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_result - return result of asynchronous operation - -== SYNOPSIS - -[source, 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 -xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. - -== RETURN VALUES - -The result of the operation, either zero on success, or an error -number on failure. - -== ERRORS - -[horizontal] -`NNG_ETIMEDOUT`:: The operation timed out. -`NNG_ECANCELED`:: The operation was canceled. - -Various other return values are possible depending on the operation. - -== SEE ALSO - -[.text-left] -xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_set_input.3.adoc b/docs/man/nng_aio_set_input.3.adoc deleted file mode 100644 index 37cf3cdd9..000000000 --- a/docs/man/nng_aio_set_input.3.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= nng_aio_set_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_set_input - set input parameter - -== SYNOPSIS - -[source, 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 xref:nng_aio_get_input.3.adoc[`nng_aio_get_input()`] function. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_get_input.3.adoc[nng_aio_get_input(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/man/nng_aio_set_iov.3.adoc b/docs/man/nng_aio_set_iov.3.adoc deleted file mode 100644 index 831280115..000000000 --- a/docs/man/nng_aio_set_iov.3.adoc +++ /dev/null @@ -1,67 +0,0 @@ -= nng_aio_set_iov(3) -// -// Copyright 2021 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_iov - set scatter/gather vector - -== SYNOPSIS - -[source,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 ((scatter/gather)) vector _iov_ on the handle _aio_. - -The _iov_ is a pointer to an array of _niov_ xref:nng_iov.5.adoc[`nng_iov`] -structures, which have the following definition: - -[source,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. - -NOTE: Earlier versions of the library could accept longer scatter-gather lists. -However, no known consumers have ever needed a scatter-gather list longer than 4 vectors. -As a result, the implementation limit was reduced, and heap allocations which could fail were removed. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EINVAL`:: Value of specified _niov_ is too large. - -== 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_count.3.adoc[nng_aio_count(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_iov.5.adoc[nng_iov(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_set_msg.3.adoc b/docs/man/nng_aio_set_msg.3.adoc deleted file mode 100644 index e0ea3e464..000000000 --- a/docs/man/nng_aio_set_msg.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_aio_set_msg(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_msg - set message for asynchronous send - -== SYNOPSIS - -[source, 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 xref:nng_send_aio.3.adoc[`nng_send_aio()`]). - -IMPORTANT: The xref:nng_aio.5.adoc[`nng_aio`] must not have an operation in progress. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], -xref:nng_send_aio.3.adoc[nng_send_aio(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_set_timeout.3.adoc b/docs/man/nng_aio_set_timeout.3.adoc deleted file mode 100644 index a82b0c838..000000000 --- a/docs/man/nng_aio_set_timeout.3.adoc +++ /dev/null @@ -1,74 +0,0 @@ -= nng_aio_set_timeout(3) -// -// Copyright 2023 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_timeout - set asynchronous I/O timeout - -== SYNOPSIS - -[source, 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 _timeout_(((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 xref:nng_clock.3supp.adoc[`nng_clock()`] 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 multiple operations, they will have the same relative -timeout. - -== 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_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_wait.3.adoc b/docs/man/nng_aio_wait.3.adoc deleted file mode 100644 index acac6fdf1..000000000 --- a/docs/man/nng_aio_wait.3.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= nng_aio_wait(3) -// -// Copyright 2023 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_wait - wait for asynchronous I/O operation - -== SYNOPSIS - -[source, 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 xref:nng_aio.5.adoc[`aio`], either this one or any other. -Doing so may result in a deadlock. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_busy.3.adoc[nng_aio_busy(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 5b79644af..ed3e12334 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -14,10 +14,7 @@ - [URLs](./api/url.md) - - [Asynchronous Operations](./api/aio/index.md) - - - [nng_aio](./api/aio/nng_aio.md) - - [aio_cancel](./api/aio/aio_cancel.md) + - [Asynchronous I/O](./api/aio.md) - [Synchronization](./api/synch.md) diff --git a/docs/ref/api/aio.md b/docs/ref/api/aio.md new file mode 100644 index 000000000..230744e88 --- /dev/null +++ b/docs/ref/api/aio.md @@ -0,0 +1,287 @@ +# Asynchronous Operations + +In order to obtain significant scalability, with low-latency, and minimal +overheads, _NNG_ supports performing operations asynchronously. + +One way that applications can perform work asynchronously and concurrently +is by using [threads][thread], but threads carry significant resource overheads +and frequently there are limits on the number that can easily be created. + +Additionally, with most network applications, the flow of execution will spend +the bulk of its time waiting for traffic from a peer. + +For these kinds of applications, it is far more efficient to use asynchronous operations +using the mechanisms described in this chapter. + +> [!TIP] +> To get the highest performance with the least overhead, applications should use +> asynchronous operations described in this chapter whenever possible. + +## Asynchronous I/O Handle + +```c +typedef struct nng_aio nng_aio; +``` + +An {{i:`nng_aio`}}{{hi:aio}} is an opaque structure used in conjunction with +{{i:asynchronous I/O}} operations. +Every asynchronous operation uses one of these structures, each of which +can only be used with a single operation at a time. + +Asynchronous operations are performed without blocking calling application threads. +Instead the application registers a callback function to be executed +when the operation is complete (whether successfully or not). +This callback will be executed exactly once. + +The asynchronous I/O framework also supports [cancellation][`nng_aio_cancel`] of +operations that are already in progress as well setting a maximum +[timeout][`nng_aio_set_timeout`] for them to complete. + +It is also possible to initiate an asynchronous operation, and [wait][`nng_aio_wait`] for it to +complete, creating a synchronous flow from an asynchronous one. + +## Create Handle + +```c +int nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg); +``` + +The {{i:`nng_aio_alloc`}} function creates an [`nng_aio`] object, with the +{{i:callback}} _callb_ taking the argument _arg_, and returns it in _aiop_. + +If this succeeds, the function returns zero. Otherwise it may return [`NNG_ENOMEM`]. + +> [!TIP] +> The _arg_ should normally be a structure that contains a pointer to the _aiop_, +> or from which it can be located. This allows _callb_ to check the handle for +> success using [`nng_aio_result`], as well access other properties of _aiop_. + +> [!TIP] +> The _callb_ may be executed on another [thread], so it may be necessary to use +> [synchronization] methods in _callb_ to avoid data races. + +## Destroy Handle + +```c +void nng_aio_free(nng_aio *aio); +void nng_aio_reap(nng_aio *aio); +``` + +The {{i:`nng_aio_free`}} handle destroys the handle _aio_, waiting for any operations +and associated callbacks to complete before doing so. + +The {{i:`nng_aio_reap`}} handle destroys the handle _aio_ asynchronously, using a _reaper_ +[thread] to do so. It does not wait for the object to be destroyed. Thus this function +is safe to call from _aio_'s own callback. + +> [!NOTE] +> The `nng_aio_free` function must never be called from an _aio_ callback. +> Use `nng_aio_reap` instead if an object must be destroyed from a callback. + +## Cancellation + +```c +void nng_aio_abort(nng_aio *aio, int err); +void nng_aio_cancel(nng_aio *aio); +void nng_aio_stop(nng_aio *aio); +``` + +These functions are used to stop a previously submitted asynchronous +I/O operation. The operation may be canceled, or may continue to +completion. If no operation is in progress (perhaps because it has +already completed), then these operations have no effect. +If the operation is successfully canceled or aborted, then the callback +will still be called. + +The {{i:`nng_aio_abort`}} function aborts the operation associated with _aio_ +and returns immediately without waiting. If cancellation was successful, +then [`nng_aio_result`] will return _err_. + +The {{i:`nng_aio_cancel`}} function acts like `nng_aio_abort`, but uses the error code +[`NNG_ECANCELED`]{{hi:`NNG_ECANCELED`}}. + +The {{i:`nng_aio_stop`}} function aborts the _aio_ operation with [`NNG_ECANCELED`], +and then waits the operation and any associated callback to complete. +This function also marks _aio_ itself permanently stopped, so that any +new operations scheduled by I/O providers using [`nng_aio_begin`] +return false. Thus this function should be used to teardown operations. + +> [!TIP] +> When multiple asynchronous I/O handles are in use and need to be +> deallocated, it is safest to stop all of them using `nng_aio_stop`, +> before deallocating any of them with [`nng_aio_free`], +> particularly if the callbacks might attempt to reschedule further operations. + +## Set Timeout + +```c +void nng_aio_set_timeout(nng_aio *aio, nng_duration timeout); +void nng_aio_set_expire(nng_aio *aio, nng_time expiration); +``` + +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][`nng_aio_abort`] with an error of `NNG_ETIMEDOUT`. +The _timeout_ [duration][time] 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 {{i:`nng_aio_set_expire`}} function is similar to `nng_aio_set_timeout`, but sets +an expiration time based on the system clock. The _expiration_ +[time] is a clock timestamp, such as would be returned by [`nng_clock`]. + +## Wait for Completion + +```c +void nng_aio_wait(nng_aio *aio); +``` + +The {{i:`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] +> The `nng_aio_wait` function should never be called from a function that itself +> is a callback of an [`nng_aio`], either this one or any other. +> Doing so may result in a deadlock. + +## Test for Completion + +```c +bool nng_aio_busy(nng_aio *aio); +``` + +The {{i:`nng_aio_busy`}} function returns `true` if the _aio_ is currently busy performing an +operation or is executing a completion callback. Otherwise it return `false`. +This is the same test used internally by [`nng_aio_wait`]. + +> [!IMPORTANT] +> The caller is responsible for coordinating any use of this with any reuse of the _aio_. +> Because the _aio_ can be reused use of this function can be racy. + +## Result of Operation + +```c +int nng_aio_result(nng_aio *aio); +size_t nng_aio_count(nng_aio *aio); +``` + +The {{i:`nng_aio_result`}} function 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, such as [`NNG_ECANCELED`] or [`NNG_ETIMEDOUT`], is returned. + +For operations that transfer data, {{i:`nng_aio_count`}} returns the +number of bytes transferred by the operation associated with the handle _aio_. +Operations that do not transfer data, or do not keep a count, may return zero for this function. + +> [!NOTE] +> The return value from these functions is undefined if the operation has not completed yet. +> Either call these from the handle's completion callback, or after waiting for the +> operation to complete with [`nng_aio_wait`]. + +## Messages + +```c +nng_msg *nng_aio_get_msg(nng_aio *aio); +void nng_aio_set_msg(nng_aio *aio, nng_msg *msg); +``` + +The {{i:`nng_aio_get_msg`}} and {{i:`nng_aio_set_msg`}} functions retrieve and store a [message] +in _aio_. +For example, if a function to receive data is called, that function can generally be expected +to store a message on the asssociated _aio_, for the application to retrieve with +`nng_aio_get_msg`. +Conversely an application desiring to send a message _msg_ will store it in the _aio_ using +`nng_aio_set_msg`. The function implementing the send operation will retrieve the message +and arrange for it to be sent. + +### Message Ownership + +For send or transmit operations, the rule of thumb is that implementation of the operation +is responsible for taking ownership of the message (and releasing resources when it is complete), +if it will return success. If the operation will end in error, then the message will be +retained and it is the consuming application's responsibility to dispose of the message. +This allows an application the opportunity to reuse the message to try again, if it so desires. + +For receive operations, the implementation of the operation will set the message on the _aio_ +on success, and the consuming application hasa responsibility to retrieve and dispose of the +message. Failure to do so will leak the message. If the operation does not complete successfully, +then no message is stored on the _aio_. + +## I/O Vector + +```c +typedef struct nng_iov { + void * iov_buf; + size_t iov_len; +}; + +int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov); +``` + +For some operations, the unit of data transferred is not a [message], but +rather a stream of bytes. + +For these operations, an array of _niov_ {{i:`nng_iov`}} structures can be passed to +the {{i:`nng_aio_set_iov`}} function to provide a scatter/gather array of +elements describing the location (`iov_buf`) and length (`iov_len`) of data, +to transfer. + +The _iov_ vector 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. + +> [!TIP] +> Most functions using `nng_iov` do not guarantee to transfer all of the data that they +> are requested to. To be sure that correct amount of data is transferred, as well as to +> start an attempt to complete any partial transfer, check the amount of data transferred by +> calling [`nng_aio_count`]. + +## Inputs and Outputs + +```c +void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param); +void *nng_aio_get_output(nng_aio *aio, unsigned int index); +``` + +Asynchronous operations can take additional input parameters, and +provide additional result outputs besides the [result][`nng_aio_result`] code. + +The `nng_aio_set_input` function sets the input parameter at _index_ +to _param_ for the operation associated with _aio_. + +The `nng_aio_get_output` function returns the output result at _index_ +for the operation associated with _aio_. + +The type and semantics of input parameters and output results are determined by specific +operations. The documentation for the operation should provide details. + +The valid values of _index_ range from zero (0) to three (3), as no operation +currently defined can accept more than four parameters or return more than four additional +results. + +> [!NOTE] +> If the _index_ does not correspond to a defined input for the operation, +> then `nng_aio_set_input` will have no effect, and `nng_aio_get_output` will +> return `NULL`. + +> [!IMPORTANT] +> It is an error to call this function while the _aio_ is currently +> in use by an active asynchronous operation. + +## See Also + +[Synchronization][synchronization], +[Threads][thread], +[Time][time] + +{{#include ../xref.md}} diff --git a/docs/ref/api/aio/index.md b/docs/ref/api/aio/index.md deleted file mode 100644 index 1e9872e9a..000000000 --- a/docs/ref/api/aio/index.md +++ /dev/null @@ -1 +0,0 @@ -# Asynchronous I/O Operations diff --git a/docs/ref/api/aio/nng_aio.md b/docs/ref/api/aio/nng_aio.md deleted file mode 100644 index 0fdb6ca1e..000000000 --- a/docs/ref/api/aio/nng_aio.md +++ /dev/null @@ -1,65 +0,0 @@ -# nng_aio - -## NAME - -nng_aio - asynchronous I/O handle - -## SYNOPSIS - -```c -#include - -typedef struct nng_aio nng_aio; -``` - -## DESCRIPTION - -An {{i:`nng_aio`}}{{hi:aio}} is an opaque structure used in conjunction with -{{i:asynchronous I/O}} operations. -Every asynchronous operation uses one of these structures, each of which -can only be used with a single operation at a time. - -Asynchronous operations are performed without blocking calling application threads. -Instead the application registers a callback function to be executed -when the operation is complete (whether successfully or not). -This callback will be executed exactly once. - -The asynchronous I/O framework also supports cancellation of -operations that are already in progress -(see [`nng_aio_cancel`][aio_cancel]), as well setting a maximum -timeout for them to complete within -(see [`nng_aio_set_timeout`][nng_aio_set_timeout]). - -It is also possible to initiate an asynchronous operation, and wait for it to -complete using [`nng_aio_wait`][nng_aio_wait]. - -These structures are created using [`nng_aio_alloc`][nng_aio_alloc], -and destroyed using [`nng_aio_free`][nng_aio_free]. - -## SEE ALSO - -[nng_aio_cancel][aio_cancel], -[nng_aio_alloc][nng_aio_alloc], -[nng_aio_free][nng_aio_free], -[nng_aio_set_timeout][nng_aio_set_timeout] - - - -[aio_cancel]: nng_aio_cancel.md -[nng_aio_alloc]: nng_aio_alloc.md -[nng_aio_free]: nng_aio_free.md -[nng_aio_set_timeout]: nng_aio_set_timeout.md -[nng_aio_wait]: TODO.md diff --git a/docs/ref/api/synch.md b/docs/ref/api/synch.md index 82eee869f..d56fb600b 100644 --- a/docs/ref/api/synch.md +++ b/docs/ref/api/synch.md @@ -172,3 +172,9 @@ one thread (which may be chosen randomly). ``` {{#include ../xref.md}} + +## See Also + +[Threads][thread], +[Time][time], +[Asynchronous I/O][aio] diff --git a/docs/ref/xref.md b/docs/ref/xref.md index d103a73be..3abf999c5 100644 --- a/docs/ref/xref.md +++ b/docs/ref/xref.md @@ -56,8 +56,20 @@ [`nng_send`]: /TODO.md [`nng_recv`]: /TODO.md [`nng_aio`]: /TODO.md +[`nng_aio_alloc`]: /api/aio.md#create-handle +[`nng_aio_free`]: /api/aio.md#destroy-handle [`nng_sleep_aio`]: /TODO.md -[`nng_aio_cancel`]: /TODO.md +[`nng_aio`]: /api/aio.md#asynchronous-i-o-handle +[`nng_aio_cancel`]: /api/aio.md#cancellation +[`nng_aio_abort`]: /api/aio.md#cancellation +[`nng_aio_stop`]: /api/aio.md#cancellation +[`nng_aio_wait`]: /api/api.md#wait-for-completion +[`nng_aio_busy`]: /api/api.md#test-for-completion +[`nng_aio_result`]: /api/api.md#result-of-operation +[`nng_aio_count`]: /api/api.md#result-of-operation +[`nng_aio_begin`]: /TODO.md +[`nng_aio_finish`]: /TODO.md +[`nng_aio_set_timeout`]: /TODO.md [`nng_opts_parse`]: /TODO.md @@ -131,12 +143,13 @@ -[aio]: /TODO.md +[aio]: /api/aio.md [raw]: /TODO.md [pipe]: /TODO.md [socket]: /TODO.md [dialer]: /TODO.md [listener]: /TODO.md +[message]: /api/msg.md [message-body]: /api/msg.md#message-body [message-header]: /api/msg.md#message-header [synchronization]: /api/synch.md @@ -144,3 +157,6 @@ [condvar]: /api/synch.md#condition-variable [thread]: /api/thread.md [statistic]: /api/stats.md +[time]: /api/time.md +[error]: /api/errors.md +[duration]: /api/time.md#duration-type