XS_PGM(7) Crossroads I/O Manual XS_PGM(7)NAMExs_pgm - reliable multicast transport via PGM protocol
SYNOPSIS
PGM (Pragmatic General Multicast) is a protocol for reliable multicast
transport of data over IP networks.
DESCRIPTION
Crossroads implement 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 transport) and "Encapsulated PGM" where PGM datagrams
are encapsulated inside UDP datagrams (the epgm transport).
The pgm and epgm transports can only be used with the XS_PUB and XS_SUB
socket types.
Further, PGM sockets are rate limited by default. For details, refer to
the XS_RATE, and XS_RECOVERY_IVL options documented in
xs_setsockopt(3).
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.
ADDRESSING
A Crossroads address string consists of two parts as follows:
transport://endpoint. The transport part specifies the underlying
transport protocol to use. For the standard PGM protocol, transport
shall be set to pgm. For the "Encapsulated PGM" protocol transport
shall be set to epgm. The meaning of the endpoint part for both the pgm
and epgm transport is defined below.
Connecting a socket
When connecting a socket to a peer address using xs_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:
· The interface name as defined by the operating system.
· 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 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 it’s
numeric representation.
WIRE FORMAT
Consecutive PGM datagrams are interpreted by the library as a single
continuous stream of data where messages are not necessarily aligned
with PGM datagram boundaries and a single message may span several PGM
datagrams. This stream of data consists of Crossroads messages
encapsulated in frames as described in xs_tcp(7).
PGM datagram payload
The following ABNF grammar represents the payload of a single PGM
datagram as used by Crossroads:
datagram = (offset data)
offset = 2OCTET
data = *OCTET
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 or containing the value 0xFFFF if the
datagram contains solely an intermediate part of a larger message.
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.
The following diagram illustrates the layout of a single PGM datagram
payload:
+------------------+----------------------+
| offset (16 bits) | data |
+------------------+----------------------+
The following diagram further illustrates how three example Crossroads
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) |
+--------------+----------------------------+-------------+
EXAMPLE
Connecting a socket.
/* Connecting to the multicast address 239.192.1.1, port 5555, */
/* using the first Ethernet network interface on Linux */
/* and the Encapsulated PGM protocol */
rc = xs_connect(socket, "epgm://eth0;239.192.1.1:5555");
assert (rc != -1);
/* 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 */
rc = xs_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
assert (rc != -1);
SEE ALSOxs_connect(3)xs_setsockopt(3)xs_tcp(7)xs_ipc(7)xs_inproc(7)xs(7)AUTHORS
The Crossroads documentation was written by Martin Sustrik
<sustrik@250bpm.com[1]> and Martin Lucina <martin@lucina.net[2]>.
NOTES
1. sustrik@250bpm.com
mailto:sustrik@250bpm.com
2. martin@lucina.net
mailto:martin@lucina.net
Crossroads I/O 1.2.0 02/17/2016 XS_PGM(7)
