mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-13 18:55:10 +01:00
107 lines
3.9 KiB
Plaintext
107 lines
3.9 KiB
Plaintext
zmq_pgm(7)
|
|
==========
|
|
|
|
|
|
NAME
|
|
----
|
|
zmq_pgm - 0MQ PGM reliable multicast transport
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
PGM is a protocol for reliable multicast (RFC3208). 0MQ's PGM transport allows
|
|
you to deliver messages to multiple destinations sending the data over
|
|
the network once only. It makes sense to use PGM transport if the data,
|
|
delivered to each destination separately, would seriously load or even overload
|
|
the network.
|
|
|
|
PGM sending is rate limited rather than controlled by receivers. Thus, to get
|
|
optimal performance you should set ZMQ_RATE and ZMQ_RECOVERY_IVL socket options
|
|
prior to using PGM transport. Also note that passing multicast packets via
|
|
loopback interface has negative effect on the overall performance of the system.
|
|
Thus, if not needed, you should turn multicast loopback off using ZMQ_MCAST_LOOP
|
|
socket option.
|
|
|
|
PGM transport can be used only with ZMQ_PUB and ZMQ_SUB sockets.
|
|
|
|
CAUTION: PGM protocol runs directly on top of IP protocol and thus needs to
|
|
open raw IP socket. On some operating systems this operation requires special
|
|
privileges. On Linux, for example, you would need to either run your application
|
|
as root or set adequate capabilities for your executable. Alternative approach
|
|
is to use UDP transport, linkzmq:zmq_udp[7], that stacks PGM on top of UDP and
|
|
thus needs no special privileges.
|
|
|
|
|
|
CONNECTION STRING
|
|
-----------------
|
|
Connection string for PGM transport is "pgm://" followed by an IP address
|
|
of the NIC to use, semicolon, IP address of the multicast group, colon and
|
|
port number. IP address of the NIC can be either its numeric representation
|
|
or the name of the NIC as reported by operating system. IP address of the
|
|
multicast group should be specified in the numeric representation. For example:
|
|
|
|
----
|
|
pgm://eth0;224.0.0.1:5555
|
|
pgm://lo;230.0.0.0:6666
|
|
pgm://192.168.0.111;224.0.0.1:5555
|
|
----
|
|
|
|
NOTE: NIC names are not standardised by POSIX. They tend to be rather arbitrary
|
|
and platform dependent. Say, "eth0" on Linux would correspond to "en0" on OSX
|
|
and "e1000g" on Solaris. On Windows platform, as there are no short NIC names
|
|
available, you have to use numeric IP addresses instead.
|
|
|
|
|
|
WIRE FORMAT
|
|
-----------
|
|
Consecutive PGM packets are interpreted as a single continuous stream of data.
|
|
The data is then split into messages using the wire format described in
|
|
linkzmq:zmq_tcp[7]. Thus, messages are not aligned with packet boundaries and
|
|
each message can start at an arbitrary position within the packet and span
|
|
several packets.
|
|
|
|
Given this wire format, it would be impossible for late joining consumers to
|
|
identify message boundaries. To solve this problem, each PGM packet payload
|
|
starts with 16-bit unsigned integer in network byte order which specifies the
|
|
offset of the first message in the packet. If there's no beginning of a message
|
|
in the packet (it's a packet transferring inner part of a larger message)
|
|
the value of the initial integer is 0xFFFF.
|
|
|
|
Each packet thus looks like this:
|
|
|
|
----
|
|
+-----------+------------+------------------+--------
|
|
| IP header | PGM header | offset (16 bits) | data .....
|
|
+-----------+------------+------------------+--------
|
|
----
|
|
|
|
Following example shows how messages are arranged in subsequent packets:
|
|
|
|
----
|
|
+---------------+--------+-----------+-----------------------------+
|
|
| PGM/IPheaders | 0x0000 | message 1 | message 2 (part 1) |
|
|
+---------------+--------+-----------+-----------------------------+
|
|
|
|
+---------------+--------+-----------------------------------------+
|
|
| PGM/IPheaders | 0xFFFF | message 2 (part 2) |
|
|
+---------------+--------+-----------------------------------------+
|
|
|
|
+---------------+--------+--------------------------+-----------+
|
|
| PGM/IPheaders | 0x0008 | message 2 (last 8 bytes) | message 3 |
|
|
+---------------+--------+--------------------------+-----------+
|
|
----
|
|
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkzmq:zmq_udp[7]
|
|
linkzmq:zmq_tcp[7]
|
|
linkzmq:zmq_ipc[7]
|
|
linkzmq:zmq_inproc[7]
|
|
linkzmq:zmq_setsockopt[3]
|
|
|
|
|
|
AUTHOR
|
|
------
|
|
Martin Sustrik <sustrik at 250bpm dot com>
|