From 77a3c36ff1f11215229a4efdb821a3cb83a9d6fc Mon Sep 17 00:00:00 2001 From: Pieter Hintjens Date: Wed, 4 Aug 2010 14:43:33 +0200 Subject: 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 (limited to 'doc') diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf index 15633a3..c20001b 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 d13f572..e8a3a97 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 a74e81d..62c4584 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 f944bda..a1f835e 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 0061c37..47e0540 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 d43ff62..e25f460 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 0000000..e5ba83f --- /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 61939a5..e3e9ab2 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 b3325f2..ae6ae9b 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 0e4cfb5..e1cc014 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 04bbbc8..60c85eb 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 2805f71..b0c6a6b 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 81f6747..24475e9 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 1da353b..1394a4e 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 f41a42e..49e761c 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 dbf6612..cb90db7 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 d31dbae..d34be79 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 8378757..a9cefff 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 b4ef393..ddc004a 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 75c8e74..97f07bf 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 05abfa6..ecbe045 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 4017db2..862cbd6 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 d96af3e..92c5efe 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 a3f84f2..2d198cf 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 79d3dc1..8aba42a 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 419e386..37524c8 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 a5a2601..9fef404 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 23cc317..7f0ac4e 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 c8d517b..5f142f7 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 61f30e3..0624c59 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 a845f62..29d3543 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 820fa30..546c7a6 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 0ad3a55..e5cf0c4 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 . -- cgit v1.2.3