ZMQ_PROXY_STEERABLE(3)

✨ ZMQ_PROXY_STEERABLE(3) ✨

okay so bestie, this is a page from the 0MQ Manual and it's about the built-in 0MQ proxy that you can literally steer, like it's a little remote-controlled car except it's a message-forwarding machine 💅

---

🌸 NAME 🌸

zmq_proxy_steerable — the 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 💖

So zmq_proxy_steerable() is basically zmq_proxy() but with a glow-up: it takes a fourth socket, the control socket. And here's the tea — if that control socket is NULL, the two functions behave identically. No cap. Same thing, zero difference. 🙈

But when you hand it a control socket of type REP, your app gets to send commands to the proxy and tell it what to do. Main character energy honestly. These are the commands that are supported:

🎀 PAUSE 🎀

The proxy stops transferring messages between its endpoints. It's giving "brb bestie" 😭

🎀 RESUME 🎀

The proxy starts transferring messages between its endpoints again. We're so back. 🔥

🎀 TERMINATE 🎀

The proxy function exits with a return value of 0. Bye queen 👑

🎀 STATISTICS 🎀

The proxy behavior stays exactly the same — no changes, no drama — and it replies with a set of simple summary values describing the messages that have been sent through the proxy, as described right below. ✨

There are eight statistics values, and each one is size uint64_t, living in the multi-part message reply to the STATISTICS command. They 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 🌈

zmq_proxy_steerable() returns 0 if TERMINATE is received on its control socket. 💖

Otherwise it returns -1 and sets errno to one of these:

• ETERM or EINTR — the 0MQ context associated with either of the specified sockets was terminated 😭
• EFAULT — the provided frontend or backend was invalid 💀

---

🍓 EXAMPLE 🍓

First up: make 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);

Then, 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. 🫶 Wanna make a change? Please read the 0MQ Contribution Policy at http://www.zeromq.org/docs:contributing.

---

and that's the whole vibe, bestie — this page was served fresh from 0MQ 4.3.5 on 10/09/2023. go slay some sockets 💅✨