xs_pgm(7)
=========


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
linkxs: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
linkxs: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
--------
linkxs:xs_connect[3]
linkxs:xs_setsockopt[3]
linkxs:xs_tcp[7]
linkxs:xs_ipc[7]
linkxs:xs_inproc[7]
linkxs:xs[7]

AUTHORS
-------
The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com>
and Martin Lucina <martin@lucina.net>.
