From 5219e4ce8f9aa082c5f91e248a9f66639c69727d Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Fri, 28 May 2010 00:49:13 +0200 Subject: Clarify socket types in documentation, reinstate ZMQ_PAIR --- doc/zmq.txt | 4 +-- doc/zmq_setsockopt.txt | 14 ++++---- doc/zmq_socket.txt | 91 +++++++++++++++++++++++++++++++------------------- 3 files changed, 65 insertions(+), 44 deletions(-) diff --git a/doc/zmq.txt b/doc/zmq.txt index 003570a..fa15e43 100644 --- a/doc/zmq.txt +++ b/doc/zmq.txt @@ -90,8 +90,8 @@ Standard sockets present a _synchronous_ interface to either connection-mode reliable byte streams (SOCK_STREAM), or connection-less unreliable datagrams (SOCK_DGRAM). In comparison, 0MQ sockets present an abstraction of a asynchronous _message queue_, with the exact queueing semantics depending on -the socket type (_messaging pattern_) in use. See linkzmq:zmq_socket[3] for the -_messaging patterns_ provided. +the socket type in use. See linkzmq:zmq_socket[3] for the socket types +provided. 0MQ sockets being _asynchronous_ means that the timings of the physical connection setup and teardown, reconnect and effective delivery are organized diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index 8845a10..3bc1081 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/zmq_setsockopt.txt @@ -61,13 +61,13 @@ The 'ZMQ_AFFINITY' option shall set the I/O thread affinity for connections created by subsequent _zmq_connect()_ or _zmq_bind()_ calls on the specified 'socket'. -sockets. Affinity determines which threads from the 0MQ I/O thread pool -associated with the socket's _context_ shall handle newly created connections. -A value of zero specifies no affinity, meaning that work shall be distributed -fairly among all 0MQ I/O threads in the thread pool. For non-zero values, the -lowest bit corresponds to thread 1, second lowest bit to thread 2 and so on. -For example, a value of 3 specifies that subsequent connections on 'socket' -shall be handled exclusively by I/O threads 1 and 2. +Affinity determines which threads from the 0MQ I/O thread pool associated with +the socket's _context_ shall handle newly created connections. A value of zero +specifies no affinity, meaning that work shall be distributed fairly among all +0MQ I/O threads in the thread pool. For non-zero values, the lowest bit +corresponds to thread 1, second lowest bit to thread 2 and so on. For example, +a value of 3 specifies that subsequent connections on 'socket' shall be handled +exclusively by I/O threads 1 and 2. See also linkzmq:zmq_init[3] for details on allocating the number of I/O threads for a specific _context_. diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt index e01921c..ebae5e1 100644 --- a/doc/zmq_socket.txt +++ b/doc/zmq_socket.txt @@ -19,7 +19,31 @@ The 'zmq_socket()' function shall create a 0MQ socket within the specified argument specifies the socket type, which determines the semantics of communication over the socket. -The following _messaging patterns_ are defined: +The following sections present the socket types defined by 0MQ, grouped by the +general _messaging pattern_ built from related socket types. + + +Request-reply pattern +~~~~~~~~~~~~~~~~~~~~~ +The request-reply pattern is used for sending requests from a _client_ to a +_service_, and receiving subsequent replies to each request sent. + +Socket type:: 'ZMQ_REQ' +Compatible peer sockets:: 'ZMQ_REP' + +A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and +receive replies from a _service_. This socket type allows only an alternating +sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each +request sent is load-balanced among all connected _services_. + +Socket type:: 'ZMQ_REP' +Compatible peer sockets:: 'ZMQ_REQ' + +A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and +send replies to a _client_. This socket type allows only an alternating +sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each +reply is routed to the _client_ that issued the last received request. + Publish-subscribe pattern ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -43,49 +67,46 @@ which messages to subscribe to. The _zmq_send()_ function is not implemented for this socket type. -Request-reply pattern -~~~~~~~~~~~~~~~~~~~~~ -The request-reply pattern is used for sending requests from a _client_ to a -_service_, and receiving subsequent replies to each request sent. - -Socket type:: 'ZMQ_REQ' -Compatible peer sockets:: 'ZMQ_REP' +Pipeline pattern +~~~~~~~~~~~~~~~~ +The pipeline pattern is used for distributing data to _nodes_ arranged in +a pipeline. Data always flows *down* the pipeline, and each stage of the +pipeline is connected to at least one _node_. When a pipeline stage is +connected to multiple _nodes_ data is processed by all connected _nodes_ in +parallel. -A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and -receive replies from a _service_. This socket type allows only an alternating -sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each -request sent is load-balanced among all connected _services_. +Socket type:: 'ZMQ_DOWNSTREAM' +Compatible peer sockets:: 'ZMQ_UPSTREAM' -Socket type:: 'ZMQ_REP' -Compatible peer sockets:: 'ZMQ_REQ' +A socket of type 'ZMQ_DOWNSTREAM' is used by a pipeline _node_ to send messages +to downstream pipeline _nodes_. Messages are load-balanced to all connected +downstream _nodes_. The _zmq_recv()_ function is not implemented for this +socket type. -A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and -send replies to a _client_. This socket type allows only an alternating -sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each -reply is routed to the _client_ that issued the last received request. +Socket type:: 'ZMQ_UPSTREAM' +Compatible peer sockets:: 'ZMQ_DOWNSTREAM' +A socket of type 'ZMQ_UPSTREAM' is used by a pipeline _node_ to receive +messages from upstream pipeline _nodes_. Messages are fair-queued from among +all connected upstream _nodes_. The _zmq_send()_ function is not implemented +for this socket type. -Parallelized pipeline pattern -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The parallelized pipeline pattern is used for distributing work between -_components_ of a pipeline. Work travels down the pipeline and at each stage -can be processed by any number of _components_ in parallel. -Socket type:: 'ZMQ_UPSTREAM' -Compatible peer sockets:: 'ZMQ_DOWNSTREAM' +Exclusive pair pattern +~~~~~~~~~~~~~~~~~~~~~~ +The exclusive pair pattern is used for communicating exclusively between two +peers. -A socket of type 'ZMQ_UPSTREAM' is used by a _component_ of a pipeline to -receive messages from upstream stages of the pipeline. Messages are fair-queued -from among all connected upstream _components_. The _zmq_send()_ function is -not implemented for this socket type. +Socket type:: 'ZMQ_PAIR' +Compatible peer sockets:: 'ZMQ_PAIR' -Socket type:: 'ZMQ_DOWNSTREAM' -Compatible peer sockets:: 'ZMQ_UPSTREAM' +A socket of type 'ZMQ_PAIR' can only be connected to a single peer at any one +time. No message routing or filtering is performed on messages sent over a +'ZMQ_PAIR' socket. -A socket of type 'ZMQ_DOWNSTREAM' is used by a _component_ of a pipeline to -send messages to downstream stages of the pipeline. Messages are load-balanced -to all connected downstream _components_. The _zmq_recv()_ function is not -implemented for this socket type. +NOTE: 'ZMQ_PAIR' sockets are experimental, and are currently missing several +features such as auto-reconnection. Developers should consider other patterns +in preference to the exclusive pair pattern. RETURN VALUE -- cgit v1.2.3 From 8bd3f743f50a61355b6cf18046d59c7d0289836b Mon Sep 17 00:00:00 2001 From: Mikko Koppanen Date: Fri, 16 Apr 2010 00:01:13 +0100 Subject: Import redhat packaging --- builds/redhat/zeromq.spec | 137 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 builds/redhat/zeromq.spec diff --git a/builds/redhat/zeromq.spec b/builds/redhat/zeromq.spec new file mode 100644 index 0000000..756ba9d --- /dev/null +++ b/builds/redhat/zeromq.spec @@ -0,0 +1,137 @@ +Name: zeromq +Version: @PACKAGE_VERSION@ +Release: 1%{?dist} +Summary: Fastest. Messaging. Ever. +Group: Applications/Internet +License: LGPLv3+ +URL: http://www.zeromq.org/ +Source: http://www.zeromq.org/local--files/area:download/%{name}-%{version}.tar.gz +Prefix: %{_prefix} +Buildroot: %{_tmppath}/%{name}-%{version}-%{release}-root +BuildRequires: uuid-devel, gcc, make, gcc-c++, libstdc++-devel +Requires: uuid, libstdc++ + +# Build pgm only on supported archs +%ifarch pentium3 pentium4 athlon i386 i486 i586 i686 x86_64 +BuildRequires: glib2-devel +Requires: glib2 +%endif + +%description +Fast and lightweight messaging system designed with +speed and reliability in mind. + +%package devel +Summary: Development headers +Group: Development/Libraries +Requires: %{name} = %{version}-%{release}, pkgconfig + +%description devel +Files needed for building applications with zeromq. + +%package utils +Summary: zeromq utilities +Group: System Environment/Utilities +Requires: %{name} = %{version}-%{release} + +%description utils +Performance testing utilities for zeromq. + +%prep +%setup -q + +%build +%ifarch pentium3 pentium4 athlon i386 i486 i586 i686 x86_64 + %configure --with-pgm +%else + %configure +%endif + +%{__make} %{?_smp_mflags} + +%install +[ "%{buildroot}" != "/" ] && %{__rm} -rf %{buildroot} + +# Install the package to build area +%makeinstall + +# copy the utility binaries +%{__cp} %{_builddir}/%{name}-%{version}/perf/local_lat %{buildroot}/%{_bindir} +%{__cp} %{_builddir}/%{name}-%{version}/perf/local_thr %{buildroot}/%{_bindir} +%{__cp} %{_builddir}/%{name}-%{version}/perf/remote_lat %{buildroot}/%{_bindir} +%{__cp} %{_builddir}/%{name}-%{version}/perf/remote_thr %{buildroot}/%{_bindir} + +%post +/sbin/ldconfig + +%postun +/sbin/ldconfig + +%clean +[ "%{buildroot}" != "/" ] && %{__rm} -rf %{buildroot} + +%files +%defattr(-,root,root,-) + +# docs in the main package +%doc AUTHORS ChangeLog COPYING COPYING.LESSER NEWS README + +# libraries +%{_libdir}/libzmq.so.0 +%{_libdir}/libzmq.so.0.0.0 + +%attr(0755,root,root) %{_bindir}/zmq_forwarder +%attr(0755,root,root) %{_bindir}/zmq_queue +%attr(0755,root,root) %{_bindir}/zmq_streamer + +%{_mandir}/man7/zmq.7.gz +%{_mandir}/man1/zmq_forwarder.1.gz +%{_mandir}/man1/zmq_queue.1.gz +%{_mandir}/man1/zmq_streamer.1.gz + +%files utils +%attr(0755, root, root) %{_bindir}/local_lat +%attr(0755, root, root) %{_bindir}/local_thr +%attr(0755, root, root) %{_bindir}/remote_lat +%attr(0755, root, root) %{_bindir}/remote_thr + +%files devel +%defattr(-,root,root,-) +%{_includedir}/zmq.h +%{_includedir}/zmq.hpp + +%{_libdir}/libzmq.la +%{_libdir}/libzmq.a +%{_libdir}/pkgconfig/libzmq.pc +%{_libdir}/libzmq.so + +%{_mandir}/man3/zmq_bind.3.gz +%{_mandir}/man3/zmq_close.3.gz +%{_mandir}/man3/zmq_connect.3.gz +%{_mandir}/man3/zmq_init.3.gz +%{_mandir}/man3/zmq_msg_close.3.gz +%{_mandir}/man3/zmq_msg_copy.3.gz +%{_mandir}/man3/zmq_msg_data.3.gz +%{_mandir}/man3/zmq_msg_init.3.gz +%{_mandir}/man3/zmq_msg_init_data.3.gz +%{_mandir}/man3/zmq_msg_init_size.3.gz +%{_mandir}/man3/zmq_msg_move.3.gz +%{_mandir}/man3/zmq_msg_size.3.gz +%{_mandir}/man3/zmq_poll.3.gz +%{_mandir}/man3/zmq_recv.3.gz +%{_mandir}/man3/zmq_send.3.gz +%{_mandir}/man3/zmq_setsockopt.3.gz +%{_mandir}/man3/zmq_socket.3.gz +%{_mandir}/man3/zmq_strerror.3.gz +%{_mandir}/man3/zmq_term.3.gz +%{_mandir}/man3/zmq_version.3.gz +%{_mandir}/man7/zmq_cpp.7.gz +%{_mandir}/man7/zmq_epgm.7.gz +%{_mandir}/man7/zmq_inproc.7.gz +%{_mandir}/man7/zmq_ipc.7.gz +%{_mandir}/man7/zmq_pgm.7.gz +%{_mandir}/man7/zmq_tcp.7.gz + +%changelog +* Sat Apr 10 2010 Mikko Koppanen 2.0.7-1 +- Initial packaging -- cgit v1.2.3 From b4cc7b97ecaf743f3259f9df7d687558892b8a72 Mon Sep 17 00:00:00 2001 From: Mikko Koppanen Date: Fri, 16 Apr 2010 10:26:22 +0100 Subject: dist-hook for copying zeromq.spec to top-level --- Makefile.am | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Makefile.am b/Makefile.am index e6ecfcc..314a97c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -9,6 +9,8 @@ $(top_srcdir)/foreign/xmlParser/xmlParser.cpp \ $(top_srcdir)/foreign/xmlParser/xmlParser.hpp dist-hook: + -cp $(top_srcdir)/builds/redhat/zeromq.spec $(distdir)/zeromq.spec + -sed s/\@PACKAGE_VERSION\@/@PACKAGE_VERSION@/ -i $(distdir)/zeromq.spec -rm -rf $(distdir)/foreign/openpgm/@pgm_basename@ distclean-local: -rm -rf $(top_srcdir)/foreign/openpgm/@pgm_basename@ -- cgit v1.2.3 From 74f1a4a579d3b09b3420092d9f076827be31c4e7 Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Fri, 28 May 2010 00:55:04 +0200 Subject: RPM packaging cleanups - ditch -utils package - add descriptions from Debian packaging --- builds/redhat/zeromq.spec | 41 +++++++++++++++++------------------------ 1 file changed, 17 insertions(+), 24 deletions(-) diff --git a/builds/redhat/zeromq.spec b/builds/redhat/zeromq.spec index 756ba9d..781c65d 100644 --- a/builds/redhat/zeromq.spec +++ b/builds/redhat/zeromq.spec @@ -1,7 +1,7 @@ Name: zeromq Version: @PACKAGE_VERSION@ Release: 1%{?dist} -Summary: Fastest. Messaging. Ever. +Summary: The ZeroMQ messaging library Group: Applications/Internet License: LGPLv3+ URL: http://www.zeromq.org/ @@ -18,24 +18,29 @@ Requires: glib2 %endif %description -Fast and lightweight messaging system designed with -speed and reliability in mind. +The 0MQ lightweight messaging kernel is a library which extends the +standard socket interfaces with features traditionally provided by +specialised messaging middleware products. 0MQ sockets provide an +abstraction of asynchronous message queues, multiple messaging +patterns, message filtering (subscriptions), seamless access to +multiple transport protocols and more. + +This package contains the ZeroMQ shared library. %package devel -Summary: Development headers +Summary: Development files and static library for the ZeroMQ library Group: Development/Libraries Requires: %{name} = %{version}-%{release}, pkgconfig %description devel -Files needed for building applications with zeromq. - -%package utils -Summary: zeromq utilities -Group: System Environment/Utilities -Requires: %{name} = %{version}-%{release} +The 0MQ lightweight messaging kernel is a library which extends the +standard socket interfaces with features traditionally provided by +specialised messaging middleware products. 0MQ sockets provide an +abstraction of asynchronous message queues, multiple messaging +patterns, message filtering (subscriptions), seamless access to +multiple transport protocols and more. -%description utils -Performance testing utilities for zeromq. +This package contains ZeroMQ related development libraries and header files. %prep %setup -q @@ -55,12 +60,6 @@ Performance testing utilities for zeromq. # Install the package to build area %makeinstall -# copy the utility binaries -%{__cp} %{_builddir}/%{name}-%{version}/perf/local_lat %{buildroot}/%{_bindir} -%{__cp} %{_builddir}/%{name}-%{version}/perf/local_thr %{buildroot}/%{_bindir} -%{__cp} %{_builddir}/%{name}-%{version}/perf/remote_lat %{buildroot}/%{_bindir} -%{__cp} %{_builddir}/%{name}-%{version}/perf/remote_thr %{buildroot}/%{_bindir} - %post /sbin/ldconfig @@ -89,12 +88,6 @@ Performance testing utilities for zeromq. %{_mandir}/man1/zmq_queue.1.gz %{_mandir}/man1/zmq_streamer.1.gz -%files utils -%attr(0755, root, root) %{_bindir}/local_lat -%attr(0755, root, root) %{_bindir}/local_thr -%attr(0755, root, root) %{_bindir}/remote_lat -%attr(0755, root, root) %{_bindir}/remote_thr - %files devel %defattr(-,root,root,-) %{_includedir}/zmq.h -- cgit v1.2.3 From da37c45b0c7200eea96118952e671972b71df4ce Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Fri, 28 May 2010 01:38:43 +0200 Subject: Clarify zmq_bind/zmq_connect Use the term 'endpoint' correctly, and drop the nonsense about local/remote addresses which doesn't clearly explain what is going on --- doc/zmq_bind.txt | 28 +++++++++++++++------------- doc/zmq_connect.txt | 26 ++++++++++++++------------ 2 files changed, 29 insertions(+), 25 deletions(-) diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.txt index 983ce93..c76d05a 100644 --- a/doc/zmq_bind.txt +++ b/doc/zmq_bind.txt @@ -4,34 +4,36 @@ zmq_bind(3) NAME ---- -zmq_bind - assign a local address to a socket +zmq_bind - accept connections on a socket SYNOPSIS -------- -*int zmq_bind (void '*socket', const char '*address');* +*int zmq_bind (void '*socket', const char '*endpoint');* DESCRIPTION ----------- -The _zmq_bind()_ function shall assign a local address specified by the -'address' argument to the socket referenced by the 'socket' argument. +The _zmq_bind()_ function shall create an endpoint for accepting connections +and bind it to the socket referenced by the 'socket' argument. -The 'address' argument is a string consisting of two parts as follows: -'transport'://'endpoint'. The 'transport' part specifies the underlying -transport protocol to use. The meaning of the 'endpoint' part is specific to +The 'endpoint' argument is a string consisting of two parts as follows: +'transport'`://`'address'. The 'transport' part specifies the underlying +transport protocol to use. The meaning of the 'address' part is specific to the underlying transport protocol selected. The following transports are defined: +'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] +'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] 'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7] 'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] -'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] -'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] -A single socket may have an arbitrary number of local addresses assigned to it -using _zmq_bind()_, while also being connected to an arbitrary number of peer -addresses using _zmq_connect()_. +With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to +multiple endpoints using _zmq_connect()_, while simultaneously accepting +incoming connections from multiple endpoints bound to the socket using +_zmq_bind()_. Refer to linkzmq:zmq_socket[3] for a description of the exact +semantics involved when connecting or binding a socket to multiple endpoints. RETURN VALUE @@ -63,7 +65,7 @@ EXAMPLE /* Create a ZMQ_PUB socket */ void *socket = zmq_socket (context, ZMQ_PUB); assert (socket); -/* Bind it to a in-process transport with the endpoint 'my_publisher' */ +/* Bind it to a in-process transport with the address 'my_publisher' */ int rc = zmq_bind (socket, "inproc://my_publisher"); assert (rc == 0); /* Bind it to a TCP transport on port 5555 of the 'eth0' interface */ diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt index d31b87b..2bc8e4f 100644 --- a/doc/zmq_connect.txt +++ b/doc/zmq_connect.txt @@ -4,34 +4,36 @@ zmq_connect(3) NAME ---- -zmq_connect - connect a socket to a peer address +zmq_connect - connect a socket SYNOPSIS -------- -*int zmq_connect (void '*socket', const char '*address');* +*int zmq_connect (void '*socket', const char '*endpoint');* DESCRIPTION ----------- The _zmq_connect()_ function shall connect the socket referenced by the -'socket' argument to a peer address specified by the 'address' argument. +'socket' argument to the endpoint specified by the 'endpoint' argument. -The 'address' argument is a string consisting of two parts as follows: -'transport'`://`'endpoint'. The 'transport' part specifies the underlying -transport protocol to use. The meaning of the 'endpoint' part is specific to +The 'endpoint' argument is a string consisting of two parts as follows: +'transport'`://`'address'. The 'transport' part specifies the underlying +transport protocol to use. The meaning of the 'address' part is specific to the underlying transport protocol selected. The following transports are defined: +'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] +'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] 'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7] 'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7] -'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7] -'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7] -A single socket may be connected to an arbitrary number of peer addresses using -_zmq_connect()_, while also having an arbitrary number of local addresses -assigned to it using _zmq_bind()_. +With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to +multiple endpoints using _zmq_connect()_, while simultaneously accepting +incoming connections from multiple endpoints bound to the socket using +_zmq_bind()_. Refer to linkzmq:zmq_socket[3] for a description of the exact +semantics involved when connecting or binding a socket to multiple endpoints. NOTE: The connection will not be performed immediately but as needed by 0MQ. Thus a successful invocation of _zmq_connect()_ does not indicate that a @@ -61,7 +63,7 @@ EXAMPLE /* Create a ZMQ_SUB socket */ void *socket = zmq_socket (context, ZMQ_SUB); assert (socket); -/* Connect it to an in-process transport with the endpoint 'my_publisher' */ +/* Connect it to an in-process transport with the address 'my_publisher' */ int rc = zmq_connect (socket, "inproc://my_publisher"); assert (rc == 0); /* Connect it to the host server001, port 5555 using a TCP transport */ -- cgit v1.2.3