diff options
Diffstat (limited to 'doc/zmq_epgm.txt')
| -rw-r--r-- | doc/zmq_epgm.txt | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/doc/zmq_epgm.txt b/doc/zmq_epgm.txt new file mode 100644 index 0000000..4017db2 --- /dev/null +++ b/doc/zmq_epgm.txt @@ -0,0 +1,157 @@ +zmq_pgm(7) +========== + + +NAME +---- +zmq_pgm - 0MQ reliable multicast transport using PGM + + +SYNOPSIS +-------- +PGM (Pragmatic General Multicast) is a protocol for reliable multicast +transport of data over IP networks. + + +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' +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 'ZMQ_PUB' and +'ZMQ_SUB' socket types. + +Further, PGM sockets are rate limited by default and incur a performance +penalty when used over a loopback interface. For details, refer to the +'ZMQ_RATE', 'ZMQ_RECOVERY_IVL' and 'ZMQ_MCAST_LOOP' options documented in +linkzmq:zmq_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 0MQ 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 _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: + +* 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 0MQ as a single continous stream +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]. + + +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 +.... + +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. + +The following diagram illustrates the layout of a single PGM datagram payload: + +.... ++------------------+----------------------+ +| offset (16 bits) | data | ++------------------+----------------------+ +.... + +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) | ++--------------+----------------------------+-------------+ +.... + + +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 = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555"); +assert (rc == 0); +/* 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 = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555"); +assert (rc == 0); +---- + + +SEE ALSO +-------- +linkzmq:zmq_connect[3] +linkzmq:zmq_setsockopt[3] +linkzmq:zmq_tcp[7] +linkzmq:zmq_ipc[7] +linkzmq:zmq_inproc[7] +linkzmq:zmq[7] + +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>. |