zmq_pgm.txt 5.39 KB
Newer Older
1 2
zmq_pgm(7)
==========
3

4 5 6

NAME
----
Martin Lucina's avatar
Martin Lucina committed
7
zmq_pgm - 0MQ reliable multicast transport using PGM
8 9 10 11


SYNOPSIS
--------
Martin Lucina's avatar
Martin Lucina committed
12 13
PGM (Pragmatic General Multicast) is a protocol for reliable multicast
transport of data over IP networks.
14 15


Martin Lucina's avatar
Martin Lucina committed
16 17 18 19
DESCRIPTION
-----------
0MQ implements two variants of PGM, the standard protocol where PGM datagrams
are layered directly on top of IP datagrams as defined by RFC 3208 (the 'pgm'
Pieter Hintjens's avatar
Pieter Hintjens committed
20 21
transport) and "Encapsulated PGM" or EPGM where PGM datagrams are encapsulated
inside UDP datagrams (the 'epgm' transport).
22

Martin Lucina's avatar
Martin Lucina committed
23 24
The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and
'ZMQ_SUB' socket types.
25

Martin Sustrik's avatar
Martin Sustrik committed
26 27
Further, PGM sockets are rate limited by default. For details, refer to the
'ZMQ_RATE', and 'ZMQ_RECOVERY_IVL' options documented in
Martin Lucina's avatar
Martin Lucina committed
28
linkzmq:zmq_setsockopt[3].
29

Martin Lucina's avatar
Martin Lucina committed
30 31 32 33 34
CAUTION: The 'pgm' transport implementation requires access to raw IP sockets.
Additional privileges may be required on some operating systems for this
operation. Applications not requiring direct interoperability with other PGM
implementations are encouraged to use the 'epgm' transport instead which does
not require any special privileges.
35 36


Martin Lucina's avatar
Martin Lucina committed
37 38
ADDRESSING
----------
Pieter Hintjens's avatar
Pieter Hintjens committed
39 40 41 42 43 44
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
'address'. The 'transport' specifies the underlying protocol to use. The
'address' specifies the transport-specific address to connect to.

For the PGM transport, the transport is `pgm`, and for the EPGM protocol the
transport is `epgm`. The meaning of the 'address' part is defined below.
45 46


Martin Lucina's avatar
Martin Lucina committed
47 48 49 50 51 52 53 54
Connecting a socket
~~~~~~~~~~~~~~~~~~~
When connecting a socket to a peer address using _zmq_connect()_ with the 'pgm'
or 'epgm' transport, the 'endpoint' shall be interpreted as an 'interface'
followed by a semicolon, followed by a 'multicast address', followed by a colon
and a port number.

An 'interface' may be specified by either of the following:
55

Martin Lucina's avatar
Martin Lucina committed
56
* The interface name as defined by the operating system.
Pieter Hintjens's avatar
Pieter Hintjens committed
57
* The primary IPv4 address assigned to the interface, in its numeric
Martin Lucina's avatar
Martin Lucina committed
58
  representation.
59

Martin Lucina's avatar
Martin Lucina committed
60 61 62
NOTE: Interface names are not standardised in any way and should be assumed to
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
63 64
'interface'. The 'interface' part can be omitted, in that case the default one
will be selected.
Martin Lucina's avatar
Martin Lucina committed
65

Pieter Hintjens's avatar
Pieter Hintjens committed
66
A 'multicast address' is specified by an IPv4 multicast address in its numeric
Martin Lucina's avatar
Martin Lucina committed
67 68 69 70 71
representation.


WIRE FORMAT
-----------
72
Consecutive PGM datagrams are interpreted by 0MQ as a single continuous stream
Martin Lucina's avatar
Martin Lucina committed
73 74 75 76 77
of data where 0MQ messages are not necessarily aligned with PGM datagram
boundaries and a single 0MQ message may span several PGM datagrams. This stream
of data consists of 0MQ messages encapsulated in 'frames' as described in
linkzmq:zmq_tcp[7].

78 79 80 81 82 83 84 85 86 87 88 89

PGM datagram payload
~~~~~~~~~~~~~~~~~~~~
The following ABNF grammar represents the payload of a single PGM datagram as
used by 0MQ:

....
datagram               = (offset data)
offset                 = 2OCTET
data                   = *OCTET
....

Martin Lucina's avatar
Martin Lucina committed
90 91 92
In order for late joining consumers to be able to identify message boundaries,
each PGM datagram payload starts with a 16-bit unsigned integer in network byte
order specifying either the offset of the first message 'frame' in the datagram
93 94
or containing the value `0xFFFF` if the datagram contains solely an
intermediate part of a larger message.
Martin Lucina's avatar
Martin Lucina committed
95

96 97 98 99 100
Note that offset specifies where the first message begins rather than the first
message part. Thus, if there are trailing message parts at the beginning of
the packet the offset ignores them and points to first initial message part
in the packet.

101
The following diagram illustrates the layout of a single PGM datagram payload:
Martin Lucina's avatar
Martin Lucina committed
102 103

....
104 105 106
+------------------+----------------------+
| offset (16 bits) |         data         |
+------------------+----------------------+
Martin Lucina's avatar
Martin Lucina committed
107 108
....

109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130
The following diagram further illustrates how three example 0MQ frames are laid
out in consecutive PGM datagram payloads:

....
First datagram payload
+--------------+-------------+---------------------+
| Frame offset |   Frame 1   |   Frame 2, part 1   |
|    0x0000    | (Message 1) | (Message 2, part 1) |
+--------------+-------------+---------------------+

Second datagram payload
+--------------+---------------------+
| Frame offset |   Frame 2, part 2   |
| 0xFFFF       | (Message 2, part 2) |
+--------------+---------------------+

Third datagram payload
+--------------+----------------------------+-------------+
| Frame offset |   Frame 2, final 8 bytes   |   Frame 3   |
| 0x0008       | (Message 2, final 8 bytes) | (Message 3) |
+--------------+----------------------------+-------------+
....
Martin Lucina's avatar
Martin Lucina committed
131 132 133 134 135 136


EXAMPLE
-------
.Connecting a socket
----
Pieter Hintjens's avatar
Pieter Hintjens committed
137 138 139
//  Connecting to the multicast address 239.192.1.1, port 5555,
//  using the first Ethernet network interface on Linux
//  and the Encapsulated PGM protocol
Martin Lucina's avatar
Martin Lucina committed
140 141
rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555");
assert (rc == 0);
Pieter Hintjens's avatar
Pieter Hintjens committed
142 143 144
//  Connecting to the multicast address 239.192.1.1, port 5555,
//  using the network interface with the address 192.168.1.1
//  and the standard PGM protocol
Martin Lucina's avatar
Martin Lucina committed
145 146
rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
assert (rc == 0);
147
----
148 149


150 151
SEE ALSO
--------
Martin Lucina's avatar
Martin Lucina committed
152 153
linkzmq:zmq_connect[3]
linkzmq:zmq_setsockopt[3]
154 155 156
linkzmq:zmq_tcp[7]
linkzmq:zmq_ipc[7]
linkzmq:zmq_inproc[7]
Ilya Kulakov's avatar
Ilya Kulakov committed
157
linkzmq:zmq_vmci[7]
Martin Lucina's avatar
Martin Lucina committed
158
linkzmq:zmq[7]
159

160

161 162
AUTHORS
-------
163 164
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.