= nng_ctx(5)
//
// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
//
// This document is supplied under the terms of the MIT License, a
// copy of which should be located in the distribution where this
// file was obtained (LICENSE.txt).  A copy of the license may also be
// found online at https://opensource.org/licenses/MIT.
//

== NAME

nng_ctx - protocol context

== SYNOPSIS

[source, c]
----
#include <nng/nng.h>

typedef struct nng_ctx_s nng_ctx
----

== DESCRIPTION

An `nng_ctx`(((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, with its various underlying
xref:nng_dialer.5.adoc[dialers],
xref:nng_listener.5.adoc[listeners],
and xref:nng_pipe.5.adoc[pipes],
while still benefiting from separate state tracking.

For example, a xref:nng_req.7.adoc[_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.

(((concurrent)))(((raw mode)))
Historically, applications wanting to use a stateful protocol concurrently
would have to resort to xref:nng.7.adoc#raw_mode[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: xref:nng.7.adoc#raw_mode[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
xref:nng.7.adoc#raw_mode[raw mode] sockets when possible.

IMPORTANT: Use of file descriptor polling (with descriptors
obtained using the
xref:nng_options.5.adoc#NNG_OPT_RECVFD[`NNG_OPT_RECVFD`] or
xref:nng_options.5.adoc#NNG_OPT_SENDFD[`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.

[[NNG_CTX_INITIALIZER]]
=== 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 xref:nng_rep.7.adoc[_rep_] service that simply echos messages back
to the sender.

[source, 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 xref:nng_socket.5.adoc[socket] has already been
created and any transports set up as well with functions such as
xref:nng_dial.3.adoc[`nng_dial()`]
or xref:nng_listen.3.adoc[`nng_listen()`].

[source,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

[.text-left]
xref:libnng.3.adoc[libnng(3)],
xref:nng_ctx_close.3.adoc[nng_ctx_close(3)],
xref:nng_ctx_open.3.adoc[nng_ctx_open(3)],
xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt(3)],
xref:nng_ctx_id.3.adoc[nng_ctx_id(3)],
xref:nng_ctx_recv.3.adoc[nng_ctx_recv(3)],
xref:nng_ctx_send.3.adoc[nng_ctx_send(3)],
xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt(3)],
xref:nng_dialer.5.adoc[nng_dialer(5)],
xref:nng_listener.5.adoc[nng_listener(5)],
xref:nng_socket.5.adoc[nng_socket(5)],
xref:nng_options.5.adoc[nng_options(5)],
xref:nng.7.adoc[nng(7)]