NAME

       nng_ctx - protocol context

SYNOPSIS

           #include <nng/nng.h>

           typedef struct nng_ctx_s nng_ctx

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.

           Important

           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.

           Note

           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.

           Note

           Raw mode sockets do not support contexts, since there is generally no state tracked for them, and
           thus contexts make no sense.

           Tip

           Contexts are an excellent mechanism to use when building concurrent applications, and should be used
           in lieu of raw mode sockets when possible.

           Important

           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

           static struct 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(&ecs[i].ctx, rep_socket);
                   nng_aio_alloc(&ecs[i].aio, echo, ecs+i);
                   ecs[i].state = INIT;
                   echo(ecs+i); // start it running
               }
           }

SEE ALSO

       libnng(3), nng_ctx_close(3), nng_ctx_open(3), nng_ctx_get(3), nng_ctx_id(3), nng_ctx_recv(3),
       nng_ctx_recvmsg(3), nng_ctx_send(3), nng_ctx_sendmsg(3), nng_ctx_set(3), nng_dialer(5), nng_listener(5),
       nng_socket(5), nng_options(5), nng(7)

                                                   2025-04-20                                         NNG_CTX(5)