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.

1 files changed, 53 insertions, 0 deletions

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)>>