From de233cfd5c8d6996ce6b6e5946c93b44a24bbbde Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 30 Mar 2024 16:50:42 -0700 Subject: context fixups --- docs/reference/src/SUMMARY.md | 22 +-- docs/reference/src/api/context/index.md | 160 --------------------- docs/reference/src/api/context/nng_ctx_close.md | 41 ------ docs/reference/src/api/context/nng_ctx_get.md | 112 --------------- docs/reference/src/api/context/nng_ctx_getopt.md | 116 ---------------- docs/reference/src/api/context/nng_ctx_id.md | 31 ----- docs/reference/src/api/context/nng_ctx_open.md | 56 -------- docs/reference/src/api/context/nng_ctx_recv.md | 56 -------- docs/reference/src/api/context/nng_ctx_recvmsg.md | 50 ------- docs/reference/src/api/context/nng_ctx_send.md | 68 --------- docs/reference/src/api/context/nng_ctx_sendmsg.md | 67 --------- docs/reference/src/api/context/nng_ctx_set.md | 94 ------------- docs/reference/src/api/context/nng_ctx_setopt.md | 98 ------------- docs/reference/src/ctx/index.md | 162 ++++++++++++++++++++++ docs/reference/src/ctx/nng_ctx_close.md | 43 ++++++ docs/reference/src/ctx/nng_ctx_get.md | 114 +++++++++++++++ docs/reference/src/ctx/nng_ctx_getopt.md | 118 ++++++++++++++++ docs/reference/src/ctx/nng_ctx_id.md | 33 +++++ docs/reference/src/ctx/nng_ctx_open.md | 59 ++++++++ docs/reference/src/ctx/nng_ctx_recv.md | 58 ++++++++ docs/reference/src/ctx/nng_ctx_recvmsg.md | 53 +++++++ docs/reference/src/ctx/nng_ctx_send.md | 70 ++++++++++ docs/reference/src/ctx/nng_ctx_sendmsg.md | 69 +++++++++ docs/reference/src/ctx/nng_ctx_set.md | 96 +++++++++++++ docs/reference/src/ctx/nng_ctx_setopt.md | 100 +++++++++++++ docs/reference/src/refs.md | 18 ++- 26 files changed, 1003 insertions(+), 961 deletions(-) delete mode 100644 docs/reference/src/api/context/index.md delete mode 100644 docs/reference/src/api/context/nng_ctx_close.md delete mode 100644 docs/reference/src/api/context/nng_ctx_get.md delete mode 100644 docs/reference/src/api/context/nng_ctx_getopt.md delete mode 100644 docs/reference/src/api/context/nng_ctx_id.md delete mode 100644 docs/reference/src/api/context/nng_ctx_open.md delete mode 100644 docs/reference/src/api/context/nng_ctx_recv.md delete mode 100644 docs/reference/src/api/context/nng_ctx_recvmsg.md delete mode 100644 docs/reference/src/api/context/nng_ctx_send.md delete mode 100644 docs/reference/src/api/context/nng_ctx_sendmsg.md delete mode 100644 docs/reference/src/api/context/nng_ctx_set.md delete mode 100644 docs/reference/src/api/context/nng_ctx_setopt.md create mode 100644 docs/reference/src/ctx/index.md create mode 100644 docs/reference/src/ctx/nng_ctx_close.md create mode 100644 docs/reference/src/ctx/nng_ctx_get.md create mode 100644 docs/reference/src/ctx/nng_ctx_getopt.md create mode 100644 docs/reference/src/ctx/nng_ctx_id.md create mode 100644 docs/reference/src/ctx/nng_ctx_open.md create mode 100644 docs/reference/src/ctx/nng_ctx_recv.md create mode 100644 docs/reference/src/ctx/nng_ctx_recvmsg.md create mode 100644 docs/reference/src/ctx/nng_ctx_send.md create mode 100644 docs/reference/src/ctx/nng_ctx_sendmsg.md create mode 100644 docs/reference/src/ctx/nng_ctx_set.md create mode 100644 docs/reference/src/ctx/nng_ctx_setopt.md (limited to 'docs/reference') diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index d6aaf9cb..50cf1668 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -59,17 +59,17 @@ - [Contexts](api/context/index.md) - - [nng_ctx_close](api/context/nng_ctx_close.md) - - [nng_ctx_get](api/context/nng_ctx_get.md) - - [nng_ctx_getopt](api/context/nng_ctx_getopt.md) - - [nng_ctx_id](api/context/nng_ctx_id.md) - - [nng_ctx_open](api/context/nng_ctx_open.md) - - [nng_ctx_recv](api/context/nng_ctx_recv.md) - - [nng_ctx_recvmsg](api/context/nng_ctx_recvmsg.md) - - [nng_ctx_send](api/context/nng_ctx_send.md) - - [nng_ctx_sendmsg](api/context/nng_ctx_sendmsg.md) - - [nng_ctx_set](api/context/nng_ctx_set.md) - - [nng_ctx_setopt](api/context/nng_ctx_setopt.md) + - [nng_ctx_close](ctx/nng_ctx_close.md) + - [nng_ctx_get](ctx/nng_ctx_get.md) + - [nng_ctx_getopt](ctx/nng_ctx_getopt.md) + - [nng_ctx_id](ctx/nng_ctx_id.md) + - [nng_ctx_open](ctx/nng_ctx_open.md) + - [nng_ctx_recv](ctx/nng_ctx_recv.md) + - [nng_ctx_recvmsg](ctx/nng_ctx_recvmsg.md) + - [nng_ctx_send](ctx/nng_ctx_send.md) + - [nng_ctx_sendmsg](ctx/nng_ctx_sendmsg.md) + - [nng_ctx_set](ctx/nng_ctx_set.md) + - [nng_ctx_setopt](ctx/nng_ctx_setopt.md) - [Asynchronous I/O](./api/aio/index.md) diff --git a/docs/reference/src/api/context/index.md b/docs/reference/src/api/context/index.md deleted file mode 100644 index d5a3fc90..00000000 --- a/docs/reference/src/api/context/index.md +++ /dev/null @@ -1,160 +0,0 @@ -# nng_ctx - -## NAME - -nng_ctx --- protocol context - -## SYNOPSIS - -```c -#include - -typedef struct nng_ctx_s nng_ctx -``` - -## DESCRIPTION - -An `nng_ctx`{{hi:context}} is a handle to an underlying context object, -which keeps the protocol state for some stateful protocols. -The purpose of a separate context object is to permit applications to -share a single [socket](../socket/index.md), with its various underlying -[dialers](nng_dialer.md), -[listeners](nng_listener.md), -[pipes](nng_pipe.md), -while still benefiting from separate state tracking. - -For example, a [_REQ_](../protocols/req.md) context will contain the request ID -of any sent request, a timer to retry the request on failure, and so forth. -A separate context on the same socket can have similar data, but corresponding -to a completely different request. - -> [!NOTE] -> The `nng_ctx` structure is always passed by value (both -> for input parameters and return values), and should be treated opaquely. -> Passing structures this way gives the compiler a chance to perform -> accurate type checks in functions passing values of this type. - -All contexts share the same socket, and so some options, as well as the -underlying transport details, will be common to all contexts on that socket. - -Protocols that make use of contexts will also have a default context -that is used when the socket global operations are used. -Operations using the global context will generally not interfere with -any other contexts, except that certain socket options may affect socket -global behavior. - -{{hi:concurrent}}{{hi:raw mode}} -Historically, applications wanting to use a stateful protocol concurrently -would have to resort to [raw mode](../overview/raw.md) sockets, which bypasses -much of the various protocol handling, leaving it to up to the application -to do so. -Contexts make it possible to still benefit from advanced protocol handling, -including timeouts, retries, and matching requests to responses, while doing so -concurrently. - -> [!TIP] -> Contexts are an excellent mechanism to use when building concurrent -> applications, and should be used in lieu of -> [raw mode](../overview/raw.md) sockets when possible. - -## Caveats - -Not every protocol supports separate contexts. -See the protocol-specific documentation for further details about whether -contexts are supported, and details about what options are supported for -contexts. - -Use of file descriptor polling (with descriptors obtained using the -[`NNG_OPT_RECVFD`](nng_options.md#NNG_OPT_RECVFD) or -[`NNG_OPT_SENDFD`](nng_options.md#NNG_OPT_SENDFD) options) while contexts -are in use on the same socket is not supported, and may lead to unpredictable -behavior. These asynchronous methods should not be mixed on the same socket. - -[Raw mode](../overview/raw.md) sockets do not support contexts, since -there is generally no state tracked for them, and thus contexts make no sense. - -## Initialization - -A context may be initialized using the macro `NNG_CTX_INITIALIZER` -before it is opened, to prevent confusion with valid open contexts. - -## Example - -The following program fragment demonstrates the use of contexts to implement -a concurrent [_REP_](../protocols/rep.md) service that simply echos messages back -to the sender. - -```c -struct echo_context { - nng_ctx ctx; - nng_aio *aio; - enum { INIT, RECV, SEND } state; -}; - -void -echo(void *arg) -{ - struct echo_context *ec = arg; - - switch (ec->state) { - case INIT: - ec->state = RECV; - nng_ctx_recv(ec->ctx, ec->aio); - return; - case RECV: - if (nng_aio_result(ec->aio) != 0) { - // ... handle error - } - // We reuse the message on the ec->aio - ec->state = SEND; - nng_ctx_send(ec->ctx, ec->aio); - return; - case SEND: - if (nng_aio_result(ec->aio) != 0) { - // ... handle error - } - ec->state = RECV; - nng_ctx_recv(ec->ctx, ec->aio); - return; - } -} -``` - -Given the above fragment, the following example shows setting up the -service. It assumes that the [socket](nng_socket.md) has already been -created and any transports set up as well with functions such as -[`nng_dial()`](nng_dial.md) or [`nng_listen()`](nng_listen.md). - -```c -#define CONCURRENCY 1024 - -echo_context ecs[CONCURRENCY]; - -void -start_echo_service(nng_socket rep_socket) -{ - for (int i = 0; i < CONCURRENCY; i++) { - // error checks elided for clarity - nng_ctx_open(ec[i].ctx, rep_socket) - nng_aio_alloc(ec[i].aio, echo, &e[i]); - ec[i].state = INIT; - echo(&ec[i]); // start it running - } -} -``` - -## SEE ALSO - -[nng_ctx_close](nng_ctx_close.md), -[nng_ctx_open](nng_ctx_open.md), -[nng_ctx_get](nng_ctx_get.md), -[nng_ctx_id](nng_ctx_id.md) -[nng_ctx_recv](nng_ctx_recv.md), -[nng_ctx_recvmsg](nng_ctx_recvmsg.md), -[nng_ctx_send](nng_ctx_send.md), -[nng_ctx_sendmsg](nng_ctx_sendmsg.md), -[nng_ctx_set](nng_ctx_set.md), -[nng_dialer](nng_dialer.md), -[nng_listener](nng_listener.md), -[nng_socket](../socket/index.md), -[nng_options](nng_options.md) diff --git a/docs/reference/src/api/context/nng_ctx_close.md b/docs/reference/src/api/context/nng_ctx_close.md deleted file mode 100644 index e33dd843..00000000 --- a/docs/reference/src/api/context/nng_ctx_close.md +++ /dev/null @@ -1,41 +0,0 @@ -# nng_ctx_close - -## NAME - -nng_ctx_close --- close context - -## SYNOPSIS - -```c -#include - -int nng_ctx_close(nng_ctx ctx); -``` - -## DESCRIPTION - -The `nng_ctx_close()` function closes the context _ctx_. -Messages that have been submitted for sending may be flushed or delivered, -depending upon the transport. - -Further attempts to use the context after this call returns will result -in `NNG_ECLOSED`. -Threads waiting for operations on the context when this -call is executed may also return with an `NNG_ECLOSED` result. - -> [!NOTE] -> Closing the socket associated with _ctx_ -> (using [`nng_close()`](../socket/nng_close.md)) also closes this context. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ECLOSED`: The context _ctx_ is already closed or was never opened. - -## SEE ALSO - -[nng_close](nng_close.md), -[nng_ctx_open](nng_ctx_open.md) diff --git a/docs/reference/src/api/context/nng_ctx_get.md b/docs/reference/src/api/context/nng_ctx_get.md deleted file mode 100644 index 35407f18..00000000 --- a/docs/reference/src/api/context/nng_ctx_get.md +++ /dev/null @@ -1,112 +0,0 @@ -# nng_ctx_get - -## NAME - -nng_ctx_get --- get context option - -## SYNOPSIS - -```c -#include - -int nng_ctx_get(nng_ctx ctx, const char *opt, void *val, size_t *valszp); - -int nng_ctx_get_bool(nng_ctx ctx, const char *opt, bool *bvalp); - -int nng_ctx_get_int(nng_ctx ctx, const char *opt, int *ivalp); - -int nng_ctx_get_ms(nng_ctx ctx, const char *opt, nng_duration *durp); - -int nng_ctx_get_size(nng_ctx ctx, const char *opt, size_t *zp); - -int nng_ctx_get_string(nng_ctx ctx, const char *opt, char **strp); - -int nng_ctx_get_uint64(nng_ctx ctx, const char *opt, uint64_t *u64p); -``` - -## DESCRIPTION - -{{hi:options, context}} -The `nng_ctx_get()` functions are used to retrieve option values for -the [context](index.md) _ctx_. -The actual options that may be retrieved in this way vary. -A number of them are documented in [nng_options](../socket/nng_options.md). - -> [!NOTE] -> Context options are protocol specific. -> The details will be documented with the protocol. - -### Forms - -In all of these forms, the option _opt_ is retrieved from the context _ctx_. -The forms vary based on the type of the option they take. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -- `nng_ctx_get()`:\ - This function is untyped and can be used to retrieve the value of any option. - The caller must store a pointer to a buffer to receive the value in _val_, - and the size of the buffer shall be stored at the location referenced by - _valszp_.\ - \ - When the function returns, the actual size of the data copied (or that - would have been copied if sufficient space were present) is stored at - the location referenced by _valszp_. - If the caller's buffer is not large enough to hold the entire object, - then the copy is truncated. - Therefore the caller should check for truncation by verifying that the - returned size in _valszp_ does not exceed the original buffer size.\ - \ - It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. - This can be used to determine the size of the buffer needed to receive - the object. - -- `nng_ctx_get_bool()`:\ - This function is for options which take a Boolean (`bool`). - The value will be stored at _ivalp_. - -- `nng_ctx_get_int()`:\ - This function is for options which take an integer (`int`). - The value will be stored at _ivalp_. - -- `nng_ctx_get_ms()`:\ - This function is used to retrieve time [durations](nng_duration.md) - (such as timeouts), stored in _durp_ as a number of milliseconds. - (The special value {{i:`NNG_DURATION_INFINITE`}} means an infinite amount of time, and - the special value {{i:`NNG_DURATION_DEFAULT`}} means a context-specific default.) -- `nng_ctx_get_size()`:\ - This function is used to retrieve a size into the pointer _zp_, - typically for buffer sizes, message maximum sizes, and similar options. -- `nng_ctx_get_string()`:\ - This function is used to retrieve a string into _strp_. - This string is created from the source using [`nng_strdup()`](nng_strdup.md) - and consequently must be freed by the caller using - [`nng_strfree()`](nng_strfree.md) when it is no longer needed. - -- `nng_ctx_get_uint64()`:\ - This function is used to retrieve a 64-bit unsigned value into the value - referenced by _u64p_. - This is typically used for options related to identifiers, network - numbers, and similar. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_EBADTYPE`: Incorrect type for option. -- `NNG_ECLOSED`: Parameter _s_ does not refer to an open socket. -- `NNG_EINVAL`: Size of destination _val_ too small for object. -- `NNG_ENOMEM`: Insufficient memory exists. -- `NNG_ENOTSUP`: The option _opt_ is not supported. -- `NNG_EWRITEONLY`: The option _opt_ is write-only. - -## SEE ALSO - -[nng_ctx_set](nng_ctx_set.md), -[nng_strdup](nng_strdup.md), -[nng_strfree](nng_strfree.md), -[nng_duration](nng_duration.md), -[nng_options](../socket/nng_options.md) diff --git a/docs/reference/src/api/context/nng_ctx_getopt.md b/docs/reference/src/api/context/nng_ctx_getopt.md deleted file mode 100644 index 83a648d0..00000000 --- a/docs/reference/src/api/context/nng_ctx_getopt.md +++ /dev/null @@ -1,116 +0,0 @@ -# nng_ctx_getopt - -## NAME - -nng_ctx_getopt --- get context option (deprecated) - -## SYNOPSIS - -```c -#include - -int nng_ctx_getopt(nng_ctx ctx, const char *opt, void *val, size_t *valszp); - -int nng_ctx_getopt_bool(nng_ctx ctx, const char *opt, bool *bvalp); - -int nng_ctx_getopt_int(nng_ctx ctx, const char *opt, int *ivalp); - -int nng_ctx_getopt_ms(nng_ctx ctx, const char *opt, nng_duration *durp); - -int nng_ctx_getopt_size(nng_ctx ctx, const char *opt, size_t *zp); - -int nng_ctx_getopt_string(nng_ctx ctx, const char *opt, char **strp); - -int nng_ctx_getopt_uint64(nng_ctx ctx, const char *opt, uint64_t *u64p); -``` - -## DESCRIPTION - -> [!IMPORTANT] -> These functions are deprecated. Please see [nng_ctx_get](nng_ctx_get.md). -> They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. -> They may also be removed entirely in a future version of _NNG_. - -The `nng_ctx_getopt()` functions are used to retrieve option values for -the [context](index.md) _ctx_. -The actual options that may be retrieved in this way vary. - -> [!NOTE] -> Context options are protocol specific. -> The details will be documented with the protocol. - -### Forms - -In all of these forms, the option _opt_ is retrieved from the context _ctx_. -The forms vary based on the type of the option they take. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -- `nng_ctx_getopt()`:\ - This function is untyped and can be used to retrieve the value of any option. - The caller must store a pointer to a buffer to receive the value in _val_, - and the size of the buffer shall be stored at the location referenced by - _valszp_.\ - \ - When the function returns, the actual size of the data copied (or that - would have been copied if sufficient space were present) is stored at - the location referenced by _valszp_. - If the caller's buffer is not large enough to hold the entire object, - then the copy is truncated. - Therefore the caller should check for truncation by verifying that the - returned size in _valszp_ does not exceed the original buffer size.\ - \ - It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. - This can be used to determine the size of the buffer needed to receive - the object. - -- `nng_ctx_getopt_bool()`:\ - This function is for options which take a Boolean (`bool`). - The value will be stored at _ivalp_. - -- `nng_ctx_getopt_int()`:\ - This function is for options which take an integer (`int`). - The value will be stored at _ivalp_. - -- `nng_ctx_getopt_ms()`:\ - This function is used to retrieve time [durations](nng_duration.md) - (such as timeouts), stored in _durp_ as a number of milliseconds. - (The special value `NNG_DURATION_INFINITE` means an infinite amount of time, and - the special value `NNG_DURATION_DEFAULT` means a context-specific default.) - -- `nng_ctx_getopt_size()`:\ - This function is used to retrieve a size into the pointer _zp_, - typically for buffer sizes, message maximum sizes, and similar options. - -- `nng_ctx_getopt_string()`:\ - This function is used to retrieve a string into _strp_. - This string is created from the source using [`nng_strdup()`](../util/nng_strdup.md) - and consequently must be freed by the caller using - [`nng_strfree()`](../util/nng_strfree.md) when it is no longer needed. - -- `nng_ctx_getopt_uint64()`:\ - This function is used to retrieve a 64-bit unsigned value into the value - referenced by _u64p_. - This is typically used for options related to identifiers, network - numbers, and similar. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_EBADTYPE`: Incorrect type for option. -- `NNG_ECLOSED`: Parameter _s_ does not refer to an open socket. -- `NNG_EINVAL`: Size of destination _val_ too small for object. -- `NNG_ENOMEM`: Insufficient memory exists. -- `NNG_ENOTSUP`: The option _opt_ is not supported. -- `NNG_EWRITEONLY`: The option _opt_ is write-only. - -## SEE ALSO - -[nng_strdup](../util/nng_strdup.md), -[nng_strfree](../util/nng_strfree.md), -[nng_duration](nng_duration.md), -[nng_options](../socket/nng_options.md) diff --git a/docs/reference/src/api/context/nng_ctx_id.md b/docs/reference/src/api/context/nng_ctx_id.md deleted file mode 100644 index 9d8d7223..00000000 --- a/docs/reference/src/api/context/nng_ctx_id.md +++ /dev/null @@ -1,31 +0,0 @@ -# nng_ctx_id - -## NAME - -nng_ctx_id --- return numeric context identifier - -## SYNOPSIS - -```c -#include - -int nng_ctx_id(nng_ctx c); -``` - -## DESCRIPTION - -The `nng_ctx_id()` function returns a positive identifier for the context _c_, -if it is valid. -Otherwise it returns `-1`. - -> [!NOTE] -> A context is considered valid if it was ever opened with -> [`nng_ctx_open()`](nng_ctx_open.md) function. -> Contexts that are allocated on the stack or statically should be -> initialized with the macro `NNG_CTX_INITIALIZER` to ensure that -> they cannot be confused with a valid context before they are opened. - -## RETURN VALUES - -This function returns the positive value for the context identifier, or -`-1` if the context is invalid. diff --git a/docs/reference/src/api/context/nng_ctx_open.md b/docs/reference/src/api/context/nng_ctx_open.md deleted file mode 100644 index b582e254..00000000 --- a/docs/reference/src/api/context/nng_ctx_open.md +++ /dev/null @@ -1,56 +0,0 @@ -# nng_ctx_open - -## NAME - -nng_ctx_open --- create context - -## SYNOPSIS - -```c -#include - -int nng_ctx_open(nng_ctx *ctxp, nng_socket s); -``` - -## DESCRIPTION - -The `nng_ctx_open()` function creates a separate {{i:context}} to be used with -the socket _s_, -and returns it at the location pointed by _ctxp_. - -> [!NOTE] -> Not every protocol supports creation of separate contexts. - -Contexts allow the independent and concurrent use of stateful operations -using the same socket. -For example, two different contexts created on a -[_REP_](../protocols/rep.md) -socket can each receive requests, and send replies to them, without any -regard to or interference with each other. - -> [!TIP] -> Using contexts is an excellent way to write simpler concurrent -> applications, while retaining the benefits of the protocol-specific -> advanced processing, avoiding the need to bypass that with -> {{hi:raw mode}}[raw mode](../overview/raw.md) sockets. - -> [!NOTE] -> Use of contexts with [raw mode](../overview/raw.md) sockets is -> nonsensical, and not supported. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient memory is available. -- `NNG_ENOTSUP`: The protocol does not support separate contexts, or the socket was opened in raw mode. - -## SEE ALSO - -[nng_ctx_close](nng_ctx_close.md), -[nng_ctx_get](nng_ctx_get.md), -[nng_ctx_recv](nng_ctx_recv.md), -[nng_ctx_send](nng_ctx_send.md), -[nng_ctx_set](nng_ctx_set.md) diff --git a/docs/reference/src/api/context/nng_ctx_recv.md b/docs/reference/src/api/context/nng_ctx_recv.md deleted file mode 100644 index 2ef398ea..00000000 --- a/docs/reference/src/api/context/nng_ctx_recv.md +++ /dev/null @@ -1,56 +0,0 @@ -# nng_ctx_recv - -## NAME - -nng_ctx_recv --- receive message using context asynchronously - -## SYNOPSIS - -```c -#include - -void nng_ctx_recv(nng_ctx ctx, nng_aio *aio); -``` - -## DESCRIPTION - -The `nng_ctx_recv()` receives a [message](../msg/index.md) using the -[context](index.md) _s_ asynchronously. - -When a message is successfully received by the context, it is -stored in the _aio_ by an internal call equivalent to -[`nng_aio_set_msg()`](../aio/nng_aio_set_msg.md), then the completion -callback on the _aio_ is executed. -In this case, [`nng_aio_result()`](../aio/nng_aio_result.md) will -return zero. -The callback function is responsible for retrieving the message -and disposing of it appropriately. - -> [!IMPORTANT] -> Failing to accept and dispose of messages in this -> case can lead to memory leaks. - -If for some reason the asynchronous receive cannot be completed -successfully (including by being canceled or timing out), then -the callback will still be executed, -but [`nng_aio_result()`](../aio/nng_aio_result.md) will be non-zero. - -> [!TIP] -> The semantics of what receiving a message means varies from protocol to -> protocol, so examination of the protocol documentation is encouraged. - -## ERRORS - -The following errors may be set on the _aio_, if the operation fails. - -- `NNG_ECANCELED`: The operation was aborted. -- `NNG_ECLOSED`: The context _ctx_ is not open. -- `NNG_ENOMEM`: Insufficient memory is available. -- `NNG_ENOTSUP`: The protocol for context _ctx_ does not support receiving. -- `NNG_ESTATE`: The context _ctx_ cannot receive data in this state. -- `NNG_ETIMEDOUT`: The receive timeout expired. - -## SEE ALSO - -[Asynchronous I/O](../aio/index.md), -[Messages](../msg/index.md) diff --git a/docs/reference/src/api/context/nng_ctx_recvmsg.md b/docs/reference/src/api/context/nng_ctx_recvmsg.md deleted file mode 100644 index c0065dd3..00000000 --- a/docs/reference/src/api/context/nng_ctx_recvmsg.md +++ /dev/null @@ -1,50 +0,0 @@ -# nng_ctx_recvmsg - -## NAME - -nng_ctx_recvmsg --- receive message using socket - -## SYNOPSIS - -```c -#include - -int nng_ctx_recvmsg(nng_ctx ctx, nng_msg **msgp, int flags); -``` - -## DESCRIPTION - -The `nng_ctx_recvmsg()` receives a message on context _ctx_, storing the -received message at the location pointed to by _msgp_. - -The _flags_ may contain the following value: - -- `NNG_FLAG_NONBLOCK`:\ - The function returns immediately, even if no message is available. - Without this flag, the function will wait until a message is receivable - on the context _ctx_, or any configured timer expires. - -> [!TIP] -> The semantics of what receiving a message means vary from protocol to -> protocol, so examination of the protocol documentation is encouraged. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. -- `NNG_ECLOSED`: The context or socket is not open. -- `NNG_EINVAL`: An invalid set of _flags_ was specified. -- `NNG_ENOMEM`: Insufficient memory is available. -- `NNG_ENOTSUP`: The protocol does not support receiving. -- `NNG_ESTATE`: The context cannot receive data in this state. -- `NNG_ETIMEDOUT`: The operation timed out. - -## SEE ALSO - -[nng_msg_free()](../msg/nng_msg_free.md), -[nng_ctx_open()](nng_ctx_open.md), -[nng_ctx_recv()](nng_ctx_recv.md), -[nng_ctx_sendmsg()](nng_ctx_sendmsg.md) diff --git a/docs/reference/src/api/context/nng_ctx_send.md b/docs/reference/src/api/context/nng_ctx_send.md deleted file mode 100644 index 9caad652..00000000 --- a/docs/reference/src/api/context/nng_ctx_send.md +++ /dev/null @@ -1,68 +0,0 @@ -# nng_ctx_send - -## NAME - -nng_ctx_send --- send message using context asynchronously - -## SYNOPSIS - -```c -#include - -void nng_ctx_send(nng_ctx ctx, nng_aio *aio); -``` - -## DESCRIPTION - -The `nng_ctx_send()` sends a [message](../msg/index.md) using the -[context](nng_ctx.md) _ctx_ asynchronously. - -The message to send must have previously been set on the _aio_ -using the [`nng_aio_set_msg()`](../aio/nng_aio_set_msg.md) function. -The function assumes ownership of the message. - -If the message was successfully queued for delivery to the socket, -then the _aio_ will be completed, and [`nng_aio_result()`](../aio/nng_aio_result.md) -will return zero. -In this case the socket will dispose of the message when it is finished with it. - -> [!NOTE] -> The operation will be completed, and the callback associated -> with the _aio_ executed, as soon as the socket accepts the message -> for sending. -> This does _not_ indicate that the message was actually delivered, as it -> may still be buffered in the sending socket, buffered in the receiving -> socket, or in flight over physical media. - -If the operation fails for any reason (including cancellation or timeout), -then the _aio_ callback will be executed and -[`nng_aio_result()`](../aio/nng_aio_result.md) will return a non-zero error status. -In this case, the callback has a responsibility to retrieve the message from -the _aio_ with [`nng_aio_get_msg()`](../aio/nng_aio_get_msg.md) and dispose of -it appropriately. -(This may include retrying the send operation on the same or a different -socket, or deallocating the message with [`nng_msg_free()`](../msg/nng_msg_free.md). - -> [!TIP] -> The semantics of what sending a message means varies from protocol to -> protocol, so examination of the protocol documentation is encouraged. - -## ERRORS - -- `NNG_ECANCELED`: The operation was aborted. -- `NNG_ECLOSED`: The context _ctx_ is not open. -- `NNG_EMSGSIZE`: The message is too large. -- `NNG_ENOMEM`: Insufficient memory is available. -- `NNG_ENOTSUP`: The protocol for context _ctx_ does not support sending. -- `NNG_ESTATE`: The context _ctx_ cannot send data in this state. -- `NNG_ETIMEDOUT`: The send timeout expired. - -## SEE ALSO - -[nng_aio_get_msg](../aio/nng_aio_get_msg.md), -[nng_aio_set_msg](../aio/nng_aio_set_msg.md), -[nng_ctx_sendmsg](nng_ctx_sendmsg.md), -[nng_msg_alloc](../msg/nng_msg_alloc.md), -[nng_msg_free](../msg/nng_msg_free.md), -[Asynchronous I/O](../aio/index.md), -[Messages](../msg/index.md) diff --git a/docs/reference/src/api/context/nng_ctx_sendmsg.md b/docs/reference/src/api/context/nng_ctx_sendmsg.md deleted file mode 100644 index 346f927d..00000000 --- a/docs/reference/src/api/context/nng_ctx_sendmsg.md +++ /dev/null @@ -1,67 +0,0 @@ -# nng_ctx_sendmsg() - -## NAME - -nng_ctx_sendmsg --- send message using context - -## SYNOPSIS - -```c -#include - -int nng_ctx_sendmsg(nng_ctx c, nng_msg *msg, int flags); -``` - -## DESCRIPTION - -The `nng_ctx_sendmsg()` sends message _msg_ using the context _ctx_. - -If the function returns zero, indicating it has accepted the message for -delivery, then the _msg_ is owned by the socket _s_, and the caller -must not make any further use of it. -The socket will free the message when it is finished. - -If the function returns non-zero, then it is the caller's responsibility -to dispose of the _msg_, which may include freeing it, sending it to -another socket, or simply trying again later. - -> [!TIP] -> The semantics of what sending a message means vary from protocol to -> protocol, so examination of the protocol documentation is encouraged. - -The _flags_ may contain the following value: - -- `NNG_FLAG_NONBLOCK`:\ - The function returns immediately, regardless of whether - the context is able to accept the data or not. - If the context is unable to accept the data (such as if backpressure exists - because the peers are consuming messages too slowly, or no peer is present), - then the function will return with `NNG_EAGAIN`. - If this flag is not specified, then the function will block if such a - condition exists. - -> [!NOTE] -> Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may -> be queues between the sender and the receiver. -> Furthermore, there is no guarantee that the message has actually been delivered. -> Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. -- `NNG_ECLOSED`: The context or socket is not open. -- `NNG_EINVAL`: An invalid set of _flags_ was specified. -- `NNG_EMSGSIZE`: The value of _size_ is too large. -- `NNG_ENOMEM`: Insufficient memory is available. -- `NNG_ENOTSUP`: The protocol does not support sending. -- `NNG_ESTATE`: The context cannot send data in this state. -- `NNG_ETIMEDOUT`: The operation timed out. - -## SEE ALSO - -[nng_ctx_send()](nng_ctx_send.md), -[Messages](../msg/index.md) diff --git a/docs/reference/src/api/context/nng_ctx_set.md b/docs/reference/src/api/context/nng_ctx_set.md deleted file mode 100644 index b3237717..00000000 --- a/docs/reference/src/api/context/nng_ctx_set.md +++ /dev/null @@ -1,94 +0,0 @@ -# nng_ctx_set - -## NAME - -nng_ctx_set --- set context option - -## SYNOPSIS - -```c -#include - -int nng_ctx_set(nng_ctx ctx, const char *opt, const void *val, size_t valsz); - -int nng_ctx_set_bool(nng_ctx ctx, const char *opt, int bval); - -int nng_ctx_set_int(nng_ctx ctx, const char *opt, int ival); - -int nng_ctx_set_ms(nng_ctx ctx, const char *opt, nng_duration dur); - -int nng_ctx_set_size(nng_ctx ctx, const char *opt, size_t z); - -int nng_ctx_set_string(nng_ctx ctx, const char *opt, const char *str); - -int nng_ctx_set_uint64(nng_ctx ctx, const char *opt, uint64_t u64); -``` - -## DESCRIPTION - -{{hi:options, context}} -The `nng_ctx_set()` functions are used to configure options for -the context _ctx_. -The actual options that may be configured in this way vary, and are -specified by _opt_. - -> [!NOTE] -> Context options are protocol specific. -> The details will be documented with the protocol. - -### Forms - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -- `nng_ctx_set()`:\ - This function is untyped, and can be used to configure any arbitrary data. - The _val_ pointer addresses the data to copy, and _valsz_ is the - size of the objected located at _val_. - -- `nng_ctx_set_bool()`:\ - This function is for options which take a Boolean (`bool`). - The _bval_ is passed to the option. - -- `nng_ctx_set_int()`:\ - This function is for options which take an integer (`int`). - The _ival_ is passed to the option. - -- `nng_ctx_set_ms()`:\ - This function is used to configure time durations (such as timeouts) using - type [`nng_duration`](nng_duration.md). - The duration _dur_ is an integer number of milliseconds. - -- `nng_ctx_set_size()`:\ - This function is used to configure a size, _z_, typically for buffer sizes, - message maximum sizes, and similar options. - -- `nng_ctx_set_string()`:\ - This function is used to pass configure a string, _str_. - Strings passed this way must be legal UTF-8 or ASCII strings, terminated - with a `NUL` (`\0`) byte. - (Other constraints may apply as well, see the documentation for each option - for details.) - -- `nng_ctx_set_uint64()`:\ - This function is used to configure a 64-bit unsigned value, _u64_. - This is typically used for options related to identifiers, network numbers, - and similar. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ECLOSED`: Parameter _s_ does not refer to an open socket. -- `NNG_EINVAL`: The value being passed is invalid. -- `NNG_ENOTSUP`: The option _opt_ is not supported. -- `NNG_EREADONLY`: The option _opt_ is read-only. -- `NNG_ESTATE`: The socket is in an inappropriate state for setting this option. - -## SEE ALSO - -[nng_ctx_get](nng_ctx_get), -[nng_socket_set](../socket/nng_socket_get), -[nng_options](nng_options) diff --git a/docs/reference/src/api/context/nng_ctx_setopt.md b/docs/reference/src/api/context/nng_ctx_setopt.md deleted file mode 100644 index f62b6857..00000000 --- a/docs/reference/src/api/context/nng_ctx_setopt.md +++ /dev/null @@ -1,98 +0,0 @@ -# nng_ctx_setopt - -## NAME - -nng_ctx_setopt --- set context option (deprecated) - -## SYNOPSIS - -```c -#include - -int nng_ctx_setopt(nng_ctx ctx, const char *opt, const void *val, size_t valsz); - -int nng_ctx_setopt_bool(nng_ctx ctx, const char *opt, int bval); - -int nng_ctx_setopt_int(nng_ctx ctx, const char *opt, int ival); - -int nng_ctx_setopt_ms(nng_ctx ctx, const char *opt, nng_duration dur); - -int nng_ctx_setopt_size(nng_ctx ctx, const char *opt, size_t z); - -int nng_ctx_setopt_string(nng_ctx ctx, const char *opt, const char *str); - -int nng_ctx_setopt_uint64(nng_ctx ctx, const char *opt, uint64_t u64); -``` - -## DESCRIPTION - -> [!IMPORTANT] -> These functions are deprecated. -> Please see [nng_ctx_set()](nng_ctx_set.md). -> They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. -> They may also be removed entirely in a future version of _NNG_. - -The `nng_ctx_setopt()` functions are used to configure options for -the context _ctx_. -The actual options that may be configured in this way vary, and are -specified by _opt_. - -> [!NOTE] -> Context options are protocol specific. -> The details will be documented with the protocol. - -### Forms - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -- `nng_ctx_setopt()`:\ - This function is untyped, and can be used to configure any arbitrary data. - The _val_ pointer addresses the data to copy, and _valsz_ is the - size of the objected located at _val_. - -- `nng_ctx_setopt_bool()`:\ - This function is for options which take a Boolean (`bool`). - The _bval_ is passed to the option. - -- `nng_ctx_setopt_int()`:\ - This function is for options which take an integer (`int`). - The _ival_ is passed to the option. - -- `nng_ctx_setopt_ms()`:\ - This function is used to configure time durations (such as timeouts) using - type [`nng_duration`](nng_duration.md). - The duration _dur_ is an integer number of milliseconds. - -- `nng_ctx_setopt_size()`:\ - This function is used to configure a size, _z_, typically for buffer sizes, - message maximum sizes, and similar options. - -- `nng_ctx_setopt_string()`:\ - This function is used to pass configure a string, _str_. - Strings passed this way must be legal UTF-8 or ASCII strings, terminated - with a `NUL` (`\0`) byte. - (Other constraints may apply as well, see the documentation for each option - for details.) - -- `nng_ctx_setopt_uint64()`:\ - This function is used to configure a 64-bit unsigned value, _u64_. - This is typically used for options related to identifiers, network numbers, - and similar. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ECLOSED`: Parameter _s_ does not refer to an open socket. -- `NNG_EINVAL`: The value being passed is invalid. -- `NNG_ENOTSUP`: The option _opt_ is not supported. -- `NNG_EREADONLY`: The option _opt_ is read-only. -- `NNG_ESTATE`: The socket is in an inappropriate state for setting this option. - -## SEE ALSO - -[nng_ctx_set](nng_ctx_set.md), -[nng_options](nng_options.md) diff --git a/docs/reference/src/ctx/index.md b/docs/reference/src/ctx/index.md new file mode 100644 index 00000000..074989d8 --- /dev/null +++ b/docs/reference/src/ctx/index.md @@ -0,0 +1,162 @@ +# nng_ctx + +## NAME + +nng_ctx --- protocol context + +## SYNOPSIS + +```c +#include + +typedef struct nng_ctx_s nng_ctx +``` + +## DESCRIPTION + +An `nng_ctx`{{hi:context}} is a handle to an underlying context object, +which keeps the protocol state for some stateful protocols. +The purpose of a separate context object is to permit applications to +share a single [socket](../socket/index.md), with its various underlying +[dialers][nng_dialer], +[listeners][nng_listener], +[pipes][nng_pipe], +while still benefiting from separate state tracking. + +For example, a [_REQ_](../protocols/req.md) context will contain the request ID +of any sent request, a timer to retry the request on failure, and so forth. +A separate context on the same socket can have similar data, but corresponding +to a completely different request. + +> [!NOTE] +> The `nng_ctx` structure is always passed by value (both +> for input parameters and return values), and should be treated opaquely. +> Passing structures this way gives the compiler a chance to perform +> accurate type checks in functions passing values of this type. + +All contexts share the same socket, and so some options, as well as the +underlying transport details, will be common to all contexts on that socket. + +Protocols that make use of contexts will also have a default context +that is used when the socket global operations are used. +Operations using the global context will generally not interfere with +any other contexts, except that certain socket options may affect socket +global behavior. + +{{hi:concurrent}}{{hi:raw mode}} +Historically, applications wanting to use a stateful protocol concurrently +would have to resort to [raw mode](../overview/raw.md) sockets, which bypasses +much of the various protocol handling, leaving it to up to the application +to do so. +Contexts make it possible to still benefit from advanced protocol handling, +including timeouts, retries, and matching requests to responses, while doing so +concurrently. + +> [!TIP] +> Contexts are an excellent mechanism to use when building concurrent +> applications, and should be used in lieu of +> [raw mode](../overview/raw.md) sockets when possible. + +## Caveats + +Not every protocol supports separate contexts. +See the protocol-specific documentation for further details about whether +contexts are supported, and details about what options are supported for +contexts. + +Use of file descriptor polling (with descriptors obtained using the +[`NNG_OPT_RECVFD`](nng_options.md#NNG_OPT_RECVFD) or +[`NNG_OPT_SENDFD`](nng_options.md#NNG_OPT_SENDFD) options) while contexts +are in use on the same socket is not supported, and may lead to unpredictable +behavior. These asynchronous methods should not be mixed on the same socket. + +[Raw mode](../overview/raw.md) sockets do not support contexts, since +there is generally no state tracked for them, and thus contexts make no sense. + +## Initialization + +A context may be initialized using the macro `NNG_CTX_INITIALIZER` +before it is opened, to prevent confusion with valid open contexts. + +## Example + +The following program fragment demonstrates the use of contexts to implement +a concurrent [_REP_](../protocols/rep.md) service that simply echos messages back +to the sender. + +```c +struct echo_context { + nng_ctx ctx; + nng_aio *aio; + enum { INIT, RECV, SEND } state; +}; + +void +echo(void *arg) +{ + struct echo_context *ec = arg; + + switch (ec->state) { + case INIT: + ec->state = RECV; + nng_ctx_recv(ec->ctx, ec->aio); + return; + case RECV: + if (nng_aio_result(ec->aio) != 0) { + // ... handle error + } + // We reuse the message on the ec->aio + ec->state = SEND; + nng_ctx_send(ec->ctx, ec->aio); + return; + case SEND: + if (nng_aio_result(ec->aio) != 0) { + // ... handle error + } + ec->state = RECV; + nng_ctx_recv(ec->ctx, ec->aio); + return; + } +} +``` + +Given the above fragment, the following example shows setting up the +service. It assumes that the [socket][nng_socket] has already been +created and any transports set up as well with functions such as +[`nng_dial()`][nng_dial] or [`nng_listen()`](nng_listen.md). + +```c +#define CONCURRENCY 1024 + +echo_context ecs[CONCURRENCY]; + +void +start_echo_service(nng_socket rep_socket) +{ + for (int i = 0; i < CONCURRENCY; i++) { + // error checks elided for clarity + nng_ctx_open(ec[i].ctx, rep_socket) + nng_aio_alloc(ec[i].aio, echo, &e[i]); + ec[i].state = INIT; + echo(&ec[i]); // start it running + } +} +``` + +## SEE ALSO + +[nng_ctx_close][nng_ctx_close], +[nng_ctx_open][nng_ctx_open], +[nng_ctx_get][nng_ctx_get], +[nng_ctx_id][nng_ctx_id] +[nng_ctx_recv][nng_ctx_recv], +[nng_ctx_recvmsg][nng_ctx_recvmsg], +[nng_ctx_send][nng_ctx_send], +[nng_ctx_sendmsg][nng_ctx_sendmsg], +[nng_ctx_set][nng_ctx_set], +[nng_dialer][nng_dialer], +[nng_listener][nng_listener], +[nng_socket](../socket/index.md), +[nng_options][nng_options] + +{{#include ../refs.md}} diff --git a/docs/reference/src/ctx/nng_ctx_close.md b/docs/reference/src/ctx/nng_ctx_close.md new file mode 100644 index 00000000..857808f1 --- /dev/null +++ b/docs/reference/src/ctx/nng_ctx_close.md @@ -0,0 +1,43 @@ +# nng_ctx_close + +## NAME + +nng_ctx_close --- close context + +## SYNOPSIS + +```c +#include + +int nng_ctx_close(nng_ctx ctx); +``` + +## DESCRIPTION + +The `nng_ctx_close()` function closes the [context][context] _ctx_. +Messages that have been submitted for sending may be flushed or delivered, +depending upon the transport. + +Further attempts to use the context after this call returns will result +in `NNG_ECLOSED`. +Threads waiting for operations on the context when this +call is executed may also return with an `NNG_ECLOSED` result. + +> [!NOTE] +> Closing the socket associated with _ctx_ +> (using [`nng_close()`][nng_close]) also closes this context. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ECLOSED`: The context _ctx_ is already closed or was never opened. + +## SEE ALSO + +[nng_close][nng_close], +[nng_ctx_open][nng_ctx_open] + +{{#include ../refs.md}} diff --git a/docs/reference/src/ctx/nng_ctx_get.md b/docs/reference/src/ctx/nng_ctx_get.md new file mode 100644 index 00000000..dca3681f --- /dev/null +++ b/docs/reference/src/ctx/nng_ctx_get.md @@ -0,0 +1,114 @@ +# nng_ctx_get + +## NAME + +nng_ctx_get --- get context option + +## SYNOPSIS + +```c +#include + +int nng_ctx_get(nng_ctx ctx, const char *opt, void *val, size_t *valszp); + +int nng_ctx_get_bool(nng_ctx ctx, const char *opt, bool *bvalp); + +int nng_ctx_get_int(nng_ctx ctx, const char *opt, int *ivalp); + +int nng_ctx_get_ms(nng_ctx ctx, const char *opt, nng_duration *durp); + +int nng_ctx_get_size(nng_ctx ctx, const char *opt, size_t *zp); + +int nng_ctx_get_string(nng_ctx ctx, const char *opt, char **strp); + +int nng_ctx_get_uint64(nng_ctx ctx, const char *opt, uint64_t *u64p); +``` + +## DESCRIPTION + +{{hi:options, context}} +The `nng_ctx_get()` functions are used to retrieve option values for +the [context][context] _ctx_. +The actual options that may be retrieved in this way vary. +A number of them are documented in [nng_options][options]. + +> [!NOTE] +> Context options are protocol specific. +> The details will be documented with the protocol. + +### Forms + +In all of these forms, the option _opt_ is retrieved from the context _ctx_. +The forms vary based on the type of the option they take. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +- `nng_ctx_get()`:\ + This function is untyped and can be used to retrieve the value of any option. + The caller must store a pointer to a buffer to receive the value in _val_, + and the size of the buffer shall be stored at the location referenced by + _valszp_.\ + \ + When the function returns, the actual size of the data copied (or that + would have been copied if sufficient space were present) is stored at + the location referenced by _valszp_. + If the caller's buffer is not large enough to hold the entire object, + then the copy is truncated. + Therefore the caller should check for truncation by verifying that the + returned size in _valszp_ does not exceed the original buffer size.\ + \ + It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. + This can be used to determine the size of the buffer needed to receive + the object. + +- `nng_ctx_get_bool()`:\ + This function is for options which take a Boolean (`bool`). + The value will be stored at _ivalp_. + +- `nng_ctx_get_int()`:\ + This function is for options which take an integer (`int`). + The value will be stored at _ivalp_. + +- `nng_ctx_get_ms()`:\ + This function is used to retrieve time [durations][duration] + (such as timeouts), stored in _durp_ as a number of milliseconds. + (The special value {{i:`NNG_DURATION_INFINITE`}} means an infinite amount of time, and + the special value {{i:`NNG_DURATION_DEFAULT`}} means a context-specific default.) +- `nng_ctx_get_size()`:\ + This function is used to retrieve a size into the pointer _zp_, + typically for buffer sizes, message maximum sizes, and similar options. +- `nng_ctx_get_string()`:\ + This function is used to retrieve a string into _strp_. + This string is created from the source using [`nng_strdup()`][nng_strdup] + and consequently must be freed by the caller using + [`nng_strfree()`][nng_strfree] when it is no longer needed. + +- `nng_ctx_get_uint64()`:\ + This function is used to retrieve a 64-bit unsigned value into the value + referenced by _u64p_. + This is typically used for options related to identifiers, network + numbers, and similar. + +## RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_EBADTYPE`: Incorrect type for option. +- `NNG_ECLOSED`: Parameter _s_ does not refer to an open socket. +- `NNG_EINVAL`: Size of destination _val_ too small for object. +- `NNG_ENOMEM`: Insufficient memory exists. +- `NNG_ENOTSUP`: The option _opt_ is not supported. +- `NNG_EWRITEONLY`: The option _opt_ is write-only. + +## SEE ALSO + +[nng_ctx_set][nng_ctx_set], +[nng_strdup][nng_strdup], +[nng_strfree][nng_strfree], +[nng_duration][nng_duration], +[nng_options][options] + +{{#include ../refs.md}} diff --git a/docs/reference/src/ctx/nng_ctx_getopt.md b/docs/reference/src/ctx/nng_ctx_getopt.md new file mode 100644 index 00000000..87d75519 --- /dev/null +++ b/docs/reference/src/ctx/nng_ctx_getopt.md @@ -0,0 +1,118 @@ +# nng_ctx_getopt + +## NAME + +nng_ctx_getopt --- get context option (deprecated) + +## SYNOPSIS + +```c +#include + +int nng_ctx_getopt(nng_ctx ctx, const char *opt, void *val, size_t *valszp); + +int nng_ctx_getopt_bool(nng_ctx ctx, const char *opt, bool *bvalp); + +int nng_ctx_getopt_int(nng_ctx ctx, const char *opt, int *ivalp); + +int nng_ctx_getopt_ms(nng_ctx ctx, const char *opt, nng_duration *durp); + +int nng_ctx_getopt_size(nng_ctx ctx, const char *opt, size_t *zp); + +int nng_ctx_getopt_string(nng_ctx ctx, const char *opt, char **strp); + +int nng_ctx_getopt_uint64(nng_ctx ctx, const char *opt, uint64_t *u64p); +``` + +## DESCRIPTION + +> [!IMPORTANT] +> These functions are deprecated. Please see [nng_ctx_get][nng_ctx_get]. +> They may not be present if the library was built with {{i:`NNG_ELIDE_DEPRECATED`}}. +> They may also be removed entirely in a future version of _NNG_. + +The `nng_ctx_getopt()` functions are used to retrieve option values for +the [context][context] _ctx_. +The actual options that may be retrieved in this way vary. + +> [!NOTE] +> Context options are protocol specific. +> The details will be documented with the protocol. + +### Forms + +In all of these forms, the option _opt_ is retrieved from the context _ctx_. +The forms vary based on the type of the option they take. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +- `nng_ctx_getopt()`:\ + This function is untyped and can be used to retrieve the value of any option. + The caller must store a pointer to a buffer to receive the value in _val_, + and the size of the buffer shall be stored at the location referenced by + _valszp_.\ + \ + When the function returns, the actual size of the data copied (or that + would have been copied if sufficient space were present) is stored at + the location referenced by _valszp_. + If the caller's buffer is not large enough to hold the entire object, + then the copy is truncated. + Therefore the caller should check for truncation by verifying that the + returned size in _valszp_ does not exceed the original buffer size.\ + \ + It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. + This can be used to determine the size of the buffer needed to receive + the object. + +- `nng_ctx_getopt_bool()`:\ + This function is for options which take a Boolean (`bool`). + The value will be stored at _ivalp_. + +- `nng_ctx_getopt_int()`:\ + This function is for options which take an integer (`int`). + The value will be stored at _ivalp_. + +- `nng_ctx_getopt_ms()`:\ + This function is used to retrieve time [durations][nng_duration] + (such as timeouts), stored in _durp_ as a number of milliseconds. + (The special value `NNG_DURATION_INFINITE` means an infinite amount of time, and + the special value `NNG_DURATION_DEFAULT` means a context-specific default.) + +- `nng_ctx_getopt_size()`:\ + This function is used to retrieve a size into the pointer _zp_, + typically for buffer sizes, message maximum sizes, and similar options. + +- `nng_ctx_getopt_string()`:\ + This function is used to retrieve a string into _strp_. + This string is created from the source using [`nng_strdup()`][nng_strdup] + and consequently must be freed by the caller using + [`nng_strfree()`][nng_strfree] when it is no longer needed. + +- `nng_ctx_getopt_uint64()`:\ + This function is used to retrieve a 64-bit unsigned value into the value + referenced by _u64p_. + This is typically used for options related to identifiers, network + numbers, and similar. + +## RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_EBADTYPE`: Incorrect type for option. +- `NNG_ECLOSED`: Parameter _s_ does not refer to an open socket. +- `NNG_EINVAL`: Size of destination _val_ too small for object. +- `NNG_ENOMEM`: Insufficient memory exists. +- `NNG_ENOTSUP`: The option _opt_ is not supported. +- `NNG_EWRITEONLY`: The option _opt_ is write-only. + +## SEE ALSO + +[nng_strdup][nng_strdup], +[nng_strfree][nng_strfree], +[nng_duration][duration], +[nng_options][options] + +{{#include ../refs.md}} diff --git a/docs/reference/src/ctx/nng_ctx_id.md b/docs/reference/src/ctx/nng_ctx_id.md new file mode 100644 index 00000000..6592da7d --- /dev/null +++ b/docs/reference/src/ctx/nng_ctx_id.md @@ -0,0 +1,33 @@ +# nng_ctx_id + +## NAME + +nng_ctx_id --- return numeric context identifier + +## SYNOPSIS + +```c +#include + +int nng_ctx_id(nng_ctx c); +``` + +## DESCRIPTION + +The `nng_ctx_id()` function returns a positive identifier for the [context][context] _c_, +if it is valid. +Otherwise it returns `-1`. + +> [!NOTE] +> A context is considered valid if it was ever opened with +> [`nng_ctx_open()`][nng_ctx_open] function. +> Contexts that are allocated on the stack or statically should be +> initialized with the macro {{i:`NNG_CTX_INITIALIZER`}} to ensure that +> they cannot be confused with a valid context before they are opened. + +## RETURN VALUES + +This function returns the positive value for the context identifier, or +`-1` if the context is invalid. + +{{#include ../refs.md}} diff --git a/docs/reference/src/ctx/nng_ctx_open.md b/docs/reference/src/ctx/nng_ctx_open.md new file mode 100644 index 00000000..024081d5 --- /dev/null +++ b/docs/reference/src/ctx/nng_ctx_open.md @@ -0,0 +1,59 @@ +# nng_ctx_open + +## NAME + +nng_ctx_open --- create context + +## SYNOPSIS + +```c +#include + +int nng_ctx_open(nng_ctx *ctxp, nng_socket s); +``` + +## DESCRIPTION + +The `nng_ctx_open()` function creates a separate {{hi:context}}[context][context] to be used with +the [socket][socket] _s_, +and returns it at the location pointed by _ctxp_. + +> [!NOTE] +> Not every protocol supports creation of separate contexts. + +Contexts allow the independent and concurrent use of stateful operations +using the same socket. +For example, two different contexts created on a +[_REP_][rep] +socket can each receive requests, and send replies to them, without any +regard to or interference with each other. + +> [!TIP] +> Using contexts is an excellent way to write simpler concurrent +> applications, while retaining the benefits of the protocol-specific +> advanced processing, avoiding the need to bypass that with +> {{hi:raw mode}}[raw mode][raw] sockets. + +> [!NOTE] +> Use of contexts with [raw mode][raw] sockets is +> nonsensical, and not supported. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient memory is available. +- `NNG_ENOTSUP`: The protocol does not support separate contexts, or the socket was opened in raw mode. + +## SEE ALSO + +[nng_ctx_close][nng_ctx_close], +[nng_ctx_get][nng_ctx_get], +[nng_ctx_recv][nng_ctx_recv], +[nng_ctx_send][nng_ctx_send], +[nng_ctx_set][nng_ctx_set], +[Sockets][socket] + +{{#include ../refs.md}} diff --git a/docs/reference/src/ctx/nng_ctx_recv.md b/docs/reference/src/ctx/nng_ctx_recv.md new file mode 100644 index 00000000..94ed21f9 --- /dev/null +++ b/docs/reference/src/ctx/nng_ctx_recv.md @@ -0,0 +1,58 @@ +# nng_ctx_recv + +## NAME + +nng_ctx_recv --- receive message using context asynchronously + +## SYNOPSIS + +```c +#include + +void nng_ctx_recv(nng_ctx ctx, nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_ctx_recv()` receives a [message][msg] using the +[context][context] _ctx_ asynchronously. + +When a message is successfully received by the context, it is +stored in the [_aio_][aio] by an internal call equivalent to +[`nng_aio_set_msg()`][nng_aio_set_msg], then the completion +callback on the _aio_ is executed. +In this case, [`nng_aio_result()`][nng_aio_result] will +return zero. +The callback function is responsible for retrieving the message +and disposing of it appropriately. + +> [!IMPORTANT] +> Failing to accept and dispose of messages in this +> case can lead to memory leaks. + +If for some reason the asynchronous receive cannot be completed +successfully (including by being canceled or timing out), then +the callback will still be executed, +but [`nng_aio_result()`][nng_aio_result] will be non-zero. + +> [!TIP] +> The semantics of what receiving a message means varies from protocol to +> protocol, so examination of the protocol documentation is encouraged. + +## ERRORS + +The following errors may be set on the _aio_, if the operation fails. + +- `NNG_ECANCELED`: The operation was aborted. +- `NNG_ECLOSED`: The context _ctx_ is not open. +- `NNG_ENOMEM`: Insufficient memory is available. +- `NNG_ENOTSUP`: The protocol for context _ctx_ does not support receiving. +- `NNG_ESTATE`: The context _ctx_ cannot receive data in this state. +- `NNG_ETIMEDOUT`: The receive timeout expired. + +## SEE ALSO + +[Asynchronous I/O][aio], +[Messages][msg] + +{{#include ../refs.md}} diff --git a/docs/reference/src/ctx/nng_ctx_recvmsg.md b/docs/reference/src/ctx/nng_ctx_recvmsg.md new file mode 100644 index 00000000..028ad9e6 --- /dev/null +++ b/docs/reference/src/ctx/nng_ctx_recvmsg.md @@ -0,0 +1,53 @@ +# nng_ctx_recvmsg + +## NAME + +nng_ctx_recvmsg --- receive message using socket + +## SYNOPSIS + +```c +#include + +int nng_ctx_recvmsg(nng_ctx ctx, nng_msg **msgp, int flags); +``` + +## DESCRIPTION + +The `nng_ctx_recvmsg()` receives a message on [context][context] _ctx_, storing the +received [message][msg] at the location pointed to by _msgp_. + +The _flags_ may contain the following value: + +- {{i:`NNG_FLAG_NONBLOCK`}}:\ + The function returns immediately, even if no message is available. + Without this flag, the function will wait until a message is receivable + on the context _ctx_, or any configured timer expires. + +> [!TIP] +> The semantics of what receiving a message means vary from protocol to +> protocol, so examination of the protocol documentation is encouraged. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. +- `NNG_ECLOSED`: The context or socket is not open. +- `NNG_EINVAL`: An invalid set of _flags_ was specified. +- `NNG_ENOMEM`: Insufficient memory is available. +- `NNG_ENOTSUP`: The protocol does not support receiving. +- `NNG_ESTATE`: The context cannot receive data in this state. +- `NNG_ETIMEDOUT`: The operation timed out. + +## SEE ALSO + +[nng_msg_free][nng_msg_free], +[nng_ctx_open][nng_ctx_open], +[nng_ctx_recv][nng_ctx_recv], +[nng_ctx_sendmsg][nng_ctx_sendmsg], +[Messages][msg] + +{{#include ../refs.md}} diff --git a/docs/reference/src/ctx/nng_ctx_send.md b/docs/reference/src/ctx/nng_ctx_send.md new file mode 100644 index 00000000..dfe1796b --- /dev/null +++ b/docs/reference/src/ctx/nng_ctx_send.md @@ -0,0 +1,70 @@ +# nng_ctx_send + +## NAME + +nng_ctx_send --- send message using context asynchronously + +## SYNOPSIS + +```c +#include + +void nng_ctx_send(nng_ctx ctx, nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_ctx_send()` sends a [message](../msg/index.md) using the +[context][nng_ctx] _ctx_ asynchronously. + +The message to send must have previously been set on the _aio_ +using the [`nng_aio_set_msg()`](../aio/nng_aio_set_msg.md) function. +The function assumes ownership of the message. + +If the message was successfully queued for delivery to the socket, +then the _aio_ will be completed, and [`nng_aio_result()`](../aio/nng_aio_result.md) +will return zero. +In this case the socket will dispose of the message when it is finished with it. + +> [!NOTE] +> The operation will be completed, and the callback associated +> with the _aio_ executed, as soon as the socket accepts the message +> for sending. +> This does _not_ indicate that the message was actually delivered, as it +> may still be buffered in the sending socket, buffered in the receiving +> socket, or in flight over physical media. + +If the operation fails for any reason (including cancellation or timeout), +then the _aio_ callback will be executed and +[`nng_aio_result()`](../aio/nng_aio_result.md) will return a non-zero error status. +In this case, the callback has a responsibility to retrieve the message from +the _aio_ with [`nng_aio_get_msg()`](../aio/nng_aio_get_msg.md) and dispose of +it appropriately. +(This may include retrying the send operation on the same or a different +socket, or deallocating the message with [`nng_msg_free()`](../msg/nng_msg_free.md). + +> [!TIP] +> The semantics of what sending a message means varies from protocol to +> protocol, so examination of the protocol documentation is encouraged. + +## ERRORS + +- `NNG_ECANCELED`: The operation was aborted. +- `NNG_ECLOSED`: The context _ctx_ is not open. +- `NNG_EMSGSIZE`: The message is too large. +- `NNG_ENOMEM`: Insufficient memory is available. +- `NNG_ENOTSUP`: The protocol for context _ctx_ does not support sending. +- `NNG_ESTATE`: The context _ctx_ cannot send data in this state. +- `NNG_ETIMEDOUT`: The send timeout expired. + +## SEE ALSO + +[nng_aio_get_msg](../aio/nng_aio_get_msg.md), +[nng_aio_set_msg](../aio/nng_aio_set_msg.md), +[nng_ctx_sendmsg][nng_ctx_sendmsg], +[nng_msg_alloc](../msg/nng_msg_alloc.md), +[nng_msg_free](../msg/nng_msg_free.md), +[Asynchronous I/O][aio], +[Messages][msg] + +{{#include ../refs.md}} diff --git a/docs/reference/src/ctx/nng_ctx_sendmsg.md b/docs/reference/src/ctx/nng_ctx_sendmsg.md new file mode 100644 index 00000000..e3ecb974 --- /dev/null +++ b/docs/reference/src/ctx/nng_ctx_sendmsg.md @@ -0,0 +1,69 @@ +# nng_ctx_sendmsg() + +## NAME + +nng_ctx_sendmsg --- send message using context + +## SYNOPSIS + +```c +#include + +int nng_ctx_sendmsg(nng_ctx c, nng_msg *msg, int flags); +``` + +## DESCRIPTION + +The `nng_ctx_sendmsg()` sends [message][msg] _msg_ using the [context][context] _ctx_. + +If the function returns zero, indicating it has accepted the message for +delivery, then the _msg_ is owned by the socket _s_, and the caller +must not make any further use of it. +The socket will free the message when it is finished. + +If the function returns non-zero, then it is the caller's responsibility +to dispose of the _msg_, which may include freeing it, sending it to +another socket, or simply trying again later. + +> [!TIP] +> The semantics of what sending a message means vary from protocol to +> protocol, so examination of the protocol documentation is encouraged. + +The _flags_ may contain the following value: + +- {{i:`NNG_FLAG_NONBLOCK`}}:\ + The function returns immediately, regardless of whether + the context is able to accept the data or not. + If the context is unable to accept the data (such as if backpressure exists + because the peers are consuming messages too slowly, or no peer is present), + then the function will return with `NNG_EAGAIN`. + If this flag is not specified, then the function will block if such a + condition exists.[^1] + +[^1]: + Regardless of the presence or absence of {{i:`NNG_FLAG_NONBLOCK`}}, there may + be queues between the sender and the receiver. + Furthermore, there is no guarantee that the message has actually been delivered. + Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. +- `NNG_ECLOSED`: The context or socket is not open. +- `NNG_EINVAL`: An invalid set of _flags_ was specified. +- `NNG_EMSGSIZE`: The value of _size_ is too large. +- `NNG_ENOMEM`: Insufficient memory is available. +- `NNG_ENOTSUP`: The protocol does not support sending. +- `NNG_ESTATE`: The context cannot send data in this state. +- `NNG_ETIMEDOUT`: The operation timed out. + +## SEE ALSO + +[nng_ctx_send][nng_ctx_send], +[Messages][msg] + +{{#include ../refs.md}} diff --git a/docs/reference/src/ctx/nng_ctx_set.md b/docs/reference/src/ctx/nng_ctx_set.md new file mode 100644 index 00000000..b94cff50 --- /dev/null +++ b/docs/reference/src/ctx/nng_ctx_set.md @@ -0,0 +1,96 @@ +# nng_ctx_set + +## NAME + +nng_ctx_set --- set context option + +## SYNOPSIS + +```c +#include + +int nng_ctx_set(nng_ctx ctx, const char *opt, const void *val, size_t valsz); + +int nng_ctx_set_bool(nng_ctx ctx, const char *opt, int bval); + +int nng_ctx_set_int(nng_ctx ctx, const char *opt, int ival); + +int nng_ctx_set_ms(nng_ctx ctx, const char *opt, nng_duration dur); + +int nng_ctx_set_size(nng_ctx ctx, const char *opt, size_t z); + +int nng_ctx_set_string(nng_ctx ctx, const char *opt, const char *str); + +int nng_ctx_set_uint64(nng_ctx ctx, const char *opt, uint64_t u64); +``` + +## DESCRIPTION + +{{hi:options, context}} +The `nng_ctx_set()` functions are used to configure options for +the context _ctx_. +The actual options that may be configured in this way vary, and are +specified by _opt_. + +> [!NOTE] +> Context options are protocol specific. +> The details will be documented with the protocol. + +### Forms + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +- `nng_ctx_set()`:\ + This function is untyped, and can be used to configure any arbitrary data. + The _val_ pointer addresses the data to copy, and _valsz_ is the + size of the objected located at _val_. + +- `nng_ctx_set_bool()`:\ + This function is for options which take a Boolean (`bool`). + The _bval_ is passed to the option. + +- `nng_ctx_set_int()`:\ + This function is for options which take an integer (`int`). + The _ival_ is passed to the option. + +- `nng_ctx_set_ms()`:\ + This function is used to configure time durations (such as timeouts) using + type [`nng_duration`][nng_duration]. + The duration _dur_ is an integer number of milliseconds. + +- `nng_ctx_set_size()`:\ + This function is used to configure a size, _z_, typically for buffer sizes, + message maximum sizes, and similar options. + +- `nng_ctx_set_string()`:\ + This function is used to pass configure a string, _str_. + Strings passed this way must be legal UTF-8 or ASCII strings, terminated + with a `NUL` (`\0`) byte. + (Other constraints may apply as well, see the documentation for each option + for details.) + +- `nng_ctx_set_uint64()`:\ + This function is used to configure a 64-bit unsigned value, _u64_. + This is typically used for options related to identifiers, network numbers, + and similar. + +## RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ECLOSED`: Parameter _s_ does not refer to an open socket. +- `NNG_EINVAL`: The value being passed is invalid. +- `NNG_ENOTSUP`: The option _opt_ is not supported. +- `NNG_EREADONLY`: The option _opt_ is read-only. +- `NNG_ESTATE`: The socket is in an inappropriate state for setting this option. + +## SEE ALSO + +[nng_ctx_get][nng_ctx_get], +[nng_socket_set][nng_socket_get], +[Options][options] + +{{#include ../refs.md}} diff --git a/docs/reference/src/ctx/nng_ctx_setopt.md b/docs/reference/src/ctx/nng_ctx_setopt.md new file mode 100644 index 00000000..f738bbe5 --- /dev/null +++ b/docs/reference/src/ctx/nng_ctx_setopt.md @@ -0,0 +1,100 @@ +# nng_ctx_setopt + +## NAME + +nng_ctx_setopt --- set context option (deprecated) + +## SYNOPSIS + +```c +#include + +int nng_ctx_setopt(nng_ctx ctx, const char *opt, const void *val, size_t valsz); + +int nng_ctx_setopt_bool(nng_ctx ctx, const char *opt, int bval); + +int nng_ctx_setopt_int(nng_ctx ctx, const char *opt, int ival); + +int nng_ctx_setopt_ms(nng_ctx ctx, const char *opt, nng_duration dur); + +int nng_ctx_setopt_size(nng_ctx ctx, const char *opt, size_t z); + +int nng_ctx_setopt_string(nng_ctx ctx, const char *opt, const char *str); + +int nng_ctx_setopt_uint64(nng_ctx ctx, const char *opt, uint64_t u64); +``` + +## DESCRIPTION + +> [!IMPORTANT] +> These functions are deprecated. +> Please see [nng_ctx_set()][nng_ctx_set]. +> They may not be present if the library was built with {{i:`NNG_ELIDE_DEPRECATED`}}. +> They may also be removed entirely in a future version of _NNG_. + +The `nng_ctx_setopt()` functions are used to configure options for +the context _ctx_. +The actual options that may be configured in this way vary, and are +specified by _opt_. + +> [!NOTE] +> Context options are protocol specific. +> The details will be documented with the protocol. + +### Forms + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +- `nng_ctx_setopt()`:\ + This function is untyped, and can be used to configure any arbitrary data. + The _val_ pointer addresses the data to copy, and _valsz_ is the + size of the objected located at _val_. + +- `nng_ctx_setopt_bool()`:\ + This function is for options which take a Boolean (`bool`). + The _bval_ is passed to the option. + +- `nng_ctx_setopt_int()`:\ + This function is for options which take an integer (`int`). + The _ival_ is passed to the option. + +- `nng_ctx_setopt_ms()`:\ + This function is used to configure time durations (such as timeouts) using + type [`nng_duration`][nng_duration]. + The duration _dur_ is an integer number of milliseconds. + +- `nng_ctx_setopt_size()`:\ + This function is used to configure a size, _z_, typically for buffer sizes, + message maximum sizes, and similar options. + +- `nng_ctx_setopt_string()`:\ + This function is used to pass configure a string, _str_. + Strings passed this way must be legal UTF-8 or ASCII strings, terminated + with a `NUL` (`\0`) byte. + (Other constraints may apply as well, see the documentation for each option + for details.) + +- `nng_ctx_setopt_uint64()`:\ + This function is used to configure a 64-bit unsigned value, _u64_. + This is typically used for options related to identifiers, network numbers, + and similar. + +## RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ECLOSED`: Parameter _s_ does not refer to an open socket. +- `NNG_EINVAL`: The value being passed is invalid. +- `NNG_ENOTSUP`: The option _opt_ is not supported. +- `NNG_EREADONLY`: The option _opt_ is read-only. +- `NNG_ESTATE`: The socket is in an inappropriate state for setting this option. + +## SEE ALSO + +[nng_ctx_set][nng_ctx_set], +[Options][options] + +{{#include ../refs.md}} diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md index e51ffe4e..47071a0a 100644 --- a/docs/reference/src/refs.md +++ b/docs/reference/src/refs.md @@ -1,10 +1,12 @@ -[context]: ../overview/context.md +[aio]: ../aio/index.md +[context]: ../ctx/index.md [device]: ../overview/device.md [duration]: ../overview/duration.md [msg]: ../msg/index.md [pipe]: ../overview/pipe.md +[socket]: ../sock/index.md [sockadddr]: ../overview/sockaddr.md [sockaddr_in]: ../overview/sockaddr_in.md [sockaddr_in6]: ../overview/sockaddr_in6.md @@ -64,6 +66,20 @@ [nng_msg_set_pipe]: ../msg/nng_msg_set_pipe.md [nng_msg_trim]: ../msg/nng_msg_trim.md + + +[nng_ctx_close]: ../ctx/nng_ctx_close.md +[nng_ctx_get]: ../ctx/nng_ctx_get.md +[nng_ctx_getopt]: ../ctx/nng_ctx_getopt.md +[nng_ctx_id]: ../ctx/nng_ctx_id.md +[nng_ctx_open]: ../ctx/nng_ctx_open.md +[nng_ctx_recv]: ../ctx/nng_ctx_recv.md +[nng_ctx_recvmsg]: ../nng_ctx_recvmsg.md +[nng_ctx_send]: ../nng_ctx_send.md +[nng_ctx_sendmsg]: ../ctx/nng_ctx_sendmsg.dm +[nng_ctx_set]: ../ctx/nng_ctx_set.md +[nng_ctx_setopt]: ../ctx/nng_ctx_setopt.md + [nng_cv_alloc]: ../thr/nng_cv_alloc.md -- cgit v1.2.3-70-g09d2