summaryrefslogtreecommitdiff
path: root/man/man7/zmq_pgm.7
blob: fb37735d0abbc4165a0cc00b5c4d8689d20b28dc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
.TH zmq_pgm 7 "" "(c)2007-2010 iMatix Corporation" "0MQ User Manuals"
.SH NAME
PGM-based transport for 0MQ
.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.

.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>