zmq_proxy_chain(3)
==================

NAME
----
zmq_proxy_chain - start built-in 0MQ a proxy chain in the same thread
control flow


SYNOPSIS
--------
*int zmq_proxy_chain (const void '**frontends', const void '**backends', 
     const void '*capture', const void **hooks_, const void '*control');*


DESCRIPTION
-----------
The _zmq_proxy_chain()_ function starts the built-in 0MQ proxy in the 
current application thread, as _zmq_proxy()_, _zmq_proxy_steerable()_, or 
_zmq_proxy_hook()_ do. Please, refer to these functions for their general 
description and usage. We describe here only the additional proxy chaining 
capability.

Note that compared to the other proxy functions, the arguments _frontends_, 
_backends_ and _hooks_ receive arrays instead of single values. Say one need 
to implement the following architecture:

*Process      client              proxy1                  proxy2              worker*
               |             |-----------|             |----------|            |
*socket*         cl           f1          b1            f2          b2           wk
*endpoint*       |c----e1-----b|           |c----e2-----b|          |c----e3----b|

Note: "c" is for connect, "b" for bind.

With the other proxy functions, one needs typically one thread for each proxy:
----
thread 1: zmq_proxy(f1, b1);
thread 2: zmq_proxy(f2, b2);
----

With _zmq_proxy_chain_, it can be performed with only one thread:
----
void** f = {f1, f2, NULL);
void** b = {b1, b2, NULL);
single thread: zmq_proxy_chain(f, b, NULL, NULL, NULL);
----

Note: the three NULL arguments are for capture, hooks, and control, since 
_zmq_proxy_chain_ is built on top of _zmq_proxy_hook_, itself built on top 
of _zmq_proxy_steerable_, itself built on top of _zmq_proxy_. Of course, hook and  
steering features can be used along with chaining.

We have limited the number of sockets that can be chained in a single command to 10, what 
should be largely sufficient. The reason is to avoid dynamic memory allocation.

Arguments frontends and backends shall be arrays of sockets of type void*, terminated 
by NULL. Both arrays shall terminate by NULL at the same indice, otherwise, an error is 
returned. Argument hooks shall be NULL or of the same length than the socket arrays. No 
NULL is required at the end of hooks. Any number of elements may be NULL where no hook 
is implemented in some proxies.


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.
Refer to linkzmq:zmq_proxy_steerable[3] for a description of the zmq_steerable.
Refer to linkzmq:zmq_proxy_hook[3] for a description of the zmq_hook.

EXAMPLE USAGE
-------------
_zmq_proxy_chain_ aims at building protocol layers by easing the chaining of some 
proxies typically by chaining:
DEALER | ROUTER <---> STREAM <---> DEALER
in the same thread. Any kind of protocol feature can be added via hooks.

cf also zmq_proxy, zmq_proxy_steerable, zmq_proxy_hook.

RETURN VALUE
------------
The _zmq_proxy_chain()_ function returns 0 if TERMINATE is sent to its
control socket. Otherwise, it returns `-1` and 'errno' set to *ETERM* (the
0MQ 'context' associated with either of the specified sockets was terminated).


EXAMPLE
-------
cf test_proxy_chain.cpp
An example capable of proxying CURVE will be added soon.

SEE ALSO
--------
linkzmq:zmq_proxy[3]
linkzmq:zmq_proxy_steerable[3]
linkzmq:zmq_proxy_hook[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>.