fixes #334 Separate context for state machines from sockets

This provides context support for REQ and REP sockets.
More discussion around this is in the issue itself.

Optionally we would like to extend this to the surveyor pattern.

Note that we specifically do not support pollable descriptors
for non-default contexts, and the results of using file descriptors
for polling (NNG_OPT_SENDFD and NNG_OPT_RECVFD) is undefined.

In the future, it might be nice to figure out how to factor in
optional use of a message queue for users who want more buffering,
but we think there is little need for this with cooked mode.

11 files changed, 735 insertions, 12 deletions

diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index feab3ebf..8df29861 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -195,6 +195,22 @@ The following functions are used to register a transport for use.
 | <<nng_zt_register.3#,nng_zt_register()>>|register ZeroTier transport
 |===
 
+=== Protocol Contexts
+
+The following functions are useful to separate the protocol processing
+from a socket object, into a separate context.
+This can allow multiple contexts to be created on a single socket for
+concurrent applications.
+
+|===
+|<<nng_ctx_close.3#,nng_ctx_close()>>|close context
+|<<nng_ctx_getopt.3#,nng_ctx_getopt()>>|get context option
+|<<nng_ctx_open.3#,nng_ctx_open()>>|create context
+|<<nng_ctx_recv.3#,nng_ctx_recv()>>|receive message using context asynchronously
+|<<nng_ctx_send.3#,nng_ctx_send()>>|send message using context asynchronously
+|<<nng_ctx_setopt.3#,nng_ctx_setopt()>>|set context option
+|===
+
 === URL Object
 
 Common functionality is supplied for parsing and handling
