diff options
Diffstat (limited to 'docs/reference/src/api/context')
| -rw-r--r-- | docs/reference/src/api/context/index.md | 160 | ||||
| -rw-r--r-- | docs/reference/src/api/context/nng_ctx_close.md | 41 | ||||
| -rw-r--r-- | docs/reference/src/api/context/nng_ctx_get.md | 112 | ||||
| -rw-r--r-- | docs/reference/src/api/context/nng_ctx_getopt.md | 116 | ||||
| -rw-r--r-- | docs/reference/src/api/context/nng_ctx_id.md | 31 | ||||
| -rw-r--r-- | docs/reference/src/api/context/nng_ctx_open.md | 56 | ||||
| -rw-r--r-- | docs/reference/src/api/context/nng_ctx_recv.md | 56 | ||||
| -rw-r--r-- | docs/reference/src/api/context/nng_ctx_recvmsg.md | 50 | ||||
| -rw-r--r-- | docs/reference/src/api/context/nng_ctx_send.md | 68 | ||||
| -rw-r--r-- | docs/reference/src/api/context/nng_ctx_sendmsg.md | 67 | ||||
| -rw-r--r-- | docs/reference/src/api/context/nng_ctx_set.md | 94 | ||||
| -rw-r--r-- | docs/reference/src/api/context/nng_ctx_setopt.md | 98 |
12 files changed, 0 insertions, 949 deletions
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 <nng/nng.h> - -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 <nng/nng.h> - -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 <nng/nng.h> - -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 <nng/nng.h> - -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 <nng/nng.h> - -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 <nng/nng.h> - -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 <nng/nng.h> - -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 <nng/nng.h> - -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 <nng/nng.h> - -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 <nng/nng.h> - -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 <nng/nng.h> - -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 <nng/nng.h> - -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) |