NAME

       xs_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 ALSO

       xs_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                               06/13/2012                                          XS_PGM(7)