#include <nng/nng.h>
typedef struct nng_ctx_s nng_ctx| This documentation is for version v1.7.3 of NNG, but the latest released version is v1.8.0. see the documentation for v1.8.0 for the most up-to-date information. |
nng_ctx(5)
NAME
nng_ctx - protocol context
SYNOPSIS
DESCRIPTION
An nng_ctx 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, with its various underlying
dialers,
listeners,
and pipes,
while still benefiting from separate state tracking.
For example, a req 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.
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.
| 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. |
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.
Historically, applications wanting to use a stateful protocol concurrently would have to resort to raw mode 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.
| Raw mode sockets do not support contexts, since there is generally no state tracked for them, and thus contexts make no sense. |
| Contexts are an excellent mechanism to use when building concurrent applications, and should be used in lieu of raw mode sockets when possible. |
Use of file descriptor polling (with descriptors
obtained using the
NNG_OPT_RECVFD or
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.
|
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 service that simply echos messages back to the sender.
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 has already been
created and any transports set up as well with functions such as
nng_dial()
or nng_listen().
#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
}
}