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 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.

       RESUME
           The proxy will resume transferring messages between its endpoints.

       TERMINATE
           The proxy function will exit with a return value of 0.

       STATISTICS
           The proxy behavior 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.

       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

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

       zmq_proxy(3) zmq_bind(3) zmq_connect(3) zmq_socket(3) 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.

0MQ 4.3.5                                          03/31/2024                             ZMQ_PROXY_STEERABLE(3)