~ubuntu-branches/ubuntu/saucy/zeromq3/saucy

« back to all changes in this revision

Viewing changes to doc/zmq_epgm.7

  • Committer: Package Import Robot
  • Author(s): Alessandro Ghedini
  • Date: 2012-06-04 21:21:09 UTC
  • Revision ID: package-import@ubuntu.com-20120604212109-b7b3m0rn21o8oo2q
Tags: upstream-3.1.0~beta+dfsg
ImportĀ upstreamĀ versionĀ 3.1.0~beta+dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
'\" t
 
2
.\"     Title: zmq_pgm
 
3
.\"    Author: [see the "AUTHORS" section]
 
4
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
 
5
.\"      Date: 12/18/2011
 
6
.\"    Manual: 0MQ Manual
 
7
.\"    Source: 0MQ 3.1.0
 
8
.\"  Language: English
 
9
.\"
 
10
.TH "ZMQ_PGM" "7" "12/18/2011" "0MQ 3\&.1\&.0" "0MQ Manual"
 
11
.\" -----------------------------------------------------------------
 
12
.\" * Define some portability stuff
 
13
.\" -----------------------------------------------------------------
 
14
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
15
.\" http://bugs.debian.org/507673
 
16
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
 
17
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
18
.ie \n(.g .ds Aq \(aq
 
19
.el       .ds Aq '
 
20
.\" -----------------------------------------------------------------
 
21
.\" * set default formatting
 
22
.\" -----------------------------------------------------------------
 
23
.\" disable hyphenation
 
24
.nh
 
25
.\" disable justification (adjust text to left margin only)
 
26
.ad l
 
27
.\" -----------------------------------------------------------------
 
28
.\" * MAIN CONTENT STARTS HERE *
 
29
.\" -----------------------------------------------------------------
 
30
.SH "NAME"
 
31
zmq_pgm \- 0MQ reliable multicast transport using PGM
 
32
.SH "SYNOPSIS"
 
33
.sp
 
34
PGM (Pragmatic General Multicast) is a protocol for reliable multicast transport of data over IP networks\&.
 
35
.SH "DESCRIPTION"
 
36
.sp
 
37
0MQ 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 \fIpgm\fR transport) and "Encapsulated PGM" where PGM datagrams are encapsulated inside UDP datagrams (the \fIepgm\fR transport)\&.
 
38
.sp
 
39
The \fIpgm\fR and \fIepgm\fR transports can only be used with the \fIZMQ_PUB\fR and \fIZMQ_SUB\fR socket types\&.
 
40
.sp
 
41
Further, PGM sockets are rate limited by default\&. For details, refer to the \fIZMQ_RATE\fR, and \fIZMQ_RECOVERY_IVL\fR options documented in \fBzmq_setsockopt\fR(3)\&.
 
42
.if n \{\
 
43
.sp
 
44
.\}
 
45
.RS 4
 
46
.it 1 an-trap
 
47
.nr an-no-space-flag 1
 
48
.nr an-break-flag 1
 
49
.br
 
50
.ps +1
 
51
\fBCaution\fR
 
52
.ps -1
 
53
.br
 
54
.sp
 
55
The \fIpgm\fR 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 \fIepgm\fR transport instead which does not require any special privileges\&.
 
56
.sp .5v
 
57
.RE
 
58
.SH "ADDRESSING"
 
59
.sp
 
60
A 0MQ address string consists of two parts as follows: \fItransport\fR://\fIendpoint\fR\&. The \fItransport\fR part specifies the underlying transport protocol to use\&. For the standard PGM protocol, \fItransport\fR shall be set to pgm\&. For the "Encapsulated PGM" protocol \fItransport\fR shall be set to epgm\&. The meaning of the \fIendpoint\fR part for both the \fIpgm\fR and \fIepgm\fR transport is defined below\&.
 
61
.SS "Connecting a socket"
 
62
.sp
 
63
When connecting a socket to a peer address using \fIzmq_connect()\fR with the \fIpgm\fR or \fIepgm\fR transport, the \fIendpoint\fR shall be interpreted as an \fIinterface\fR followed by a semicolon, followed by a \fImulticast address\fR, followed by a colon and a port number\&.
 
64
.sp
 
65
An \fIinterface\fR may be specified by either of the following:
 
66
.sp
 
67
.RS 4
 
68
.ie n \{\
 
69
\h'-04'\(bu\h'+03'\c
 
70
.\}
 
71
.el \{\
 
72
.sp -1
 
73
.IP \(bu 2.3
 
74
.\}
 
75
The interface name as defined by the operating system\&.
 
76
.RE
 
77
.sp
 
78
.RS 4
 
79
.ie n \{\
 
80
\h'-04'\(bu\h'+03'\c
 
81
.\}
 
82
.el \{\
 
83
.sp -1
 
84
.IP \(bu 2.3
 
85
.\}
 
86
The primary IPv4 address assigned to the interface, in it\(cqs numeric representation\&.
 
87
.RE
 
88
.if n \{\
 
89
.sp
 
90
.\}
 
91
.RS 4
 
92
.it 1 an-trap
 
93
.nr an-no-space-flag 1
 
94
.nr an-break-flag 1
 
95
.br
 
96
.ps +1
 
97
\fBNote\fR
 
98
.ps -1
 
99
.br
 
100
.sp
 
101
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 \fIinterface\fR\&.
 
102
.sp .5v
 
103
.RE
 
104
.sp
 
105
A \fImulticast address\fR is specified by an IPv4 multicast address in it\(cqs numeric representation\&.
 
106
.SH "WIRE FORMAT"
 
107
.sp
 
108
Consecutive PGM datagrams are interpreted by 0MQ as a single continuous stream of data where 0MQ messages are not necessarily aligned with PGM datagram boundaries and a single 0MQ message may span several PGM datagrams\&. This stream of data consists of 0MQ messages encapsulated in \fIframes\fR as described in \fBzmq_tcp\fR(7)\&.
 
109
.SS "PGM datagram payload"
 
110
.sp
 
111
The following ABNF grammar represents the payload of a single PGM datagram as used by 0MQ:
 
112
.sp
 
113
.if n \{\
 
114
.RS 4
 
115
.\}
 
116
.nf
 
117
datagram               = (offset data)
 
118
offset                 = 2OCTET
 
119
data                   = *OCTET
 
120
.fi
 
121
.if n \{\
 
122
.RE
 
123
.\}
 
124
.sp
 
125
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 \fIframe\fR in the datagram or containing the value 0xFFFF if the datagram contains solely an intermediate part of a larger message\&.
 
126
.sp
 
127
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\&.
 
128
.sp
 
129
The following diagram illustrates the layout of a single PGM datagram payload:
 
130
.sp
 
131
.if n \{\
 
132
.RS 4
 
133
.\}
 
134
.nf
 
135
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 
136
| offset (16 bits) |         data         |
 
137
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 
138
.fi
 
139
.if n \{\
 
140
.RE
 
141
.\}
 
142
.sp
 
143
The following diagram further illustrates how three example 0MQ frames are laid out in consecutive PGM datagram payloads:
 
144
.sp
 
145
.if n \{\
 
146
.RS 4
 
147
.\}
 
148
.nf
 
149
First datagram payload
 
150
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 
151
| Frame offset |   Frame 1   |   Frame 2, part 1   |
 
152
|    0x0000    | (Message 1) | (Message 2, part 1) |
 
153
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 
154
 
 
155
Second datagram payload
 
156
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 
157
| Frame offset |   Frame 2, part 2   |
 
158
| 0xFFFF       | (Message 2, part 2) |
 
159
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 
160
 
 
161
Third datagram payload
 
162
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+
 
163
| Frame offset |   Frame 2, final 8 bytes   |   Frame 3   |
 
164
| 0x0008       | (Message 2, final 8 bytes) | (Message 3) |
 
165
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+
 
166
.fi
 
167
.if n \{\
 
168
.RE
 
169
.\}
 
170
.SH "EXAMPLE"
 
171
.PP
 
172
\fBConnecting a socket\fR. 
 
173
.sp
 
174
.if n \{\
 
175
.RS 4
 
176
.\}
 
177
.nf
 
178
/* Connecting to the multicast address 239\&.192\&.1\&.1, port 5555, */
 
179
/* using the first Ethernet network interface on Linux */
 
180
/* and the Encapsulated PGM protocol */
 
181
rc = zmq_connect(socket, "epgm://eth0;239\&.192\&.1\&.1:5555");
 
182
assert (rc == 0);
 
183
/* Connecting to the multicast address 239\&.192\&.1\&.1, port 5555, */
 
184
/* using the network interface with the address 192\&.168\&.1\&.1 */
 
185
/* and the standard PGM protocol */
 
186
rc = zmq_connect(socket, "pgm://192\&.168\&.1\&.1;239\&.192\&.1\&.1:5555");
 
187
assert (rc == 0);
 
188
.fi
 
189
.if n \{\
 
190
.RE
 
191
.\}
 
192
.sp
 
193
.SH "SEE ALSO"
 
194
.sp
 
195
\fBzmq_connect\fR(3) \fBzmq_setsockopt\fR(3) \fBzmq_tcp\fR(7) \fBzmq_ipc\fR(7) \fBzmq_inproc\fR(7) \fBzmq\fR(7)
 
196
.SH "AUTHORS"
 
197
.sp
 
198
The 0MQ documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmartin@lucina\&.net\fR\m[]\&\s-2\u[2]\d\s+2>\&.
 
199
.SH "NOTES"
 
200
.IP " 1." 4
 
201
sustrik@250bpm.com
 
202
.RS 4
 
203
\%mailto:sustrik@250bpm.com
 
204
.RE
 
205
.IP " 2." 4
 
206
martin@lucina.net
 
207
.RS 4
 
208
\%mailto:martin@lucina.net
 
209
.RE