From 77a3c36ff1f11215229a4efdb821a3cb83a9d6fc Mon Sep 17 00:00:00 2001 From: Pieter Hintjens Date: Wed, 4 Aug 2010 14:43:33 +0200 Subject: [PATCH] Various changes to documentation project: * Added documentation for zmq_deviced, which we're developing * Created consistent page footer in documentation template * Page footer notes doc authors and copyright statement --- doc/asciidoc.conf | 15 +++++ doc/zmq.txt | 19 ------ doc/zmq_bind.txt | 9 +-- doc/zmq_close.txt | 4 -- doc/zmq_connect.txt | 4 -- doc/zmq_cpp.txt | 4 -- doc/zmq_deviced.txt | 123 ++++++++++++++++++++++++++++++++++++++ doc/zmq_errno.txt | 4 -- doc/zmq_forwarder.txt | 4 -- doc/zmq_getsockopt.txt | 4 -- doc/zmq_init.txt | 4 -- doc/zmq_inproc.txt | 4 -- doc/zmq_ipc.txt | 4 -- doc/zmq_msg_close.txt | 4 -- doc/zmq_msg_copy.txt | 4 -- doc/zmq_msg_data.txt | 4 -- doc/zmq_msg_init.txt | 4 -- doc/zmq_msg_init_data.txt | 4 -- doc/zmq_msg_init_size.txt | 4 -- doc/zmq_msg_move.txt | 4 -- doc/zmq_msg_size.txt | 4 -- doc/zmq_pgm.txt | 5 +- doc/zmq_poll.txt | 4 -- doc/zmq_queue.txt | 4 -- doc/zmq_recv.txt | 4 -- doc/zmq_send.txt | 4 -- doc/zmq_setsockopt.txt | 4 -- doc/zmq_socket.txt | 31 +++++----- doc/zmq_streamer.txt | 4 -- doc/zmq_strerror.txt | 4 -- doc/zmq_tcp.txt | 4 -- doc/zmq_term.txt | 5 -- doc/zmq_version.txt | 4 -- 33 files changed, 156 insertions(+), 155 deletions(-) create mode 100644 doc/zmq_deviced.txt diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf index 15633a39..c20001b4 100644 --- a/doc/asciidoc.conf +++ b/doc/asciidoc.conf @@ -33,6 +33,21 @@ template::[header-declarations] {manname} {manpurpose} +[footer] + +AUTHORS +Man pages by Martin Lucina <mato@kotelna.sk>, Martin Sustrik <sustrik@250bpm.com>, and Pieter Hintjens <ph@imatix.com>. + + +RESOURCES +Main web site: http://www.zeromq.org/ +Report bugs to the 0MQ development mailing list: <zeromq-dev@lists.zeromq.org> + + +COPYRIGHT +Copyright (c) 2007-2010 iMatix Corporation and contributors. License LGPLv3+: GNU LGPL 3 or later <http://gnu.org/licenses/lgpl.html>. This is free software: you are free to change it and redistribute it. There is NO WARRANTY, to the extent permitted by law. For details see the files COPYING and COPYING.LESSER included with the 0MQ distribution. + + endif::backend-docbook[] endif::doctype-manpage[] diff --git a/doc/zmq.txt b/doc/zmq.txt index d13f5728..e8a3a97a 100644 --- a/doc/zmq.txt +++ b/doc/zmq.txt @@ -200,22 +200,3 @@ Other language bindings Other language bindings (Python, Ruby, Java and more) are provided by members of the 0MQ community and pointers can be found on the 0MQ website. - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . - - -RESOURCES ---------- -Main web site: - -Report bugs to the 0MQ development mailing list: - - -COPYING -------- -Free use of this software is granted under the terms of the GNU Lesser General -Public License (LGPL). For details see the files `COPYING` and `COPYING.LESSER` -included with the 0MQ distribution. diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.txt index a74e81d7..62c45840 100644 --- a/doc/zmq_bind.txt +++ b/doc/zmq_bind.txt @@ -68,8 +68,8 @@ assert (socket); /* Bind it to a in-process transport with the address 'my_publisher' */ int rc = zmq_bind (socket, "inproc://my_publisher"); assert (rc == 0); -/* Bind it to a TCP transport on port 5555 of the 'eth0' interface */ -rc = zmq_bind (socket, "tcp://eth0:5555"); +/* Bind it to a TCP transport on port 5555 of all local interfaces */ +rc = zmq_bind (socket, "tcp://*:5555"); assert (rc == 0); ---- @@ -80,8 +80,3 @@ linkzmq:zmq_connect[3] linkzmq:zmq_socket[3] linkzmq:zmq[7] - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_close.txt b/doc/zmq_close.txt index f944bda2..a1f835e1 100644 --- a/doc/zmq_close.txt +++ b/doc/zmq_close.txt @@ -41,7 +41,3 @@ linkzmq:zmq_term[3] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt index 0061c376..47e0540a 100644 --- a/doc/zmq_connect.txt +++ b/doc/zmq_connect.txt @@ -79,7 +79,3 @@ linkzmq:zmq_socket[3] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_cpp.txt b/doc/zmq_cpp.txt index d43ff62a..e25f4605 100644 --- a/doc/zmq_cpp.txt +++ b/doc/zmq_cpp.txt @@ -204,7 +204,3 @@ SEE ALSO linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_deviced.txt b/doc/zmq_deviced.txt new file mode 100644 index 00000000..e5ba83f1 --- /dev/null +++ b/doc/zmq_deviced.txt @@ -0,0 +1,123 @@ +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: + +---- + + + + + ... + ... + ... + + + ... + ... + ... + + + +---- + +*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 - + + + + + + + + + + + + + + + + +---- + + +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] diff --git a/doc/zmq_errno.txt b/doc/zmq_errno.txt index 61939a53..e3e9ab25 100644 --- a/doc/zmq_errno.txt +++ b/doc/zmq_errno.txt @@ -44,7 +44,3 @@ SEE ALSO linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_forwarder.txt b/doc/zmq_forwarder.txt index b3325f24..ae6ae9bc 100644 --- a/doc/zmq_forwarder.txt +++ b/doc/zmq_forwarder.txt @@ -27,7 +27,3 @@ SEE ALSO linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt index 0e4cfb5c..e1cc014d 100644 --- a/doc/zmq_getsockopt.txt +++ b/doc/zmq_getsockopt.txt @@ -235,7 +235,3 @@ linkzmq:zmq_socket[3] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_init.txt b/doc/zmq_init.txt index 04bbbc87..60c85eb7 100644 --- a/doc/zmq_init.txt +++ b/doc/zmq_init.txt @@ -40,7 +40,3 @@ linkzmq:zmq[7] linkzmq:zmq_term[3] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_inproc.txt b/doc/zmq_inproc.txt index 2805f71a..b0c6a6ba 100644 --- a/doc/zmq_inproc.txt +++ b/doc/zmq_inproc.txt @@ -83,7 +83,3 @@ linkzmq:zmq_pgm[7] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_ipc.txt b/doc/zmq_ipc.txt index 81f67476..24475e93 100644 --- a/doc/zmq_ipc.txt +++ b/doc/zmq_ipc.txt @@ -74,7 +74,3 @@ linkzmq:zmq_pgm[7] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_msg_close.txt b/doc/zmq_msg_close.txt index 1da353b6..1394a4ef 100644 --- a/doc/zmq_msg_close.txt +++ b/doc/zmq_msg_close.txt @@ -48,7 +48,3 @@ linkzmq:zmq_msg_size[3] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_msg_copy.txt b/doc/zmq_msg_copy.txt index f41a42e2..49e761c5 100644 --- a/doc/zmq_msg_copy.txt +++ b/doc/zmq_msg_copy.txt @@ -50,7 +50,3 @@ linkzmq:zmq_msg_close[3] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_msg_data.txt b/doc/zmq_msg_data.txt index dbf66122..cb90db7b 100644 --- a/doc/zmq_msg_data.txt +++ b/doc/zmq_msg_data.txt @@ -42,7 +42,3 @@ linkzmq:zmq_msg_close[3] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_msg_init.txt b/doc/zmq_msg_init.txt index d31dbae2..d34be799 100644 --- a/doc/zmq_msg_init.txt +++ b/doc/zmq_msg_init.txt @@ -59,7 +59,3 @@ linkzmq:zmq_msg_size[3] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_msg_init_data.txt b/doc/zmq_msg_init_data.txt index 83787570..a9cefff7 100644 --- a/doc/zmq_msg_init_data.txt +++ b/doc/zmq_msg_init_data.txt @@ -74,7 +74,3 @@ linkzmq:zmq_msg_size[3] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_msg_init_size.txt b/doc/zmq_msg_init_size.txt index b4ef393a..ddc004a6 100644 --- a/doc/zmq_msg_init_size.txt +++ b/doc/zmq_msg_init_size.txt @@ -52,7 +52,3 @@ linkzmq:zmq_msg_size[3] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_msg_move.txt b/doc/zmq_msg_move.txt index 75c8e74c..97f07bf7 100644 --- a/doc/zmq_msg_move.txt +++ b/doc/zmq_msg_move.txt @@ -45,7 +45,3 @@ linkzmq:zmq_msg_close[3] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_msg_size.txt b/doc/zmq_msg_size.txt index 05abfa66..ecbe0457 100644 --- a/doc/zmq_msg_size.txt +++ b/doc/zmq_msg_size.txt @@ -42,7 +42,3 @@ linkzmq:zmq_msg_close[3] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt index 4017db2c..862cbd6d 100644 --- a/doc/zmq_pgm.txt +++ b/doc/zmq_pgm.txt @@ -151,7 +151,4 @@ linkzmq:zmq_ipc[7] linkzmq:zmq_inproc[7] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . + diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.txt index d96af3ef..92c5efe6 100644 --- a/doc/zmq_poll.txt +++ b/doc/zmq_poll.txt @@ -127,7 +127,3 @@ linkzmq:zmq[7] Your operating system documentation for the _poll()_ system call. -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_queue.txt b/doc/zmq_queue.txt index a3f84f28..2d198cf9 100644 --- a/doc/zmq_queue.txt +++ b/doc/zmq_queue.txt @@ -27,7 +27,3 @@ SEE ALSO linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_recv.txt b/doc/zmq_recv.txt index 79d3dc16..8aba42af 100644 --- a/doc/zmq_recv.txt +++ b/doc/zmq_recv.txt @@ -105,7 +105,3 @@ linkzmq:zmq_socket[7] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_send.txt b/doc/zmq_send.txt index 419e3869..37524c82 100644 --- a/doc/zmq_send.txt +++ b/doc/zmq_send.txt @@ -103,7 +103,3 @@ linkzmq:zmq_socket[7] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index a5a2601f..9fef404b 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/zmq_setsockopt.txt @@ -267,7 +267,3 @@ linkzmq:zmq_socket[3] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt index 23cc3175..7f0ac4e8 100644 --- a/doc/zmq_socket.txt +++ b/doc/zmq_socket.txt @@ -157,22 +157,24 @@ is connected to at least one _node_. When a pipeline stage is connected to multiple _nodes_ data is load-balanced among all connected _nodes_. -ZMQ_DOWNSTREAM -^^^^^^^^^^^^^^ -A socket of type 'ZMQ_DOWNSTREAM' is used by a pipeline _node_ to send messages +ZMQ_PUSH +^^^^^^^^ +A socket of type 'ZMQ_PUSH' is used by a pipeline _node_ to send messages to downstream pipeline _nodes_. Messages are load-balanced to all connected downstream _nodes_. The _zmq_recv()_ function is not implemented for this socket type. -When a 'ZMQ_DOWNSTREAM' socket enters an exceptional state due to having +When a 'ZMQ_PUSH' socket enters an exceptional state due to having reached the high water mark for all downstream _nodes_, or if there are no downstream _nodes_ at all, then any linkzmq:zmq_send[3] operations on the socket shall block until the exceptional state ends or at least one downstream _node_ becomes available for sending; messages are not discarded. +Deprecated alias: ZMQ_DOWNSTREAM. + [horizontal] -.Summary of ZMQ_DOWNSTREAM characteristics -Compatible peer sockets:: 'ZMQ_UPSTREAM' +.Summary of ZMQ_PUSH characteristics +Compatible peer sockets:: 'ZMQ_PULL' Direction:: Unidirectional Send/receive pattern:: Send only Incoming routing strategy:: N/A @@ -180,16 +182,18 @@ Outgoing routing strategy:: Load-balanced ZMQ_HWM option action:: Block -ZMQ_UPSTREAM -^^^^^^^^^^^^ -A socket of type 'ZMQ_UPSTREAM' is used by a pipeline _node_ to receive +ZMQ_PULL +^^^^^^^^ +A socket of type 'ZMQ_PULL' is used by a pipeline _node_ to receive messages from upstream pipeline _nodes_. Messages are fair-queued from among all connected upstream _nodes_. The _zmq_send()_ function is not implemented for this socket type. +Deprecated alias: ZMQ_UPSTREAM. + [horizontal] -.Summary of ZMQ_UPSTREAM characteristics -Compatible peer sockets:: 'ZMQ_DOWNSTREAM' +.Summary of ZMQ_PULL characteristics +Compatible peer sockets:: 'ZMQ_PUSH' Direction:: Unidirectional Send/receive pattern:: Receive only Incoming routing strategy:: Fair-queued @@ -253,8 +257,3 @@ linkzmq:zmq_send[3] linkzmq:zmq_recv[3] linkzmq:zmq[7] - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_streamer.txt b/doc/zmq_streamer.txt index c8d517b9..5f142f72 100644 --- a/doc/zmq_streamer.txt +++ b/doc/zmq_streamer.txt @@ -27,7 +27,3 @@ SEE ALSO linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_strerror.txt b/doc/zmq_strerror.txt index 61f30e3d..0624c59c 100644 --- a/doc/zmq_strerror.txt +++ b/doc/zmq_strerror.txt @@ -49,7 +49,3 @@ SEE ALSO linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt index a845f622..29d35437 100644 --- a/doc/zmq_tcp.txt +++ b/doc/zmq_tcp.txt @@ -155,7 +155,3 @@ linkzmq:zmq_inproc[7] linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_term.txt b/doc/zmq_term.txt index 820fa301..546c7a61 100644 --- a/doc/zmq_term.txt +++ b/doc/zmq_term.txt @@ -51,8 +51,3 @@ SEE ALSO linkzmq:zmq[7] linkzmq:zmq_init[3] - -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . diff --git a/doc/zmq_version.txt b/doc/zmq_version.txt index 0ad3a557..e5cf0c40 100644 --- a/doc/zmq_version.txt +++ b/doc/zmq_version.txt @@ -47,7 +47,3 @@ SEE ALSO -------- linkzmq:zmq[7] -AUTHORS -------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina .