Imported Debian patch 2.1.3-1debian/2.1.3-1

1 files changed, 49 insertions, 33 deletions

diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt
index 2156af2..6250b38 100644
--- a/doc/zmq_socket.txt
+++ b/doc/zmq_socket.txt
@@ -35,7 +35,7 @@ sockets transfer streams of bytes or discrete datagrams, 0MQ sockets transfer
 discrete _messages_.
 
 0MQ sockets being _asynchronous_ means that the timings of the physical
-connection setup and teardown, reconnect and effective delivery are transparent
+connection setup and tear down, reconnect and effective delivery are transparent
 to the user and organized by 0MQ itself. Further, messages may be _queued_ in
 the event that a peer is unavailable to receive them.
 
@@ -46,6 +46,11 @@ relationships. With the exception of 'ZMQ_PAIR', 0MQ sockets may be connected
 incoming connections *from multiple endpoints* bound to the socket using
 _zmq_bind()_, thus allowing many-to-many relationships.
 
+.Thread safety
+0MQ 'sockets' are _not_ thread safe. Applications MUST NOT use a socket
+from multiple threads except after migrating a socket from one thread to 
+another with a "full fence" memory barrier.
+
 .Socket types
 The following sections present the socket types defined by 0MQ, grouped by the
 general _messaging pattern_ which is built from related socket types.
@@ -88,7 +93,8 @@ 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
 request received is fair-queued from among all _clients_, and each reply sent
-is routed to the _client_ that issued the last request.
+is routed to the _client_ that issued the last request. If the original
+requester doesn't exist any more the reply is silently discarded.
 
 When a 'ZMQ_REP' socket enters an exceptional state due to having reached the
 high water mark for a _client_, then any replies sent to the _client_ in
@@ -100,29 +106,32 @@ Compatible peer sockets:: 'ZMQ_REQ'
 Direction:: Bidirectional
 Send/receive pattern:: Receive, Send, Receive, Send, ...
 Incoming routing strategy:: Fair-queued
-Outgoing routing stratagy:: Last peer
+Outgoing routing strategy:: Last peer
 ZMQ_HWM option action:: Drop
 
 
-ZMQ_XREQ
-^^^^^^^^
-A socket of type 'ZMQ_XREQ' is an advanced pattern used for extending
+ZMQ_DEALER
+^^^^^^^^^^
+A socket of type 'ZMQ_DEALER' is an advanced pattern used for extending
 request/reply sockets. Each message sent is load-balanced among all connected
 peers, and each message received is fair-queued from all connected peers.
 
-When a 'ZMQ_XREQ' socket enters an exceptional state due to having reached the
+Previously this socket was called 'ZMQ_XREQ' and that name remains available
+for backwards compatibility.
+
+When a 'ZMQ_DEALER' socket enters an exceptional state due to having reached the
 high water mark for all peers, or if there are no peers at all, then any
 linkzmq:zmq_send[3] operations on the socket shall block until the exceptional
 state ends or at least one peer becomes available for sending; messages are not
 discarded.
 
-When a 'ZMQ_XREQ' socket is connected to a 'ZMQ_REP' socket each message sent
+When a 'ZMQ_DEALER' socket is connected to a 'ZMQ_REP' socket each message sent
 must consist of an empty message part, the _delimiter_, followed by one or more
 _body parts_.
 
 [horizontal]
-.Summary of ZMQ_XREQ characteristics
-Compatible peer sockets:: 'ZMQ_XREP', 'ZMQ_REP'
+.Summary of ZMQ_DEALER characteristics
+Compatible peer sockets:: 'ZMQ_ROUTER', 'ZMQ_REP'
 Direction:: Bidirectional
 Send/receive pattern:: Unrestricted
 Outgoing routing strategy:: Load-balanced
@@ -130,23 +139,27 @@ Incoming routing strategy:: Fair-queued
 ZMQ_HWM option action:: Block
 
 
-ZMQ_XREP
-^^^^^^^^
-A socket of type 'ZMQ_XREP' is an advanced pattern used for extending
-request/reply sockets. When receiving messages a 'ZMQ_XREP' socket shall
+ZMQ_ROUTER
+^^^^^^^^^^
+A socket of type 'ZMQ_ROUTER' is an advanced pattern used for extending
+request/reply sockets. When receiving messages a 'ZMQ_ROUTER' socket shall
 prepend a message part containing the _identity_ of the originating peer to the
 message before passing it to the application. Messages received are fair-queued
-from among all connected peers. When sending messages a 'ZMQ_XREP' socket shall
+from among all connected peers. When sending messages a 'ZMQ_ROUTER' socket shall
 remove the first part of the message and use it to determine the _identity_ of
-the peer the message shall be routed to.
+the peer the message shall be routed to. If the peer does not exist anymore
+the message shall be silently discarded.
 
