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, 17 insertions, 4 deletions

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.