From 06105d164230800e8ea42ddd513e2f7fb27e6f2f Mon Sep 17 00:00:00 2001 From: Martin Sustrik Date: Wed, 13 Jan 2010 15:15:01 +0100 Subject: transports man pages updated --- man/man7/zmq_inproc.7 | 34 ++++++++++++++++++++++- man/man7/zmq_pgm.7 | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++- man/man7/zmq_tcp.7 | 5 ++++ man/man7/zmq_udp.7 | 32 ++++++++++++++++++++- 4 files changed, 145 insertions(+), 3 deletions(-) (limited to 'man') diff --git a/man/man7/zmq_inproc.7 b/man/man7/zmq_inproc.7 index 7f43ca7..bc09f90 100644 --- a/man/man7/zmq_inproc.7 +++ b/man/man7/zmq_inproc.7 @@ -2,8 +2,40 @@ .SH NAME In-process (inter-thread) tranport for 0MQ .SH SYNOPSIS -.SH DESCRIPTION + +In-process transport is optimised for passing messages betweem threads in the +same process. + +Messages are passed directly from one application thread to +another application thread. There are no intervening I/O threads involved. +Thus, if you are using 0MQ for in-process messaging only, you can initialise +the library ( +.IR zmq_init +) with zero I/O worker threads. + +.SH CONNECTION STRING + +Connection string for inproc transport is "inproc://" followed by an arbitrary +string. There are no restrictions on the string format: + +.nf + inproc://my_endpoint + inproc://feeds/opra/cboe + inproc://feeds.opra.nasdaq + inproc://!&W#($)_@_123*((^^^ +.fi + +.SH WIRE FORMAT + +In-process transport transfers messages via memory thus there is no need for a +wire format specification. + .SH "SEE ALSO" + +.BR zmq_tcp (7) +.BR zmq_udp (7) +.BR zmq_pgm (7) + .SH AUTHOR Martin Sustrik diff --git a/man/man7/zmq_pgm.7 b/man/man7/zmq_pgm.7 index 57af65e..e432730 100644 --- a/man/man7/zmq_pgm.7 +++ b/man/man7/zmq_pgm.7 @@ -2,8 +2,83 @@ .SH NAME PGM-based tranport for 0MQ .SH SYNOPSIS -.SH DESCRIPTION + +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 adress +of the NIC to use, semicolon, IP adress of the multicast group, colon and +port numbrt. 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 +mutlicast 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 + +.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_inproc (7) +.BR zmq_setsockopt (3) + .SH AUTHOR Martin Sustrik + diff --git a/man/man7/zmq_tcp.7 b/man/man7/zmq_tcp.7 index 391215e..aa3f56e 100644 --- a/man/man7/zmq_tcp.7 +++ b/man/man7/zmq_tcp.7 @@ -64,6 +64,11 @@ Binary layout of a larger message: .fi .SH "SEE ALSO" + +.BR zmq_udp (7) +.BR zmq_pgm (7) +.BR zmq_inproc (7) + .SH AUTHOR Martin Sustrik diff --git a/man/man7/zmq_udp.7 b/man/man7/zmq_udp.7 index 16cbf08..bfebc1c 100644 --- a/man/man7/zmq_udp.7 +++ b/man/man7/zmq_udp.7 @@ -2,8 +2,38 @@ .SH NAME UDP-based tranport for 0MQ .SH SYNOPSIS -.SH DESCRIPTION + +UDP transport is exactly the same as PGM transport except that PGM packets +are encapsulated in UDP packets. Rationale for this transport is that user-space +implementation of PGM requires right to create raw sockets (PGM is located +directly on top of IP layer in the netwroking stack), which is often not +available. UDP encapsulation solves this problem, however, it adds some overhead +related to creating and transferring UDP packet headers. + +.SH CONNECTION STRING + +Connection string for UDP transport is "udp://" followed by an IP adress +of the NIC to use, semicolon, IP adress of the multicast group, colon and +port numbrt. 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 +mutlicast group should be specified in the numeric representation. For example: + +.nf + udp://eth0:224.0.0.1:5555 + udp://lo:230.0.0.0:6666 + udp://192.168.0.111:224.0.0.1:5555 +.fi + +.SH WIRE FORMAT + +Same as with PGM transport except for UDP packet headers. + .SH "SEE ALSO" + +.BR zmq_pgm (7) +.BR zmq_tcp (7) +.BR zmq_inproc (7) + .SH AUTHOR Martin Sustrik -- cgit v1.2.3