mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-12 10:33:52 +01:00
Revert "Further cleanups on reference manual"
This reverts commit 13f3481e12.
Conflicts:
doc/zmq_device.txt
doc/zmq_tcp.txt
This commit is contained in:
Martin Lucina
parent
6647e61243
commit
6c393f53e2
20
doc/zmq.txt
20
doc/zmq.txt
@ -139,14 +139,20 @@ Local in-process (inter-thread) communication transport::
|
||||
|
||||
Devices
|
||||
~~~~~~~
|
||||
0MQ provides 'devices', which are building blocks that act as intermediate
|
||||
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.
|
||||
Apart from the 0MQ library the 0MQ distribution includes 'devices' which are
|
||||
building blocks intended to serve as intermediate nodes in complex messaging
|
||||
topologies.
|
||||
|
||||
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].
|
||||
The following devices are provided:
|
||||
|
||||
Forwarder device for request-response messaging::
|
||||
linkzmq:zmq_queue[1]
|
||||
|
||||
Forwarder device for publish-subscribe messaging::
|
||||
linkzmq:zmq_forwarder[1]
|
||||
|
||||
Streamer device for parallelized pipeline messaging::
|
||||
linkzmq:zmq_streamer[1]
|
||||
|
||||
|
||||
ERROR HANDLING
|
||||
|
||||
@ -24,15 +24,10 @@ the underlying transport protocol selected.
|
||||
|
||||
The following transports are defined:
|
||||
|
||||
'inproc'::
|
||||
local in-process (inter-thread) communication transport, see
|
||||
linkzmq:zmq_inproc[7]
|
||||
'ipc'::
|
||||
local inter-process communication transport, see linkzmq:zmq_ipc[7]
|
||||
'tcp'::
|
||||
unicast transport using TCP, see linkzmq:zmq_tcp[7]
|
||||
'pgm', 'epgm'::
|
||||
reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
|
||||
'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
|
||||
'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
|
||||
'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
|
||||
'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
|
||||
|
||||
With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to
|
||||
multiple endpoints using _zmq_connect()_, while simultaneously accepting
|
||||
|
||||
@ -24,15 +24,10 @@ the underlying transport protocol selected.
|
||||
|
||||
The following transports are defined:
|
||||
|
||||
'inproc'::
|
||||
local in-process (inter-thread) communication transport, see
|
||||
linkzmq:zmq_inproc[7]
|
||||
'ipc'::
|
||||
local inter-process communication transport, see linkzmq:zmq_ipc[7]
|
||||
'tcp'::
|
||||
unicast transport using TCP, see linkzmq:zmq_tcp[7]
|
||||
'pgm', 'epgm'::
|
||||
reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
|
||||
'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
|
||||
'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
|
||||
'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
|
||||
'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
|
||||
|
||||
With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to
|
||||
multiple endpoints using _zmq_connect()_, while simultaneously accepting
|
||||
|
||||
@ -13,8 +13,7 @@ SYNOPSIS
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
The _zmq_device()_ function starts a built-in 0MQ device. The 'device'
|
||||
argument is one of:
|
||||
The _zmq_device()_ function starts a built-in 0MQ device. The 'device' argument is one of:
|
||||
|
||||
'ZMQ_QUEUE'::
|
||||
starts a queue device
|
||||
@ -23,86 +22,55 @@ argument is one of:
|
||||
'ZMQ_STREAMER'::
|
||||
starts a streamer device
|
||||
|
||||
The device connects a frontend socket to a backend socket. Conceptually, data
|
||||
flows from frontend to backend. Depending on the socket types, replies may
|
||||
flow in the opposite direction.
|
||||
The device connects a frontend socket to a backend socket. Conceptually, data flows from frontend to backend. Depending on the socket types, replies may flow in the opposite direction.
|
||||
|
||||
Before calling _zmq_device()_ you must set any socket options, and connect or
|
||||
bind both frontend and backend sockets. The two conventional device models
|
||||
are:
|
||||
Before calling _zmq_device()_ you must set any socket options, and connect or bind both frontend and backend sockets. The two conventional device models are:
|
||||
|
||||
*proxy*::
|
||||
bind frontend socket to an endpoint, and connect backend socket to
|
||||
downstream components. A proxy device model does not require changes to
|
||||
the downstream topology but that topology is static (any changes require
|
||||
reconfiguring the device).
|
||||
bind frontend socket to an endpoint, and connect backend socket to downstream components. A proxy device model does not require changes to the downstream topology but that topology is static (any changes require reconfiguring the device).
|
||||
*broker*::
|
||||
bind frontend socket to one endpoint and bind backend socket to a second
|
||||
endpoint. Downstream components must now connect into the device. A
|
||||
broker device model allows a dynamic downstream topology (components can
|
||||
come and go at any time).
|
||||
bind frontend socket to one endpoint and bind backend socket to a second endpoint. Downstream components must now connect into the device. A broker device model allows a dynamic downstream topology (components can come and go at any time).
|
||||
|
||||
_zmq_device()_ runs in the current thread and returns only if/when the current
|
||||
context is closed.
|
||||
_zmq_device()_ runs in the current thread and returns only if/when the current context is closed.
|
||||
|
||||
|
||||
QUEUE DEVICE
|
||||
------------
|
||||
'ZMQ_QUEUE' creates a shared queue that collects requests from a set of
|
||||
clients, and distributes these fairly among a set of services. Requests are
|
||||
fair-queued from frontend connections and load-balanced between backend
|
||||
connections. Replies automatically return to the client that made the original
|
||||
request.
|
||||
'ZMQ_QUEUE' creates a shared queue that collects requests from a set of clients, and distributes these fairly among a set of services. Requests are fair-queued from frontend connections and load-balanced between backend connections. Replies automatically return to the client that made the original request.
|
||||
|
||||
This device is part of the 'request-reply' pattern. The frontend speaks to
|
||||
clients and the backend speaks to services. You should use 'ZMQ_QUEUE' with a
|
||||
'ZMQ_XREP' socket for the frontend and a 'ZMQ_XREQ' socket for the backend.
|
||||
Other combinations are not documented.
|
||||
This device is part of the 'request-reply' pattern. The frontend speaks to clients and the backend speaks to services. You should use 'ZMQ_QUEUE' with a 'ZMQ_XREP' socket for the frontend and a 'ZMQ_XREQ' socket for the backend. Other combinations are not documented.
|
||||
|
||||
Refer to linkzmq:zmq_socket[3] for a description of these socket types.
|
||||
|
||||
|
||||
FORWARDER DEVICE
|
||||
----------------
|
||||
'ZMQ_FORWARDER' collects messages from a set of publishers and forwards these
|
||||
to a set of subscribers. You will generally use this to bridge networks, e.g.
|
||||
read on TCP unicast and forward on multicast.
|
||||
'ZMQ_FORWARDER' collects messages from a set of publishers and forwards these to a set of subscribers. You will generally use this to bridge networks, e.g. read on TCP unicast and forward on multicast.
|
||||
|
||||
This device is part of the 'publish-subscribe' pattern. The frontend speaks to
|
||||
publishers and the backend speaks to subscribers. You should use
|
||||
'ZMQ_FORWARDER' with a 'ZMQ_SUB' socket for the frontend and a 'ZMQ_PUB' socket
|
||||
for the backend. Other combinations are not documented.
|
||||
This device is part of the 'publish-subscribe' pattern. The frontend speaks to publishers and the backend speaks to subscribers. You should use 'ZMQ_FORWARDER' with a 'ZMQ_SUB' socket for the frontend and a 'ZMQ_PUB' socket for the backend. Other combinations are not documented.
|
||||
|
||||
Refer to linkzmq:zmq_socket[3] for a description of these socket types.
|
||||
|
||||
|
||||
STREAMER DEVICE
|
||||
---------------
|
||||
'ZMQ_STREAMER' collects tasks from a set of pushers and forwards these to a set
|
||||
of pullers. You will generally use this to bridge networks. Messages are
|
||||
fair-queued from pushers and load-balanced to pullers.
|
||||
'ZMQ_STREAMER' collects tasks from a set of pushers and forwards these to a set of pullers. You will generally use this to bridge networks. Messages are fair-queued from pushers and load-balanced to pullers.
|
||||
|
||||
This device is part of the 'pipeline' pattern. The frontend speaks to pushers
|
||||
and the backend speaks to pullers. You should use 'ZMQ_STREAMER' with a
|
||||
'ZMQ_PULL' socket for the frontend and a 'ZMQ_PUSH' socket for the backend.
|
||||
Other combinations are not documented.
|
||||
This device is part of the 'pipeline' pattern. The frontend speaks to pushers and the backend speaks to pullers. You should use 'ZMQ_STREAMER' with a 'ZMQ_PULL' socket for the frontend and a 'ZMQ_PUSH' socket for the backend. Other combinations are not documented.
|
||||
|
||||
Refer to linkzmq:zmq_socket[3] for a description of these socket types.
|
||||
|
||||
|
||||
RETURN VALUE
|
||||
------------
|
||||
<<<<<<< HEAD
|
||||
The _zmq_device()_ function shall not return if successful. Otherwise it shall
|
||||
return `-1` and set 'errno' to one of the values defined below.
|
||||
|
||||
|
||||
ERRORS
|
||||
------
|
||||
*ETERM*::
|
||||
The 0MQ 'context' associated with the specified 'frontend' or 'backend' was
|
||||
terminated.
|
||||
*EFAULT*::
|
||||
The provided 'frontend' or 'backend' was not valid (NULL).
|
||||
The _zmq_device()_ function always returns `-1` and 'errno' set to *ETERM* (the 0MQ 'context' associated with either of the specified sockets was terminated).
|
||||
|
||||
|
||||
EXAMPLE
|
||||
|
||||
@ -14,32 +14,22 @@ SYNOPSIS
|
||||
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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:
|
||||
|
||||
@ -62,28 +52,19 @@ 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].
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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].
|
||||
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].
|
||||
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].
|
||||
binds the frontend or backend to the specified endpoint. See linkzmq:zmq_connect[3].
|
||||
|
||||
SOCKET TYPES
|
||||
------------
|
||||
@ -97,12 +78,9 @@ By default 'zmq_device' uses these socket types:
|
||||
*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].
|
||||
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.
|
||||
*Note*: if you use a *sub* socket you must explicitly set a subscription filter or your socket will not receive any data.
|
||||
|
||||
|
||||
EXAMPLE
|
||||
|
||||
@ -70,7 +70,7 @@ ZMQ_SWAP: Retrieve disk offload size
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The 'ZMQ_SWAP' option shall retrieve the disk offload (swap) size for the
|
||||
specified 'socket'. A socket which has 'ZMQ_SWAP' set to a non-zero value may
|
||||
exceed its high water mark; in this case outstanding messages shall be
|
||||
exceed it's high water mark; in this case outstanding messages shall be
|
||||
offloaded to storage on disk rather than held in memory.
|
||||
|
||||
The value of 'ZMQ_SWAP' defines the maximum size of the swap space in bytes.
|
||||
|
||||
@ -55,7 +55,7 @@ and a port number.
|
||||
An 'interface' may be specified by either of the following:
|
||||
|
||||
* The interface name as defined by the operating system.
|
||||
* The primary IPv4 address assigned to the interface, in its numeric
|
||||
* The primary IPv4 address assigned to the interface, in it's numeric
|
||||
representation.
|
||||
|
||||
NOTE: Interface names are not standardised in any way and should be assumed to
|
||||
@ -63,7 +63,7 @@ be arbitrary and platform dependent. On Win32 platforms no short interface
|
||||
names exist, thus only the primary IPv4 address may be used to specify an
|
||||
'interface'.
|
||||
|
||||
A 'multicast address' is specified by an IPv4 multicast address in its numeric
|
||||
A 'multicast address' is specified by an IPv4 multicast address in it's numeric
|
||||
representation.
|
||||
|
||||
|
||||
|
||||
@ -102,13 +102,13 @@ The provided 'items' was not valid (NULL).
|
||||
|
||||
EXAMPLE
|
||||
-------
|
||||
.Polling indefinitely for input events on both a 0MQ socket and a TCP socket.
|
||||
.Polling indefinitely for input events on both a 0MQ socket and a standard socket.
|
||||
----
|
||||
zmq_pollitem_t items [2];
|
||||
/* First item refers to 0MQ socket 'socket' */
|
||||
items[0].socket = socket;
|
||||
items[0].events = ZMQ_POLLIN;
|
||||
/* Second item refers to TCP socket 'fd' */
|
||||
/* Second item refers to standard socket 'fd' */
|
||||
items[1].socket = NULL;
|
||||
items[1].fd = fd;
|
||||
items[1].events = ZMQ_POLLIN;
|
||||
|
||||
@ -48,7 +48,7 @@ Applicable socket types:: all
|
||||
ZMQ_SWAP: Set disk offload size
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The 'ZMQ_SWAP' option shall set the disk offload (swap) size for the specified
|
||||
'socket'. A socket which has 'ZMQ_SWAP' set to a non-zero value may exceed its
|
||||
'socket'. A socket which has 'ZMQ_SWAP' set to a non-zero value may exceed it's
|
||||
high water mark; in this case outstanding messages shall be offloaded to
|
||||
storage on disk rather than held in memory.
|
||||
|
||||
|
||||
@ -49,15 +49,15 @@ a colon and the TCP port number to use.
|
||||
A 'peer address' may be specified by either of the following:
|
||||
|
||||
* The DNS name of the peer.
|
||||
* The IPv4 address of the peer, in its numeric representation.
|
||||
* The IPv4 address of the peer, in it's numeric representation.
|
||||
|
||||
|
||||
WIRE FORMAT
|
||||
-----------
|
||||
0MQ messages are transmitted over TCP in frames consisting of an encoded
|
||||
'payload length', followed by a 'flags' field and the message body. The
|
||||
'payload length' is defined as the combined length in octets of the message
|
||||
body and the 'flags' field.
|
||||
'payload length', followed by a 'flags' field and the message body. The 'payload
|
||||
length' is defined as the combined length in octets of the message body and the
|
||||
'flags' field.
|
||||
|
||||
For frames with a 'payload length' not exceeding 254 octets, the 'payload
|
||||
length' shall be encoded as a single octet. The minimum valid 'payload length'
|
||||
|
||||
Loading…
Reference in New Issue
Block a user