-When a 'ZMQ_XREP' socket enters an exceptional state due to having reached the
+Previously this socket was called 'ZMQ_XREP' and that name remains available
+for backwards compatibility.
+
+When a 'ZMQ_ROUTER' socket enters an exceptional state due to having reached the
 high water mark for all peers, or if there are no peers at all, then any
 messages sent to the socket shall be dropped until the exceptional state ends.
 Likewise, any messages routed to a non-existent peer or a peer for which the
 individual high water mark has been reached shall also be dropped.
 
-When a 'ZMQ_REQ' socket is connected to a 'ZMQ_XREP' socket, in addition to the
+When a 'ZMQ_REQ' socket is connected to a 'ZMQ_ROUTER' socket, in addition to the
 _identity_ of the originating peer each message received shall contain an empty
 _delimiter_ message part. Hence, the entire structure of each received message
 as seen by the application becomes: one or more _identity_ parts, _delimiter_
@@ -154,8 +167,8 @@ part, one or more _body parts_. When sending replies to a 'ZMQ_REQ' socket the
 application must include the _delimiter_ part.
 
 [horizontal]
-.Summary of ZMQ_XREP characteristics
-Compatible peer sockets:: 'ZMQ_XREQ', 'ZMQ_REQ'
+.Summary of ZMQ_ROUTER characteristics
+Compatible peer sockets:: 'ZMQ_DEALER', 'ZMQ_REQ'
 Direction:: Bidirectional
 Send/receive pattern:: Unrestricted
 Outgoing routing strategy:: See text
@@ -166,19 +179,19 @@ ZMQ_HWM option action:: Drop
 Publish-subscribe pattern
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 The publish-subscribe pattern is used for one-to-many distribution of data from
-a single _publisher_ to multiple _subscribers_ in a fanout fashion.
+a single _publisher_ to multiple _subscribers_ in a fan out fashion.
 
 
 ZMQ_PUB
 ^^^^^^^
 A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data.
-Messages sent are distributed in a fanout fashion to all connected peers.
+Messages sent are distributed in a fan out fashion to all connected peers.
 The linkzmq:zmq_recv[3] function is not implemented for this socket type.
 
 When a 'ZMQ_PUB' socket enters an exceptional state due to having reached the
 high water mark for a _subscriber_, then any messages that would be sent to the
 _subscriber_ in question shall instead be dropped until the exceptional state
-ends.
+ends. The _zmq_send()_ function shall never block for this socket type.
 
 [horizontal]
 .Summary of ZMQ_PUB characteristics
@@ -186,7 +199,7 @@ Compatible peer sockets:: 'ZMQ_SUB'
 Direction:: Unidirectional
 Send/receive pattern:: Send only
 Incoming routing strategy:: N/A
-Outgoing routing strategy:: Fanout
+Outgoing routing strategy:: Fan out
 ZMQ_HWM option action:: Drop
 
 
@@ -205,7 +218,7 @@ Direction:: Unidirectional
 Send/receive pattern:: Receive only
 Incoming routing strategy:: Fair-queued
 Outgoing routing strategy:: N/A
-ZMQ_HWM option action:: N/A
+ZMQ_HWM option action:: Drop
 
 
 Pipeline pattern
@@ -262,8 +275,9 @@ ZMQ_HWM option action:: N/A
 
 Exclusive pair pattern
 ~~~~~~~~~~~~~~~~~~~~~~
-The exclusive pair is an advanced pattern used for communicating exclusively
-between two peers.
+The exclusive pair pattern is used to connect a peer to precisely one other
+peer. This pattern is used for inter-thread communication across the inproc
+transport.
 
 
 ZMQ_PAIR
@@ -277,8 +291,10 @@ high water mark for the connected peer, or if no peer is connected, then
 any linkzmq:zmq_send[3] operations on the socket shall block until the peer
 becomes available for sending; messages are not discarded.
 
-NOTE: 'ZMQ_PAIR' sockets are experimental, and are currently missing several
-features such as auto-reconnection.
+NOTE: 'ZMQ_PAIR' sockets are designed for inter-thread communication across
+the linkzmq:zmq_inproc[7] transport and do not implement functionality such 
+as auto-reconnection. 'ZMQ_PAIR' sockets are considered experimental and may
+have other missing or broken aspects.
 
 [horizontal]
 .Summary of ZMQ_PAIR characteristics
@@ -301,11 +317,10 @@ ERRORS
 ------
 *EINVAL*::
 The requested socket 'type' is invalid.
-*EMTHREAD*::
-The maximum number of sockets within this 'context' has been exceeded.
 *EFAULT*::
 The provided 'context' was not valid (NULL).
-
+*ETERM*::
+The context specified was terminated.
 
 SEE ALSO
 --------
@@ -315,10 +330,11 @@ linkzmq:zmq_bind[3]
 linkzmq:zmq_connect[3]
 linkzmq:zmq_send[3]
 linkzmq:zmq_recv[3]
+linkzmq:zmq_inproc[7]
 linkzmq:zmq[7]
 
 
 AUTHORS
 -------
-The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.