7
zmq_pgm - 0MQ reliable multicast transport using PGM
12
PGM (Pragmatic General Multicast) is a protocol for reliable multicast
13
transport of data over IP networks.
18
0MQ implements two variants of PGM, the standard protocol where PGM datagrams
19
are layered directly on top of IP datagrams as defined by RFC 3208 (the 'pgm'
20
transport) and "Encapsulated PGM" where PGM datagrams are encapsulated inside
21
UDP datagrams (the 'epgm' transport).
23
The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and
24
'ZMQ_SUB' socket types.
26
Further, PGM sockets are rate limited by default. For details, refer to the
27
'ZMQ_RATE', and 'ZMQ_RECOVERY_IVL' options documented in
28
linkzmq:zmq_setsockopt[3].
30
CAUTION: The 'pgm' transport implementation requires access to raw IP sockets.
31
Additional privileges may be required on some operating systems for this
32
operation. Applications not requiring direct interoperability with other PGM
33
implementations are encouraged to use the 'epgm' transport instead which does
34
not require any special privileges.
39
A 0MQ address string consists of two parts as follows:
40
'transport'`://`'endpoint'. The 'transport' part specifies the underlying
41
transport protocol to use. For the standard PGM protocol, 'transport' shall be
42
set to `pgm`. For the "Encapsulated PGM" protocol 'transport' shall be set to
43
`epgm`. The meaning of the 'endpoint' part for both the 'pgm' and 'epgm'
44
transport is defined below.
49
When connecting a socket to a peer address using _zmq_connect()_ with the 'pgm'
50
or 'epgm' transport, the 'endpoint' shall be interpreted as an 'interface'
51
followed by a semicolon, followed by a 'multicast address', followed by a colon
54
An 'interface' may be specified by either of the following:
56
* The interface name as defined by the operating system.
57
* The primary IPv4 address assigned to the interface, in it's numeric
60
NOTE: Interface names are not standardised in any way and should be assumed to
61
be arbitrary and platform dependent. On Win32 platforms no short interface
62
names exist, thus only the primary IPv4 address may be used to specify an
65
A 'multicast address' is specified by an IPv4 multicast address in it's numeric
71
Consecutive PGM datagrams are interpreted by 0MQ as a single continuous stream
72
of data where 0MQ messages are not necessarily aligned with PGM datagram
73
boundaries and a single 0MQ message may span several PGM datagrams. This stream
74
of data consists of 0MQ messages encapsulated in 'frames' as described in
80
The following ABNF grammar represents the payload of a single PGM datagram as
84
datagram = (offset data)
89
In order for late joining consumers to be able to identify message boundaries,
90
each PGM datagram payload starts with a 16-bit unsigned integer in network byte
91
order specifying either the offset of the first message 'frame' in the datagram
92
or containing the value `0xFFFF` if the datagram contains solely an
93
intermediate part of a larger message.
95
Note that offset specifies where the first message begins rather than the first
96
message part. Thus, if there are trailing message parts at the beginning of
97
the packet the offset ignores them and points to first initial message part
100
The following diagram illustrates the layout of a single PGM datagram payload:
103
+------------------+----------------------+
104
| offset (16 bits) | data |
105
+------------------+----------------------+
108
The following diagram further illustrates how three example 0MQ frames are laid
109
out in consecutive PGM datagram payloads:
112
First datagram payload
113
+--------------+-------------+---------------------+
114
| Frame offset | Frame 1 | Frame 2, part 1 |
115
| 0x0000 | (Message 1) | (Message 2, part 1) |
116
+--------------+-------------+---------------------+
118
Second datagram payload
119
+--------------+---------------------+
120
| Frame offset | Frame 2, part 2 |
121
| 0xFFFF | (Message 2, part 2) |
122
+--------------+---------------------+
124
Third datagram payload
125
+--------------+----------------------------+-------------+
126
| Frame offset | Frame 2, final 8 bytes | Frame 3 |
127
| 0x0008 | (Message 2, final 8 bytes) | (Message 3) |
128
+--------------+----------------------------+-------------+
136
/* Connecting to the multicast address 239.192.1.1, port 5555, */
137
/* using the first Ethernet network interface on Linux */
138
/* and the Encapsulated PGM protocol */
139
rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555");
141
/* Connecting to the multicast address 239.192.1.1, port 5555, */
142
/* using the network interface with the address 192.168.1.1 */
143
/* and the standard PGM protocol */
144
rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
151
linkzmq:zmq_connect[3]
152
linkzmq:zmq_setsockopt[3]
155
linkzmq:zmq_inproc[7]
160
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
161
Martin Lucina <martin@lucina.net>.
added
removed
doc/zmq_epgm.txt
