2023-10-21 01:50:38 +02:00
= zmq_proxy_steerable(3)
2013-10-18 16:35:54 +02:00
2023-10-21 01:50:38 +02:00
== NAME
2023-10-09 01:56:03 +02:00
zmq_proxy_steerable - built-in 0MQ proxy with control flow
2013-10-18 16:35:54 +02:00
2023-10-21 01:50:38 +02:00
== SYNOPSIS
2013-10-18 16:35:54 +02:00
*int zmq_proxy_steerable (const void '*frontend', const void '*backend',
2013-12-23 13:14:32 +01:00
const void '*capture', const void '*control');*
2013-10-18 16:35:54 +02:00
2023-10-21 01:50:38 +02:00
== DESCRIPTION
2023-10-09 01:56:03 +02:00
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.
2023-10-12 17:24:57 +02:00
When a _control_ socket of type _REP_ or _PAIR_ is provided to the proxy function the
2023-10-09 01:56:03 +02:00
application may send commands to the proxy. The following commands are
supported.
_PAUSE_::
2023-10-12 17:24:57 +02:00
The proxy will cease transferring messages between its endpoints. _REP_ control socket will reply with an empty message. No response otherwise.
2023-10-09 01:56:03 +02:00
_RESUME_::
2023-10-12 17:24:57 +02:00
The proxy will resume transferring messages between its endpoints. _REP_ control socket will reply with an empty message. No response otherwise.
2023-10-09 01:56:03 +02:00
_TERMINATE_::
2023-10-12 17:24:57 +02:00
The proxy function will exit with a return value of 0. _REP_ control socket will reply with an empty message. No response otherwise.
2023-10-09 01:56:03 +02:00
_STATISTICS_::
2023-10-12 17:24:57 +02:00
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.
2023-10-09 01:56:03 +02:00
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
2023-10-12 17:24:57 +02:00
Message totals count each part in a multipart message individually.
2023-10-09 01:56:03 +02:00
2023-10-21 01:50:38 +02:00
== RETURN VALUE
2023-10-09 01:56:03 +02:00
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).
2023-10-21 01:50:38 +02:00
== EXAMPLE
2023-10-09 01:56:03 +02:00
.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);
----
2013-10-18 16:35:54 +02:00
2023-10-21 01:50:38 +02:00
== SEE ALSO
2023-11-03 11:36:47 +01:00
* 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]
2013-10-18 16:35:54 +02:00
2023-10-21 01:50:38 +02:00
== AUTHORS
2013-10-18 16:35:54 +02:00
This page was written by the 0MQ community. To make a change please
2023-11-22 23:18:23 +01:00
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.