mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-12 18:40:27 +01:00
67e02ca8bc
contributors and doesn't reflect the real process. I've taken out all named authors and referred to the contribution policy. Hopefully this will improve the contributions to the man pages.
164 lines
5.4 KiB
Plaintext
164 lines
5.4 KiB
Plaintext
zmq_pgm(7)
|
|
==========
|
|
|
|
|
|
NAME
|
|
----
|
|
zmq_pgm - 0MQ reliable multicast transport using PGM
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
PGM (Pragmatic General Multicast) is a protocol for reliable multicast
|
|
transport of data over IP networks.
|
|
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
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 'pgm'
|
|
transport) and "Encapsulated PGM" or EPGM where PGM datagrams are encapsulated
|
|
inside UDP datagrams (the 'epgm' transport).
|
|
|
|
The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and
|
|
'ZMQ_SUB' socket types.
|
|
|
|
Further, PGM sockets are rate limited by default. For details, refer to the
|
|
'ZMQ_RATE', and 'ZMQ_RECOVERY_IVL' options documented in
|
|
linkzmq:zmq_setsockopt[3].
|
|
|
|
CAUTION: The 'pgm' 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 'epgm' transport instead which does
|
|
not require any special privileges.
|
|
|
|
|
|
ADDRESSING
|
|
----------
|
|
A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
|
|
'address'. The 'transport' specifies the underlying protocol to use. The
|
|
'address' specifies the transport-specific address to connect to.
|
|
|
|
For the PGM transport, the transport is `pgm`, and for the EPGM protocol the
|
|
transport is `epgm`. The meaning of the 'address' part is defined below.
|
|
|
|
|
|
Connecting a socket
|
|
~~~~~~~~~~~~~~~~~~~
|
|
When connecting a socket to a peer address using _zmq_connect()_ with the 'pgm'
|
|
or 'epgm' transport, the 'endpoint' shall be interpreted as an 'interface'
|
|
followed by a semicolon, followed by a 'multicast address', followed by a colon
|
|
and a port number.
|
|
|
|
An 'interface' may be specified by either of the following:
|
|
|
|
* The interface name as defined by the operating system.
|
|
* The primary IPv4 address assigned to the interface, in its numeric
|
|
representation.
|
|
|
|
NOTE: 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
|
|
'interface'. The 'interface' part can be omitted, in that case the default one
|
|
will be selected.
|
|
|
|
A 'multicast address' is specified by an IPv4 multicast address in its numeric
|
|
representation.
|
|
|
|
|
|
WIRE FORMAT
|
|
-----------
|
|
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 'frames' as described in
|
|
linkzmq:zmq_tcp[7].
|
|
|
|
|
|
PGM datagram payload
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
The following ABNF grammar represents the payload of a single PGM datagram as
|
|
used by 0MQ:
|
|
|
|
....
|
|
datagram = (offset data)
|
|
offset = 2OCTET
|
|
data = *OCTET
|
|
....
|
|
|
|
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 'frame' in the datagram
|
|
or containing the value `0xFFFF` if the datagram contains solely an
|
|
intermediate part of a larger message.
|
|
|
|
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.
|
|
|
|
The following diagram illustrates the layout of a single PGM datagram payload:
|
|
|
|
....
|
|
+------------------+----------------------+
|
|
| offset (16 bits) | data |
|
|
+------------------+----------------------+
|
|
....
|
|
|
|
The following diagram further illustrates how three example 0MQ frames are laid
|
|
out in consecutive PGM datagram payloads:
|
|
|
|
....
|
|
First datagram payload
|
|
+--------------+-------------+---------------------+
|
|
| Frame offset | Frame 1 | Frame 2, part 1 |
|
|
| 0x0000 | (Message 1) | (Message 2, part 1) |
|
|
+--------------+-------------+---------------------+
|
|
|
|
Second datagram payload
|
|
+--------------+---------------------+
|
|
| Frame offset | Frame 2, part 2 |
|
|
| 0xFFFF | (Message 2, part 2) |
|
|
+--------------+---------------------+
|
|
|
|
Third datagram payload
|
|
+--------------+----------------------------+-------------+
|
|
| Frame offset | Frame 2, final 8 bytes | Frame 3 |
|
|
| 0x0008 | (Message 2, final 8 bytes) | (Message 3) |
|
|
+--------------+----------------------------+-------------+
|
|
....
|
|
|
|
|
|
EXAMPLE
|
|
-------
|
|
.Connecting a socket
|
|
----
|
|
// Connecting to the multicast address 239.192.1.1, port 5555,
|
|
// using the first Ethernet network interface on Linux
|
|
// and the Encapsulated PGM protocol
|
|
rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555");
|
|
assert (rc == 0);
|
|
// Connecting to the multicast address 239.192.1.1, port 5555,
|
|
// using the network interface with the address 192.168.1.1
|
|
// and the standard PGM protocol
|
|
rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
|
|
assert (rc == 0);
|
|
----
|
|
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkzmq:zmq_connect[3]
|
|
linkzmq:zmq_setsockopt[3]
|
|
linkzmq:zmq_tcp[7]
|
|
linkzmq:zmq_ipc[7]
|
|
linkzmq:zmq_inproc[7]
|
|
linkzmq:zmq[7]
|
|
|
|
|
|
AUTHORS
|
|
-------
|
|
This page was written by the 0MQ community. To make a change please
|
|
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.
|