From 06105d164230800e8ea42ddd513e2f7fb27e6f2f Mon Sep 17 00:00:00 2001 From: Martin Sustrik Date: Wed, 13 Jan 2010 15:15:01 +0100 Subject: transports man pages updated --- man/man7/zmq_pgm.7 | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 76 insertions(+), 1 deletion(-) (limited to 'man/man7/zmq_pgm.7') diff --git a/man/man7/zmq_pgm.7 b/man/man7/zmq_pgm.7 index 57af65e..e432730 100644 --- a/man/man7/zmq_pgm.7 +++ b/man/man7/zmq_pgm.7 @@ -2,8 +2,83 @@ .SH NAME PGM-based tranport for 0MQ .SH SYNOPSIS -.SH DESCRIPTION + +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. + +.SH CONNECTION STRING + +Connection string for PGM transport is "pgm://" followed by an IP adress +of the NIC to use, semicolon, IP adress of the multicast group, colon and +port numbrt. 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 +mutlicast group should be specified in the numeric representation. For example: + +.nf + pgm://eth0:224.0.0.1:5555 + pgm://lo:230.0.0.0:6666 + pgm://192.168.0.111:224.0.0.1:5555 +.fi + +.SH 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 +.IR 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: + +.nf ++-----------+------------+------------------+-------- +| IP header | PGM header | offset (16 bits) | data ..... ++-----------+------------+------------------+-------- +.fi + +Following example shows how messages are arranged in subsequent packets: + +.nf ++---------------+--------+-----------+-----------------------------+ +| 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 | ++---------------+--------+--------------------------+-----------+ +.fi + .SH "SEE ALSO" + +.BR zmq_udp (7) +.BR zmq_tcp (7) +.BR zmq_inproc (7) +.BR zmq_setsockopt (3) + .SH AUTHOR Martin Sustrik + -- cgit v1.2.3