zmq_proxy_steerable.txt 2.84 KB
Newer Older
1 2 3 4 5
zmq_proxy_steerable(3)
======================

NAME
----
6
zmq_proxy_steerable - built-in 0MQ proxy with control flow
7 8 9 10 11


SYNOPSIS
--------
*int zmq_proxy_steerable (const void '*frontend', const void '*backend', 
Pieter Hintjens's avatar
Pieter Hintjens committed
12
     const void '*capture', const void '*control');*
13 14 15 16 17 18 19 20 21 22


DESCRIPTION
-----------
The _zmq_proxy_steerable()_ function starts the built-in 0MQ proxy in the 
current application thread, as _zmq_proxy()_ do. Please, refer to this function
for the general description and usage. We describe here only the additional 
control flow provided by the socket passed as the fourth argument "control".

If the control socket is not NULL, the proxy supports control flow. If 
23 24
'PAUSE' is received on this socket, the proxy suspends its activities. If 
'RESUME' is received, it goes on. If 'TERMINATE' is received, it terminates
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
smoothly. At start, the proxy runs normally as if zmq_proxy was used.

If the control socket is NULL, the function behave exactly as if zmq_proxy
had been called.


Refer to linkzmq:zmq_socket[3] for a description of the available socket types.
Refer to linkzmq:zmq_proxy[3] for a description of the zmq_proxy.

EXAMPLE USAGE
-------------
cf zmq_proxy

RETURN VALUE
------------
The _zmq_proxy_steerable()_ function returns 0 if TERMINATE is sent to its
41 42 43
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).
44 45 46 47 48 49 50 51 52 53 54 55 56


EXAMPLE
-------
.Creating a shared queue proxy
----
//  Create frontend, backend and control sockets
void *frontend = zmq_socket (context, ZMQ_ROUTER);
assert (backend);
void *backend = zmq_socket (context, ZMQ_DEALER);
assert (frontend);
void *control = zmq_socket (context, ZMQ_SUB);
assert (control);
Pieter Hintjens's avatar
Pieter Hintjens committed
57

58 59 60 61
//  Bind sockets to TCP ports
assert (zmq_bind (frontend, "tcp://*:5555") == 0);
assert (zmq_bind (backend, "tcp://*:5556") == 0);
assert (zmq_connect (control, "tcp://*:5557") == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
62

63 64
// Subscribe to the control socket since we have chosen SUB here
assert (zmq_setsockopt (control, ZMQ_SUBSCRIBE, "", 0));
Pieter Hintjens's avatar
Pieter Hintjens committed
65 66 67

//  Start the queue proxy, which runs until ETERM or "TERMINATE" 
//  received on the control socket
68
zmq_proxy_steerable (frontend, backend, NULL, control);
69 70 71 72 73 74
----
.Set up a controller in another node, process or whatever
----
void *control = zmq_socket (context, ZMQ_PUB);
assert (control);
assert (zmq_bind (control, "tcp://*:5557") == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
75

76 77
// pause the proxy
assert (zmq_send (control, "PAUSE", 5, 0) == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
78

79
// resume the proxy
80
assert (zmq_send (control, "RESUME", 6, 0) == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
81

82
// terminate the proxy
83
assert (zmq_send (control, "TERMINATE", 9, 0) == 0);
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99
---


SEE ALSO
--------
linkzmq:zmq_proxy[3]
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_socket[3]
linkzmq: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>.