From 597cc5edd624525563e6549dc0057eca2a51c81d Mon Sep 17 00:00:00 2001 From: Micah Anderson Date: Tue, 11 Nov 2014 13:30:46 -0500 Subject: upgrade to new version --- doc/zmq_pgm.html | 932 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 932 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..523ca61 --- /dev/null +++ b/doc/zmq_pgm.html @@ -0,0 +1,932 @@ + + + + + +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" or EPGM 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. For details, refer to the +ZMQ_RATE, and ZMQ_RECOVERY_IVL 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 endpoint is a string consisting of a transport:// followed by an +address. The transport specifies the underlying protocol to use. The +address specifies the transport-specific address to connect to.

+

For the PGM transport, the transport is pgm, and for the EPGM protocol the +transport is epgm. The meaning of the address part 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 its 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. The interface part can be omitted, in that case the default one +will be selected.
+
+

A multicast address is specified by an IPv4 multicast address in its 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.

+

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 Ø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 page was written by the ØMQ community. To make a change please +read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

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