From 9d71bbc9f67478ccc28bf6ea9cb1617e8293be94 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Mon, 25 Mar 2024 21:11:43 -0700
Subject: More updates

---
 docs/man/nng_ctx.5.adoc | 176 ------------------------------------------------
 1 file changed, 176 deletions(-)
 delete mode 100644 docs/man/nng_ctx.5.adoc

(limited to 'docs/man/nng_ctx.5.adoc')

diff --git a/docs/man/nng_ctx.5.adoc b/docs/man/nng_ctx.5.adoc
deleted file mode 100644
index c8ab62cd..00000000
--- a/docs/man/nng_ctx.5.adoc
+++ /dev/null
@@ -1,176 +0,0 @@
-= 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_get.3.adoc[nng_ctx_get(3)],
-xref:nng_ctx_id.3.adoc[nng_ctx_id(3)],
-xref:nng_ctx_recv.3.adoc[nng_ctx_recv(3)],
-xref:nng_ctx_recvmsg.3.adoc[nng_ctx_recvmsg(3)],
-xref:nng_ctx_send.3.adoc[nng_ctx_send(3)],
-xref:nng_ctx_sendmsg.3.adoc[nng_ctx_sendmsg(3)],
-xref:nng_ctx_set.3.adoc[nng_ctx_set(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)]
-- 
cgit v1.2.3-70-g09d2