diff --git a/docs/man/nng_ctx.5.adoc b/docs/man/nng_ctx.5.adoc
new file mode 100644
index 00000000..c59a4a4c
--- /dev/null
+++ b/docs/man/nng_ctx.5.adoc
@@ -0,0 +1,161 @@
+= nng_ctx(5)
+//
+// Copyright 2018 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 uint32_t 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
+<<nng_dialer.5#,dialers>>,
+<<nng_listener.5#,listeners>>,
+and <<nng_pipe.5#,pipes>>,
+while still benefiting from separate state tracking.
+
+For example, a <<nng_req.7#,_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.
+
+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 <<nng.7#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: <<nng.7#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
+<<nng.7#raw_mode,raw mode>> sockets when possible.
+
+WARNING: Use of file descriptor polling (with descriptors
+obtained using the
+<<nng_options.5#NNG_OPT_RECVFD,`NNG_OPT_RECVFD`>> or
+<<nng_options.5#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.
+
+== EXAMPLE
+
+The following program fragment demonstrates the use of contexts to implement
+a concurrent <<nng_rep.7#,_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 <<nng_socket.7#,socket>> has already been
+created and any transports set up as well with functions such as
+<<nng_dial.3#,`nng_dial()`>>
+or <<nng_listen.3#,`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
+
+<<libnng.3#,libnng(3)>>,
+<<nng_ctx_close.3#,nng_ctx_close(3)>>,
+<<nng_ctx_open.3#,nng_ctx_open(3)>>,
+<<nng_ctx_getopt.3#,nng_ctx_getopt(3)>>,
+<<nng_ctx_recv.3#,nng_ctx_recv(3)>>,
+<<nng_ctx_send.3#,nng_ctx_send(3)>>,
+<<nng_ctx_setopt.3#,nng_ctx_setopt(3)>>,
+<<nng_dialer.5#,nng_dialer(5)>>,
+<<nng_listener.5#,nng_listener(5)>>,
+<<nng_socket.5#,nng_socket(5)>>,
+<<nng_options.5#,nng_options(5)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nng_ctx_close.3.adoc b/docs/man/nng_ctx_close.3.adoc
new file mode 100644
index 00000000..16d9432e
--- /dev/null
+++ b/docs/man/nng_ctx_close.3.adoc
@@ -0,0 +1,53 @@
+= nng_ctx_close(3)
+//
+// Copyright 2018 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_close - close context
+
+== SYNOPSIS
+
+[source, 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 and the setting of the
+<<nng_options.5#NNG_OPT_LINGER,`NNG_OPT_LINGER`>> option.
+
+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.3#,`nng_close()`>>) 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_ctx_open.3#,nng_ctx_open(3)>>,
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_ctx.5#,nng_ctx(5)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nng_ctx_getopt.3.adoc b/docs/man/nng_ctx_getopt.3.adoc
new file mode 100644
index 00000000..b20ea3b4
--- /dev/null
+++ b/docs/man/nng_ctx_getopt.3.adoc
@@ -0,0 +1,128 @@
+= nng_ctx_getopt(3)
+//
+// Copyright 2018 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_getopt - get context option
+
+== SYNOPSIS
+
+[source, 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
+
+(((options, context)))
+The `nng_ctx_getopt()` functions are used to retrieve option values for
+the <<nng_ctx.5#,context>> _ctx_.
+The actual options that may be retrieved in this way vary.
+A number of them are documented in <<nng_options.5#,nng_options(5)>>.
+
+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.
+
+TIP: Generally, it will be easier to use one of the typed forms instead.
+
+==== `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 referened 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 verifyng 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 <<nng_duration.5#,durations>>
+(such as timeouts), stored in _durp_ as a number of milliseconds.
+(The special value ((`NNG_DUR_INFINITE`)) means an infinite amount of time, and
+the special value ((`NNG_DUR_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.3#,`nng_strdup()`>>
+and consequently must be freed by the caller using
+<<nng_strfree.3#,`nng_strfree()`>> 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_ctx_setopt.3#,nng_ctx_setopt(3)>>,
+<<nng_strdup.3#,nng_strdup(3)>>,
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_strfree.3#,nng_strfree(3)>>,
+<<nng_duration.5#,nng_duration(5)>>,
+<<nng_ctx.5#,nng_ctx(5)>>,
+<<nng_options.5#,nng_options(5)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nng_ctx_open.3.adoc b/docs/man/nng_ctx_open.3.adoc
new file mode 100644
index 00000000..86686417
--- /dev/null
+++ b/docs/man/nng_ctx_open.3.adoc
@@ -0,0 +1,69 @@
+= nng_ctx_open(3)
+//
+// Copyright 2018 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_open - create context
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nng/nng.h>
+
+int nng_ctx_open(nng_ctx *ctxp, nng_socket s);
+----
+
+== DESCRIPTION
+
+The `nng_ctx0_open()` function creates a separate ((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 <<nng_rep.7#,_rep_>>
+socket can each receive requests, and send replies to them, without any
+regard to or interference with each other.
+
+(((raw mode)))
+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
+<<nng.7#raw_mode,raw mode>> sockets.
+
+NOTE: Use of contexts with <<nng.7#raw_mode,raw mode>> 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.3#,nng_ctx_close(3)>>,
+<<nng_ctx_getopt.3#,nng_ctx_getopt(3)>>,
+<<nng_ctx_recv.3#,nng_ctx_recv(3)>>,
+<<nng_ctx_send.3#,nng_ctx_send(3)>>,
+<<nng_ctx_setopt.3#,nng_ctx_setopt(3)>>,
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_ctx.5#,nng_ctx(5)>>,
+<<nng_socket.5#,nng_socket(5)>>,
+<<nng_rep.7#,nng_rep(7)>>,
+<<nng_req.7#,nng_req(7)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nng_ctx_recv.3.adoc b/docs/man/nng_ctx_recv.3.adoc
new file mode 100644
index 00000000..d4e84b00
--- /dev/null
+++ b/docs/man/nng_ctx_recv.3.adoc
@@ -0,0 +1,72 @@
+= nng_ctx_recv(3)
+//
+// Copyright 2018 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_recv - receive message using context asynchronously
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+void nng_ctx_recv(nng_ctx ctx, nng_aio *aio);
+----
+
+== DESCRIPTION
+
+The `nng_ctx_recv()` receives a <<nng_msg.5#,message>> using the
+<<nng_ctx.5#,context>> _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.3#,`nng_aio_set_msg()`>>, then the completion
+callback on the _aio_ is executed.
+In this case, <<nng_aio_result.3#,`nng_aio_result()`>> 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.3#,`nng_aio_result()`>> will be non-zero.
+
+NOTE: The semantics of what receiving a message means varies from protocol to
+protocol, so examination of the protocol documentation is encouraged.
+
+== RETURN VALUES
+
+None.  (The operation completes asynchronously.)
+
+== ERRORS
+
+`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
+
+<<nng_aio_get_msg.3#,nng_aio_get_msg(3)>>,
+<<nng_aio_set_msg.3#,nng_aio_set_msg(3)>>,
+<<nng_msg_alloc.3#,nng_msg_alloc(3)>>,
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_aio.5#,nng_aio(5)>>,
+<<nng_ctx.5#,nng_ctx(5)>>,
+<<nng_msg.5#,nng_msg(5)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nng_ctx_send.3.adoc b/docs/man/nng_ctx_send.3.adoc
new file mode 100644
index 00000000..95c1a118
--- /dev/null
+++ b/docs/man/nng_ctx_send.3.adoc
@@ -0,0 +1,86 @@
+= nng_ctx_send(3)
+//
+// Copyright 2018 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_send - send message using context asynchronously
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+void nng_ctx_send(nng_ctx ctx, nng_aio *aio);
+----
+
+== DESCRIPTION
+
+The `nng_ctx_send()` sends a <<nng_msg.5#,message>> using the
+<<nng_ctx.5#,context>> _ctx_ asynchronously.
+
+The message to send must have previously been set on the _aio_
+using the <<nng_aio_set_msg.3#,`nng_aio_set_msg()`>> 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.3#,`nng_aio_result()`>>
+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.3#,`nng_aio_result()`>>
+will return a non-zero error status.
+In this case, the callback has a responsibity to retrieve the message from
+the _aio_ with <<nng_aio_get_msg.3#,`nng_aio_get_msg()`>> 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.3#,`nng_msg_free()`>>.)
+
+NOTE: The semantics of what sending a message means varies from protocol to
+protocol, so examination of the protocol documentation is encouraged.
+
+TIP: Context send operations are asynchronous.
+If a synchronous operation is needed, one can be constructed by using a
+`NULL` callback on the _aio_ and then waiting for the operation using
+<<nng_aio_wait.3#,`nng_aio_wait()`>>.
+
+== RETURN VALUES
+
+None.  (The operation completes asynchronously.)
+
+== 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.3#,nng_aio_get_msg(3)>>,
+<<nng_aio_set_msg.3#,nng_aio_set_msg(3)>>,
+<<nng_msg_alloc.3#,nng_msg_alloc(3)>>,
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_aio.5#,nng_aio(5)>>,
+<<nng_ctx.5#,nng_ctx(5)>>,
+<<nng_msg.5#,nng_msg(5)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nng_ctx_setopt.3.adoc b/docs/man/nng_ctx_setopt.3.adoc
new file mode 100644
index 00000000..4ab36e07
--- /dev/null
+++ b/docs/man/nng_ctx_setopt.3.adoc
@@ -0,0 +1,109 @@
+= nng_ctx_setopt(3)
+//
+// Copyright 2018 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_setopt - set context option
+
+== SYNOPSIS
+
+[source, 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
+(((options, context)))
+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.
+
+TIP: Generally, it will be easier to use one of the typed versions
+of this function.
+
+==== `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.5#,`nng_duration`>>.
+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_getopt.3#,nng_ctx_getopt(3)>>,
+<<nng_setopt.3#,nng_setopt(3)>>,
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_ctx.5#,nng_ctx(5)>>,
+<<nng_options.5#,nng_options(5)>>,
+<<nng_socket.5#,nng_socket(5)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nng_getopt.3.adoc b/docs/man/nng_getopt.3.adoc
index af61132c..306efbe9 100644
--- a/docs/man/nng_getopt.3.adoc
+++ b/docs/man/nng_getopt.3.adoc
@@ -16,7 +16,7 @@ nng_getopt - get socket option
 == SYNOPSIS
 
 [source, c]
------------
+----
 #include <nng/nng.h>
 
 int nng_getopt(nng_socket s, const char *opt, void *val, size_t *valszp);
@@ -34,7 +34,7 @@ int nng_getopt_size(nng_socket s, const char *opt, size_t *zp);
 int nng_getopt_string(nng_socket s, const char *opt, char **strp);
 
 int nng_getopt_uint64(nng_socket s, const char *opt, uint64_t *u64p);
------------
+----
 
 == DESCRIPTION
 
diff --git a/docs/man/nng_rep.7.adoc b/docs/man/nng_rep.7.adoc
index 255a8f4b..789b515d 100644
--- a/docs/man/nng_rep.7.adoc
+++ b/docs/man/nng_rep.7.adoc
@@ -41,15 +41,28 @@ The _rep_ protocol is the replier side, and the
 The <<nng_rep_open.3#,`nng_rep0_open()`>> functions create a replier socket.
 This socket may be used to receive messages (requests), and then to send
 replies.
+
 Generally a reply can only be sent after receiving a request.
-(Attempts to receive a message will result in `NNG_ESTATE` if there
-is no outstanding request.)
 
-Attempts to send on a socket with no outstanding requests will result
-in `NNG_ESTATE`. 
+Send operations will result in `NNG_ESTATE` if no corresponding request
+was previously received.
+
+Likewise, only one receive operation may be pending at a time.
+Any additional concurrent receive operations will result in `NNG_ESTATE`.
 
 <<nng.7#raw_mode,Raw>> mode sockets ignore all these restrictions.
 
+=== Context Operations
+
+This protocol supports the creation of <<nng_ctx.5#,contexts>> for concurrent
+use cases using <<nng_ctx_open.3#,`nng_ctx_open()`>>.
+
+Each context may have at most one outstanding request, and operates
+independently from the others.
+The restrictions for order of operations with sockets apply equally
+well for contexts, except that each context will be treated as if it were
+a separate socket.
+
 === Protocol Versions
 
 Only version 0 of this protocol is supported.
diff --git a/docs/man/nng_req.7.adoc b/docs/man/nng_req.7.adoc
index 9b956172..221023c4 100644
--- a/docs/man/nng_req.7.adoc
+++ b/docs/man/nng_req.7.adoc
@@ -53,23 +53,37 @@ The _req_ protocol is the requester side, and the
 === Socket Operations
 
 The <<nng_req_open.3#,`nng_req0_open()`>> functions create a requester socket.
-This socket may be used to send messages (requests),
-and then to receive replies.
+This socket may be used to send messages (requests), and then to receive replies.
+
 Generally a reply can only be received after sending a request.
 (Attempts to receive a message will result in `NNG_ESTATE` if there is no
 outstanding request.)
 
+Furthermore, only a single receive operation may be pending at a time.
+Attempts to post more receive operations concurrently will result in
+`NNG_ESTATE`.
+
 Requests may be canceled by sending a different request.
 This will cause the requester to discard any reply from the earlier request,
 but it will not stop a replier
 from processing a request it has already received or terminate a request
 that has already been placed on the wire.
 
-Attempts to receive on a socket with no outstanding requests will result
-in `NNG_ESTATE`. 
-
 <<nng.7#raw_mode,Raw>> mode sockets ignore all these restrictions.
 
+=== Context Operations
+
+This protocol supports the creation of <<nng_ctx.5#,contexts>> for concurrent
+use cases using <<nng_ctx_open.3#,`nng_ctx_open()`>>.
+The `NNG_OPT_REQ_RESENDTIME` value may be configured differently
+on contexts created this way.
+
+Each context may have at most one outstanding request, and operates
+independently from the others.
+The restrictions for order of operations with sockets apply equally
+well for contexts, except that each context will be treated as if it were
+a separate socket.
+
 === Protocol Versions
 
 Only version 0 of this protocol is supported.
@@ -82,7 +96,7 @@ The following protocol-specific option is available.
 ((`NNG_OPT_REQ_RESENDTIME`))::
 
    This read/write option is a duration (32-bit unsigned integer) representing
-   a relative number of milliseconds. 
+   a relative number of milliseconds.
    When a new request is started, a timer of this duration is also started.
    If no reply is received before this timer expires, then the request will
    be resent.  (Requests are also automatically resent if the peer to whom
@@ -129,7 +143,9 @@ request ID it originally used for the request.
 
 == SEE ALSO
 
+<<nng_ctx_open.3#,nng_ctx_open(3)>>,
 <<nng_device.3#,nng_device(3)>>,
 <<nng_req_open.3#,nng_req_open(3)>>,
+<<nng_ctx.5#,nng_ctx(5)>>,
 <<nng.7#,nng(7)>>,
 <<nng_rep.7#,nng_rep(7)>>