libzmq/doc/zmq_proxy_steerable.adoc

= zmq_proxy_steerable(3)

== NAME
zmq_proxy_steerable - built-in 0MQ proxy with 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 is a variant of the _zmq_proxy()_ function.
It accepts a fourth _control_ socket.  When the _control_ socket is _NULL_ the
two functions operate identically.

When a _control_ socket of type _REP_ or _PAIR_ is provided to the proxy function the
application may send commands to the proxy.  The following commands are
supported.

_PAUSE_::
    The proxy will cease transferring messages between its endpoints.  _REP_ control socket will reply with an empty message. No response otherwise.

_RESUME_::
    The proxy will resume transferring messages between its endpoints.  _REP_ control socket will reply with an empty message. No response otherwise. 

_TERMINATE_::
    The proxy function will exit with a return value of 0.  _REP_ control socket will reply with an empty message. No response otherwise.

_STATISTICS_::
    The proxy state will remain unchanged and reply with a set of simple summary values of the messages that have been sent through the proxy as described next. Control socket must support sending.

There are eight statistics values, each of size _uint64_t_ in the multi-part
message reply to the _STATISTICS_ command.  These are:

- number of messages received by the frontend socket

- number of bytes received by the frontend socket

- number of messages sent by the frontend socket

- number of bytes sent by the frontend socket

- number of messages received by the backend socket

- number of bytes received by the backend socket

- number of messages sent by the backend socket

- number of bytes sent by the backend socket

Message totals count each part in a multipart message individually.


== RETURN VALUE
The _zmq_proxy_steerable()_ function returns 0 if TERMINATE is received on its
control socket.  Otherwise, it returns -1 and errno set to ETERM or EINTR (the
0MQ context associated with either of the specified sockets was terminated) or
EFAULT (the provided frontend or backend was invalid).


== EXAMPLE
.Create a function to run the proxy
----
// Create the frontend and backend sockets to be proxied
void *frontend = zmq_socket (context, ZMQ_ROUTER);
void *backend = zmq_socket (context, ZMQ_DEALER);

// Create the proxy control socket
void *control = zmq_socket (context, ZMQ_REP);

// Bind the sockets.  
zmq_bind (frontend, "tcp://*:5555");
zmq_bind (backend, "tcp://*:5556");
zmq_bind (control, "tcp://*:5557");

zmq_proxy_steerable(frontend, backend, NULL, control);
----
.Code in another thread/process to steer the proxy.
----
void *control = zmq_socket (context, ZMQ_REQ);
zmq_connect (control, "tcp://*:5557");

zmq_msg_t msg;

zmq_send (control, "PAUSE", 5, 0);
zmq_msg_recv (&msg, control, 0));

zmq_send (control, "RESUME", 6, 0);
zmq_msg_recv (&msg, control, 0));

zmq_send (control, "STATISTICS", 10, 0);
while (1) {
    zmq_msg_recv (&msg, control, 0));
    printf(" %lu", *(uint64_t *)zmq_msg_data (&msg));
    if (!zmq_msg_get (&msg, ZMQ_MORE))
        break;
}
printf("\n");

zmq_send (control, "TERMINATE", 9, 0);
zmq_msg_recv (&msg, control, 0));

zmq_close(frontend);
zmq_close(backend);
zmq_close(control);
----


== SEE ALSO
* xref:zmq_proxy.adoc[zmq_proxy]
* xref:zmq_bind.adoc[zmq_bind]
* xref:zmq_connect.adoc[zmq_connect]
* xref:zmq_socket.adoc[zmq_socket]
* xref:zmq.adoc[zmq]


== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.