summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorMartin Lucina <mato@kotelna.sk>2010-09-04 15:51:09 +0200
committerMartin Lucina <mato@kotelna.sk>2010-09-04 15:51:09 +0200
commit83d253d72d4fe83f4a001a7cfb4059ccc52b04e0 (patch)
tree94be90cc0d34c9f35e68ecc98c357478046cdbac /doc
parent14853c2db528b3fd6eed84786053549e71f61bb7 (diff)
Revert "Removed wip zmq_deviced from master"
This reverts commit de0173754cc82f6c08875a892892f043a804554c.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am2
-rw-r--r--doc/zmq.txt4
-rw-r--r--doc/zmq_deviced.txt145
3 files changed, 149 insertions, 2 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 05cb3dc..44dcfdf 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,4 +1,4 @@
-MAN1 =
+MAN1 = zmq_deviced.1
MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_init.3 \
zmq_msg_close.3 zmq_msg_copy.3 zmq_msg_data.3 zmq_msg_init.3 \
zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_move.3 zmq_msg_size.3 \
diff --git a/doc/zmq.txt b/doc/zmq.txt
index 362f907..54c7ba1 100644
--- a/doc/zmq.txt
+++ b/doc/zmq.txt
@@ -144,7 +144,9 @@ nodes in complex messaging topologies. Devices can act as brokers that other
nodes connect to, proxies that connect through to other nodes, or any mix of
these two models.
-You can start a device in an application thread, see linkzmq:zmq_device[3].
+You can start a device in an application thread, see linkzmq:zmq_device[3],
+and you can also start devices externally, as standalone processes, see
+linkzmq:zmq_deviced[1].
ERROR HANDLING
diff --git a/doc/zmq_deviced.txt b/doc/zmq_deviced.txt
new file mode 100644
index 0000000..fd94c96
--- /dev/null
+++ b/doc/zmq_deviced.txt
@@ -0,0 +1,145 @@
+zmq_deviced(1)
+==============
+
+NAME
+----
+zmq_deviced - start built-in 0MQ devices
+
+SYNOPSIS
+--------
+
+*zmq_deviced _DEVICE_ _FRONTEND_ _BACKEND_*
+
+*zmq_deviced [_CONFIGFILE_]*
+
+DESCRIPTION
+-----------
+Starts one or more 0MQ devices. If you specify a DEVICE, FRONTEND, and BACKEND
+then _zmq_device_ starts a single device acting as a mini-broker. If you
+specify a CONFIGFILE, you can configure _zmq_device_ to start multiple
+concurrent devices with arbitrary configurations.
+
+*Note* - zmq_deviced is not yet implemented. This is a design.
+
+MINI-BROKER USAGE
+-----------------
+Runs as a mini-broker that accepts connects to both frontend and backend. This
+creates a hub-and-spoke topology in which all peers connect to the device. This
+is a robust and easy to manage topology.
+
+DEVICE is one of: *queue*, *forwarder*, or *streamer*. See
+linkzmq:zmq_device[3] for a specification of these device types.
+
+FRONTEND and BACKEND are endpoints in the format 'transport'`://`'address', See
+linkzmq:zmq_bind[3] for a specification of valid transports and addresses.
+
+
+CONFIGURED USAGE
+----------------
+CONFIGFILE is the name of an XML file, readable by 'zmq_device'. This file
+provides a specification of the devices to start and how to connect and/or bind
+their frontends and backends. If CONFIGFILE is absent or *-* then the
+configuration is read from standard input.
+
+The configuration file has this general syntax:
+
+----
+<?xml?>
+<config [ iothreads="..." ] >
+ <device type="...">
+ <frontend [ type="..." ] >
+ <set name = "..." value = "..." />...
+ <bind endpoint="..." /> ...
+ <connect address="..." /> ...
+ </frontend>
+ <backend [ type="..." ] >
+ <set name = "..." value = "..." />...
+ <bind address="..." /> ...
+ <connect address="..." /> ...
+ </backend>
+ </device>
+</config>
+----
+
+*iothreads*::
+ specifies the number of I/O threads for the process. Specify this only for
+ high-volume scenarios. See linkzmq:zmq_init[3].
+*device*::
+ defines one device. For each device element you define, 'zmq_device' will
+ start a thread.
+*frontend*::
+ defines the frontend for the device. Occurs once per device element. You
+ may override the default socket type.
+*backend*::
+ defines the backend for the device. Occurs once per device element. You
+may override the default socket type.
+*set*::
+ defines a socket option for the frontend or backend. The valid names are
+ *hwm*, *swap*, *identity*, *subscribe*, *unsubscribe*, *rate*,
+ *recovery_ivl*, *mcast_loop*, *sndbuf*, and *rcvbuf*. See
+ linkzmq:zmq_setsockopt[3].
+*bind*::
+ binds the frontend or backend to the specified endpoint. See
+ linkzmq:zmq_bind[3].
+*connect*::
+ binds the frontend or backend to the specified endpoint. See
+ linkzmq:zmq_connect[3].
+
+SOCKET TYPES
+------------
+
+By default 'zmq_device' uses these socket types:
+
+*queue* device::
+ frontend is *xrep*, backend is *xreq*.
+*forwarder* device::
+ frontend is *sub*, backend is *pub*.
+*streamer* device::
+ frontend is *pull*, backend is *push*.
+
+You can override the socket type for frontend or backend. The valid types are:
+*req*, *rep*, *xreq*, *xrep*, *sub*, *pub*, *pull*, *push*, and *pair*. See
+linkzmq:zmq_socket[3].
+
+*Note*: if you use a *sub* socket you must explicitly set a subscription filter
+or your socket will not receive any data.
+
+
+EXAMPLE
+-------
+
+.Creating a queue broker
+----
+zmq_device queue tcp://*:5050 tcp://*:5051
+----
+
+.A TCP-to-multicast proxy forwarder
+----
+zmq_device -
+<?xml?>
+<config>
+ <device type="forwarder">
+ <frontend>
+ <!-- subscribe to everything -->
+ <set name = "subscribe" value = "" />
+ <!-- connect to two publishers -->
+ <connect address="tcp://192.168.55.112:5055" />
+ <connect address="tcp://192.168.55.114:5055" />
+ </frontend>
+ <backend>
+ <!-- bind to epgm group via eth0 -->
+ <bind address="epgm://eth0;239.192.1.1:5555" />
+ </backend>
+ </device>
+</config>
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_device[3]
+linkzmq:zmq_init[3]
+linkzmq:zmq_setsockopt[3]
+linkzmq:zmq_bind[3]
+linkzmq:zmq_connect[3]
+linkzmq:zmq[7]