fixes #449 Want more flexible pipe events

This changes the signature of nng_pipe_notify(), and the associated
events.  The documentation is updated to reflect this.

We have also broken the lock up so that we don't hold the master
socket lock for some of these things, which may have beneficial
impact on performance.

1 files changed, 37 insertions, 22 deletions

diff --git a/docs/man/nng_pipe_notify.3.adoc b/docs/man/nng_pipe_notify.3.adoc
index 34b640c8..0a8785e3 100644
--- a/docs/man/nng_pipe_notify.3.adoc
+++ b/docs/man/nng_pipe_notify.3.adoc
@@ -19,40 +19,55 @@ nng_pipe_notify - register pipe notification callback
 ----
 #include <nng/nng.h>
 
-typedef enum {
-        NNG_PIPE_ADD,
-        NNG_PIPE_REM,
-} nng_pipe_action;
+enum {
+        NNG_PIPE_EV_ADD_PRE,
+        NNG_PIPE_EV_ADD_POST,
+        NNG_PIPE_EV_REM_POST,
+};
 
-typedef void (*nng_pipe_cb)(nng_pipe, nng_pipe_action, void *);
+typedef void (*nng_pipe_cb)(nng_pipe, int, void *);
 
-int nng_pipe_notify(nng_socket s, nng_pipe_cb cb, void *arg);
+int nng_pipe_notify(nng_socket s, int ev, nng_pipe_cb cb, void *arg);
 ----
 
 == DESCRIPTION
 
 The `nng_pipe_notify()` function registers the callback function _cb_
-to be called whenever a <<nng_pipe.5#,pipe>> is added to or removed from the
-socket _s_.
+to be called whenever a <<nng_pipe.5#,pipe>> the pipe event specified by
+_ev_ occurs on the socket _s_.
+The callback _cb_ will be passed _arg_ as its final argument.
 
-The function _cb_ will be called with the action `NNG_PIPE_ADD` just before
-a pipe is added to the socket (as a result of a connection being established).
-The final argument passed will be the argument _arg_ that was specified when
-the function was registered.
+A different callback may be supplied for each event.
+Each event may have at most one callback registered.
+Registering a callback implicitly unregisters any previously registered.
 
-The function _cb_ will also be called with the action `NNG_PIPE_REM` when
-the pipe is being removed from the socket for any reason.
-This will also use the same argument _arg_.
+The following pipe events are supported:
 
-NOTE: Only one callback can be registered for a given socket. 
-Subsequent calls to `nng_pipe_notify()` on the same socket will overwrite
-any prior registration.
+`NNG_PIPE_EV_ADD_PRE`:: This event occurs after a connection and negotiation
+has completed, but before the pipe is added to the socket.
+If the pipe is closed (using `<<nng_pipe_close.3#,nng_pipe_close()>>`) at
+this point, the socket will never see the pipe, and no further events will
+occur for the given pipe.
 
-TIP: The callback _cb_ may reject a pipe for any reason by simply closing
+`NNG_PIPE_EV_ADD_POST`:: This event occurs after the pipe is fully added to
+the socket.
+Prior to this time, it is not possible to communicate over the pipe with
+the socket.
+
+`NNG_PIPE_EV_REM_POST`:: This event occurs after the pipe has been removed
+from the socket.
+The underlying transport may be closed at this point, and it is not
+possible communicate using this pipe.
+
+TIP: The callback _cb_ may close a pipe for any reason by simply closing
 it using `<<nng_pipe_close.3#,nng_pipe_close()>>`.
-This might be done, for example, if the remote peer is not authorized to
-access this session, based on values determined with the aid of
-`<<nng_pipe_getopt.3#,nng_pipe_getopt()>>`.
+This might be done before the pipe is added to the socket (during
+`NNG_PIPE_EV_ADD_PRE`), for example, if the remote peer is not authorized.
+
+TIP: It is possible to register the same _cb_ and _arg_ for different events
+by calling this function separately for different values of _ev_.
+
+NOTE: This function ignores invalid values for _ev_.
 
 == RETURN VALUES