ZMQ_PROXY_STEERABLE(3)            0MQ Manual            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 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:

       o   number of messages received by the frontend socket

       o   number of bytes received by the frontend socket

       o   number of messages sent by the frontend socket

       o   number of bytes sent by the frontend socket

       o   number of messages received by the backend socket

       o   number of bytes received by the backend socket

       o   number of messages sent by the backend socket

       o   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                         10/23/2023            ZMQ_PROXY_STEERABLE(3)