mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-12 10:33:52 +01:00
b6ca9b2983
* migrate from the old, unmaintained "asciidoc-py" tool to the new "asciidoctor" generator * migrate from asciidoc-py syntax to the modern Asciidoc syntax (especially page titles and section titles) * remove the need of "xmlto" utility to create the manpage output; use asciidoctor for that * add HTML output support to the doc/Makefile by using asciidoctor * change API documentation files extension from .txt to .adoc to make it more explicit that they are Asciidoc-encoded (as a bonus several IDE plugins will autodetect the .adoc format as Asciidoc) * remove asciidoc.conf: asciidoctor does not support that; this also required replacing the macro linkzmq into all documentation pages * add a new Github action CI do deploy to Github Pages the static HTMLs produced by Asciidoctors * removed references to the "xmlto" and "a2x" tools from the build and packaging systems: Asciidoctor can convert the documentation directly to e.g. pdf (via extended converters) and anyway there was no code/target for using "xmlto" and "a2x" tools anyway
122 lines
3.6 KiB
Plaintext
122 lines
3.6 KiB
Plaintext
= 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 <http://www.zeromq.org/docs:contributing>.
|