1. Unicast transmission using TCP: zmq_tcp(7)
1.1 Name
zmq_tcp - ZMQ unicast transport using TCP
1.2 Overview
TCP is a ubiquitous, reliable unicast transport. When connecting distributed applications over a network with ZMQ, using the TCP transport may be your first choice.
1.3 Solution
A ZMQ endpoint is a string consisting of transport:// followed by an address. transport specifies the underlying protocol to use. The address specifies the transport-specific address to connect to.
For TCP transport, the transport is tcp, and the meaning of the address part is defined as follows.
1.3.1 Assigning a local address to a socket
When a socket-local address is assigned to a socket using zmq_bind() with tcp transport, the endpoint is interpreted as an interface followed by a colon and the TCP port number to use.
An interface can be specified by any of the following:
The wildcard * means all available interfaces.
The primary IPv4 or IPv6 address assigned to the interface, in its numerical representation.
The operating system-defined non-portable interface name.
The TCP port number can be specified in the following ways:
A number, usually over 1024 on POSIX systems.
The wildcard * represents a system-assigned ephemeral port.
When using ephemeral ports, the caller should use the ZMQ_LAST_ENDPOINT socket option to retrieve the actual allocated port. See zmq_getsockopt(3) for details.
1.3.2 Removing wildcard addresses from sockets
When using the wildcard * endpoint in zmq_bind(), the caller should unbind this endpoint from the socket using zmq_unbind() using the actual endpoint obtained from the ZMQ_LAST_ENDPOINT socket option.
1.3.3 Connect a socket
When connecting a socket to a peer address using zmq_connect() with tcp transport, the endpoint should be interpreted as the peer address followed by a colon and the TCP port number to use. You can optionally specify a source_endpoint as the source address of the connection; tcp://source_endpoint;'endpoint', see the interface description above for details.
The peer address can be specified by any of the following:
The DNS name of the peer.
The peer's IPv4 or IPv6 address, in its numerical representation.
Note: A description of the ZeroMQ Message Transfer Protocol (ZMTP) used by the TCP transport can be found at http://rfc.zeromq.org/spec:15
2. Reliable multicast transmission using PGM: zmq_pgm(7)
2.1 Name
zmq_pgm - ZMQ reliable multicast transport using PGM
2.2 Overview
PGM (Pragmatic General Multicast) is a reliable data multicast transmission protocol on IP networks.
2.3 Description
ZMQ implements two variants of PGM, PGM datagrams layered directly on top of RFC 3208 (pgm transport) and "encapsulated PGM" or EPGM-defined IP datagrams, where PGM datagrams are encapsulated within UDP datagrams (epgm transport ).
The pgm and epgm transports can only be used with ZMQ_PUB and ZMQ_SUB socket types.
Also, PGM sockets are rate limited by default. See the ZMQ_RATE and ZMQ_RECOVERY_IVL options documented in zmq_setsockopt(3) for details.
The pgm transport implementation requires access to raw IP sockets. Additional permissions may be required on some operating systems for this operation. Applications that do not require direct interoperability with other PGMs are encouraged to use the epgm transport without any special permissions.
2.4 Solution
A ZMQ endpoint is a string consisting of transport:// followed by an address. transport specifies the underlying protocol to use. The address specifies the transport-specific address to connect to.
For PGM shipping, shipping is pgm, and for EPGM protocols, shipping is epgm. The meaning of the address part is defined as follows.
2.5 Connect a socket
When connecting a socket to a peer address using zmq_connect() with pgm or epgm transport, the endpoint is interpreted as an interface followed by a semicolon, followed by a multicast address, followed by a colon and a port number.
An interface can be specified by any of the following:
The interface name defined by the operating system.
The primary IPv4 address assigned to the interface in numerical representation.
Note: Interface names are not standardized in any way and should be considered arbitrary and platform-dependent. On Win32 platforms, short interface names do not exist, so only the primary IPv4 address can be used to specify an interface. The interface part can be omitted, in which case the default interface part will be selected. A multicast address is specified by the IPv4 multicast address in its numerical representation.
2.5 Wire format
Consecutive PGM datagrams are interpreted by ZMQ as a single contiguous stream of data, where ZMQ messages do not necessarily align with PGM datagram boundaries, and a single ZMQ message can span several PGM datagrams. This data stream consists of ZMQ messages encapsulated in frames as described in zmq_tcp(7).
2.5.1 Pgm Datagram Payload
The following ABNF syntax represents the payload of a single PGM datagram used by ZMQ:
datagram = (offset data)
offset = 2OCTET
data = *OCTET
In order for delayed join consumers to be able to identify message boundaries, each PGM datagram payload begins with a 16-bit unsigned integer in network byte order, specifying the offset of the first message frame in the datagram or if the datagram contains the value 0xFFFF Contains only the middle part of a larger message.
Note that the offset specifies the start of the first message, not the first message part. So if there are trailing message parts at the beginning of the packet, the offset will ignore them and point to the 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 figure further illustrates the layout of three example ZMQ frames 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) |
+--- -----------+----------------------------+--------- ----+
3. Local inter-process communication transmission: zmq_ipc (7)
3.1 Name
zmq_ipc - ZMQ local inter-process communication transport
3.2 Overview
Interprocess transport uses a system-dependent IPC mechanism to pass messages between local processes.
Note: Interprocess transfers are currently only implemented on operating systems that provide UNIX domain sockets.
3.3 Solution
A ZMQ endpoint is a string consisting of transport:// followed by an address. transport specifies the underlying protocol to use.
The address specifies the transport-specific address to connect to. For inter-process transfers, the transfer is ipc and the meaning of the address part is defined below.
3.3.1 Binding a socket
When binding a socket to a local address using zmq_bind() with the ipc transport, the endpoint should be interpreted as an arbitrary string identifying the pathname to be created. Pathnames must be unique within the operating system namespace used by the ipc implementation and must meet any operating system restrictions on pathname format and length.
When the address is *, zmq_bind() should generate a unique temporary pathname. Callers should use the ZMQ_LAST_ENDPOINT socket option to retrieve this pathname. See zmq_getsockopt(3) for details.
Any existing bindings to the same endpoint should be overwritten. That is, if the second process binds to an endpoint already bound by the process, this will succeed and the first process will lose the binding. In this behavior, ipc transfers are inconsistent with tcp or inproc transfers.
The process must be able to write the endpoint pathname. When the endpoint starts with /, for example, ipc:/// pathname, this will be an absolute pathname. If the endpoint specifies a directory that does not exist, the bind will fail.
On Linux only, abstract namespaces should be used when endpoint pathnames start with @. The abstract namespace is independent of the filesystem, and if a process tries to bind an endpoint that is already bound by the process, it will fail. See unix(7) for details.
The maximum size of an IPC pathname depends on the operating system. On Linux, up to 113 characters, including the "ipc://" prefix (107 characters for real path names).
3.3.2 Removing wildcard addresses from sockets
When using the wildcard * endpoint in zmq_bind(), the caller should unbind this endpoint from the socket using zmq_unbind() using the actual endpoint obtained from the ZMQ_LAST_ENDPOINT socket option.
3.3.3 Connecting a socket
When using zmq_connect() with the ipc transport to connect a socket to a peer address, the endpoint shall be interpreted as an arbitrary string identifying the pathname to connect to. The pathname must first be created within the OS namespace by assigning it to the socket with zmq_bind().
4. Local intra-process (inter-thread) communication transmission: zmq_inproc(7)
4.1 Name
zmq_inproc - ZMQ local in-process (inter-thread) communication transport
4.2 Overview
In-process transport passes messages directly through memory between threads sharing a single ZMQ context.
Note: I/O threads are not involved when passing messages using the inproc transport. So if you're using a ZMQ context for in-process messaging, you can just initialize the context with zero I/O threads. See zmq_init(3) for details.
4.3 Solution
A ZMQ endpoint is a string consisting of transport:// followed by an address. transport specifies the underlying protocol to use. The address specifies the transport-specific address to connect to.
For shipments in progress, the shipment is unreasonable and the meaning of the address part is defined below.
4.3.1 Assigning local addresses to sockets
When assigning a local address to a socket using zmq_bind() with the inproc transport, the endpoint shall be interpreted as an arbitrary string identifying the name to be created. The name must be unique within the ZMQ context associated with the socket and can be up to 256 characters long. There are no other restrictions on the format of the name.
4.3.2 Connecting a socket
When connecting a socket to a peer address using zmq_connect() with the inproc transport, the endpoint is interpreted as an arbitrary string identifying the name to connect to. The name must first be created by assigning it to at least one socket in the same ZMQ context as the connected socket.
5. Cluster IPC protocol: zmq_tipc
5.1 Name
zmq_tipc - ZMQ unicast transport using TIPC
5.2 Overview
TIPC is a clustered IPC protocol using a location transparent addressing scheme.
5.3 Solution
A ZMQ endpoint is a string consisting of transport:// followed by an address. transport specifies the underlying protocol to use. The address specifies the transport-specific address to connect to.
For TIPC shipping, the shipping is tipc and the meaning of the address part is defined as follows.
5.3.1 Assigning port names to sockets
Using _zmq_bind()_ with 'tipc' when assigning port names to sockets
For transport, 'endpoint' is defined in the form:
{type, lower, upper}
*Type is the numeric (u32) ID of your service.
* Lower and Upper specify a range for your service.
Willingness to publish the same service with overlapping lower/higher IDs
causes connection requests to be distributed to those requests in a round-robin fashion.
5.3.2 Connecting a socket
When connecting a socket to a peer address using zmq_connect() with tipc transport, the endpoint is interpreted as the service ID followed by a comma and the instance ID.
The instance ID must be in the lower/higher range of the published port name for the endpoint to be valid.