From 354efc513fdb4096f8830e6c2e3e8f1311303e61 Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Wed, 10 Feb 2010 16:18:46 +0100 Subject: Convert documentation to AsciiDoc --- doc/zmq_pgm.txt | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 doc/zmq_pgm.txt (limited to 'doc/zmq_pgm.txt') diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt new file mode 100644 index 0000000..d0e2622 --- /dev/null +++ b/doc/zmq_pgm.txt @@ -0,0 +1,106 @@ +zmq_pgm(7) +========== + + +NAME +---- +zmq_pgm - 0MQ PGM reliable multicast transport + + +SYNOPSIS +-------- +PGM is a protocol for reliable multicast (RFC3208). 0MQ's PGM transport allows +you to deliver messages to multiple destinations sending the data over +the network once only. It makes sense to use PGM transport if the data, +delivered to each destination separately, would seriously load or even overload +the network. + +PGM sending is rate limited rather than controlled by receivers. Thus, to get +optimal performance you should set ZMQ_RATE and ZMQ_RECOVERY_IVL socket options +prior to using PGM transport. Also note that passing multicast packets via +loopback interface has negative effect on the overall performance of the system. +Thus, if not needed, you should turn multicast loopback off using ZMQ_MCAST_LOOP +socket option. + +PGM transport can be used only with ZMQ_PUB and ZMQ_SUB sockets. + +CAUTION: PGM protocol runs directly on top of IP protocol and thus needs to +open raw IP socket. On some operating systems this operation requires special +privileges. On Linux, for example, you would need to either run your application +as root or set adequate capabilities for your executable. Alternative approach +is to use UDP transport, linkzmq:zmq_udp[7], that stacks PGM on top of UDP and +thus needs no special privileges. + + +CONNECTION STRING +----------------- +Connection string for PGM transport is "pgm://" followed by an IP address +of the NIC to use, semicolon, IP address of the multicast group, colon and +port number. IP address of the NIC can be either its numeric representation +or the name of the NIC as reported by operating system. IP address of the +multicast group should be specified in the numeric representation. For example: + +---- + pgm://eth0;224.0.0.1:5555 + pgm://lo;230.0.0.0:6666 + pgm://192.168.0.111;224.0.0.1:5555 +---- + +NOTE: NIC names are not standardised by POSIX. They tend to be rather arbitrary +and platform dependent. Say, "eth0" on Linux would correspond to "en0" on OSX +and "e1000g" on Solaris. On Windows platform, as there are no short NIC names +available, you have to use numeric IP addresses instead. + + +WIRE FORMAT +----------- +Consecutive PGM packets are interpreted as a single continuous stream of data. +The data is then split into messages using the wire format described in +linkzmq:zmq_tcp[7]. Thus, messages are not aligned with packet boundaries and +each message can start at an arbitrary position within the packet and span +several packets. + +Given this wire format, it would be impossible for late joining consumers to +identify message boundaries. To solve this problem, each PGM packet payload +starts with 16-bit unsigned integer in network byte order which specifies the +offset of the first message in the packet. If there's no beginning of a message +in the packet (it's a packet transferring inner part of a larger message) +the value of the initial integer is 0xFFFF. + +Each packet thus looks like this: + +---- ++-----------+------------+------------------+-------- +| IP header | PGM header | offset (16 bits) | data ..... ++-----------+------------+------------------+-------- +---- + +Following example shows how messages are arranged in subsequent packets: + +---- ++---------------+--------+-----------+-----------------------------+ +| PGM/IPheaders | 0x0000 | message 1 | message 2 (part 1) | ++---------------+--------+-----------+-----------------------------+ + ++---------------+--------+-----------------------------------------+ +| PGM/IPheaders | 0xFFFF | message 2 (part 2) | ++---------------+--------+-----------------------------------------+ + ++---------------+--------+--------------------------+-----------+ +| PGM/IPheaders | 0x0008 | message 2 (last 8 bytes) | message 3 | ++---------------+--------+--------------------------+-----------+ +---- + + +SEE ALSO +-------- +linkzmq:zmq_udp[7] +linkzmq:zmq_tcp[7] +linkzmq:zmq_ipc[7] +linkzmq:zmq_inproc[7] +linkzmq:zmq_setsockopt[3] + + +AUTHOR +------ +Martin Sustrik -- cgit v1.2.3