add doc to zmq_proxy_steerable

doc/Makefile.am

@@ -7,7 +7,7 @@ MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_disconnect.3 zmq_close.3 \
     zmq_msg_get.3 zmq_msg_set.3 zmq_msg_more.3 \
     zmq_getsockopt.3 zmq_setsockopt.3 \
     zmq_socket.3 zmq_socket_monitor.3 zmq_poll.3 \
-    zmq_errno.3 zmq_strerror.3 zmq_version.3 zmq_proxy.3 \
+    zmq_errno.3 zmq_strerror.3 zmq_version.3 zmq_proxy.3 zmq_proxy_steerable.3 \
     zmq_sendmsg.3 zmq_recvmsg.3 zmq_init.3 zmq_term.3 \
     zmq_z85_encode.3 zmq_z85_decode.3 zmq_curve_keypair.3
 

doc/zmq_proxy_steerable.txt

@@ -0,0 +1,96 @@
+zmq_proxy_steerable(3)
+======================
+
+NAME
+----
+zmq_proxy_steerable - start built-in 0MQ proxy with STOP/RESUME/TERMINATE 
+control flow
+
+
+SYNOPSIS
+--------
+*int zmq_proxy_steerable (const void '*frontend', const void '*backend', 
+							const void '*capture', const void '*control');*
+
+
+DESCRIPTION
+-----------
+The _zmq_proxy_steerable()_ function starts the built-in 0MQ proxy in the 
+current application thread, as _zmq_proxy()_ do. Please, refer to this function
+for the general description and usage. We describe here only the additional 
+control flow provided by the socket passed as the fourth argument "control".
+
+_zmq_proxy()_ runs in the current thread and returns only if/when the current
+context is closed.
+
+If the control socket is not NULL, the proxy supports control flow. If 
+'SUSPEND\0' is received on this socket, the proxy suspends its activities. If 
+'RESUME\0' is received, it goes on. If 'TERMINATE\0' is received, it terminates
+smoothly. At start, the proxy runs normally as if zmq_proxy was used.
+
+If the control socket is NULL, the function behave exactly as if zmq_proxy
+had been called.
+
+
+Refer to linkzmq:zmq_socket[3] for a description of the available socket types.
+Refer to linkzmq:zmq_proxy[3] for a description of the zmq_proxy.
+
+EXAMPLE USAGE
+-------------
+cf zmq_proxy
+
+RETURN VALUE
+------------
+The _zmq_proxy_steerable()_ function returns 0 if TERMINATE is sent to its
+control socket. Otherwise, it returns `-1` and 'errno' set to *ETERM* (the
+0MQ 'context' associated with either of the specified sockets was terminated).
+
+
+EXAMPLE
+-------
+.Creating a shared queue proxy
+----
+//  Create frontend, backend and control sockets
+void *frontend = zmq_socket (context, ZMQ_ROUTER);
+assert (backend);
+void *backend = zmq_socket (context, ZMQ_DEALER);
+assert (frontend);
+void *control = zmq_socket (context, ZMQ_SUB);
+assert (control);
+//  Bind sockets to TCP ports
+assert (zmq_bind (frontend, "tcp://*:5555") == 0);
+assert (zmq_bind (backend, "tcp://*:5556") == 0);
+assert (zmq_connect (control, "tcp://*:5557") == 0);
+// Subscribe to the control socket since we have chosen SUB here
+assert (zmq_setsockopt (control, ZMQ_SUBSCRIBE, "", 0));
+//  Start the queue proxy, which runs until ETERM or "TERMINATE" received on
+the control socket
+zmq_proxy (frontend, backend, NULL, control);
+----
+.Set up a controller in another node, process or whatever
+----
+void *control = zmq_socket (context, ZMQ_PUB);
+assert (control);
+assert (zmq_bind (control, "tcp://*:5557") == 0);
+// stop the proxy
+assert (zmq_send (control, "STOP", 5, 0) == 0);
+// resume the proxy
+assert (zmq_send (control, "RESUME", 7, 0) == 0);
+// terminate the proxy
+assert (zmq_send (control, "TERMINATE", 10, 0) == 0);
+---
+
+
+SEE ALSO
+--------
+linkzmq:zmq_proxy[3]
+linkzmq:zmq_bind[3]
+linkzmq:zmq_connect[3]
+linkzmq:zmq_socket[3]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.