libzmq/man/man7/zmq_pgm.7
2010-01-22 11:21:28 +01:00

99 lines
3.9 KiB
Groff

.TH zmq_pgm 7 "" "(c)2007-2010 iMatix Corporation" "0MQ User Manuals"
.SH NAME
0MQ PGM Transport \- reliable multicast transport
.SH 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,
.IR zmq_udp(7) ,
that stacks PGM on top of UDP and thus needs no special privileges.
.SH 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:
.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
Note that 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.
.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_ipc (7)
.BR zmq_inproc (7)
.BR zmq_setsockopt (3)
.SH AUTHOR
Martin Sustrik <sustrik at 250bpm dot com>