From 8e61b98c5e2943b149c825310b24e714a6127072 Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Mon, 23 Jan 2012 08:53:41 +0100 Subject: Imported Upstream version 2.1.4 --- doc/zmq_pgm.html | 745 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 745 insertions(+) create mode 100644 doc/zmq_pgm.html (limited to 'doc/zmq_pgm.html') diff --git a/doc/zmq_pgm.html b/doc/zmq_pgm.html new file mode 100644 index 0000000..5506fa1 --- /dev/null +++ b/doc/zmq_pgm.html @@ -0,0 +1,745 @@ + + + + + +zmq_pgm(7) + + + + + +
+

SYNOPSIS

+
+

PGM (Pragmatic General Multicast) is a protocol for reliable multicast +transport of data over IP networks.

+
+

DESCRIPTION

+
+

ØMQ 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 loop-back interface. For details, refer to the +ZMQ_RATE, ZMQ_RECOVERY_IVL and ZMQ_MCAST_LOOP options documented in +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 ØMQ 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 ØMQ as a single continuous stream +of data where ØMQ messages are not necessarily aligned with PGM datagram +boundaries and a single ØMQ message may span several PGM datagrams. This stream +of data consists of ØMQ messages encapsulated in frames as described in +zmq_tcp(7).

+

PGM datagram payload

+

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

+
+
+
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 ØMQ 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

+
+

zmq_connect(3) +zmq_setsockopt(3) +zmq_tcp(7) +zmq_ipc(7) +zmq_inproc(7) +zmq(7)

+
+

AUTHORS

+
+

This ØMQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and +Martin Lucina <mato@kotelna.sk>.

+
+
+
+ + + -- cgit v1.2.3