fixes #591 incorrect reuse of server instances by websocket

This also arranges for server shutdown to be handled using
the reaper, leading to more elegant cleanup.

1 files changed, 18 insertions, 3 deletions

diff --git a/docs/man/nng_http_server_stop.3http.adoc b/docs/man/nng_http_server_stop.3http.adoc
index bf45adc9..8082409c 100644
--- a/docs/man/nng_http_server_stop.3http.adoc
+++ b/docs/man/nng_http_server_stop.3http.adoc
@@ -25,9 +25,23 @@ void nng_http_server_stop(nng_http_server *server);
 
 == DESCRIPTION
 
-The `nng_http_server_stop()` stops the HTTP server instance _server_.
-This will cause it to close any underlying TCP sockets, and to terminate
-any HTTP connections associated with it.
+The `nng_http_server_stop()` undoes the effect of
+`<<nng_http_server_start.3http#,nng_http_server_start()>>`.
+
+Each call by
+`<<nng_http_server_start.3http#,nng_http_server_start()>>` acts as reference
+count, and should be matched by a call to `nng_http_server_stop()`.
+When the reference count drops to zero, then the server is actually stopped,
+and existing open connections to it are closed.
+
+This function does not wait for the connections to close.
+
+NOTE: Once the server instance is actually stopped, it cannot be started again,
+and any future calls to `<<nng_http_server_hold.3http#,nng_http_server_hold()>>`
+will return a new instance of the server.
+It is expected that the caller will follow this function call with a call to
+`<<nng_http_server_release.3http#,nng_http_server_release()>>`.
+
 
 == RETURN VALUES
 
@@ -41,5 +55,6 @@ None.
 
 [.text-left]
 <<nng_http_server_hold.3http#,nng_http_server_hold(3http)>>,
+<<nng_http_server_release.3http#,nng_http_server_release(3http)>>,
 <<nng_http_server_start.3http#,nng_http_server_start(3http)>>,
 <<nng.7#,nng(7)>>