Merge pull request #3816 from somdoron/SCATTER-GATHER-DOC

problem: no docs for scatter-gather

doc/zmq_socket.txt

@@ -340,6 +340,60 @@ Incoming routing strategy:: Fair-queued
 Outgoing routing strategy:: N/A
 Action in mute state:: Block
 
+Scatter-gather pattern
+~~~~~~~~~~~~~~~~
+The scatter-gather pattern is the thread-safe version of the pipeline pattern.
+The scatter-gather 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 round-robined among all connected _nodes_.
+
+ZMQ_SCATTER
+^^^^^^^^
+A socket of type 'ZMQ_SCATTER' is used by a scatter-gather _node_ to send messages
+to downstream scatter-gather _nodes_. Messages are round-robined to all connected
+downstream _nodes_. The _zmq_recv()_ function is not implemented for this
+socket type.
+
+When a 'ZMQ_SCATTER' socket enters the 'mute' state due to having reached the
+high water mark for all downstream _nodes_, or, for connection-oriented transports,
+if the ZMQ_IMMEDIATE option is set and there are no downstream _nodes_ at all,
+then any linkzmq:zmq_send[3] operations on the socket shall block until the mute
+state ends or at least one downstream _node_ becomes available for sending;
+messages are not discarded.
+
+NOTE: 'ZMQ_SCATTER' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
+This limits them to single part data.
+
+[horizontal]
+.Summary of ZMQ_SCATTER characteristics
+Compatible peer sockets:: 'ZMQ_SCATTER'
+Direction:: Unidirectional
+Send/receive pattern:: Send only
+Incoming routing strategy:: N/A
+Outgoing routing strategy:: Round-robin
+Action in mute state:: Block
+
+
+ZMQ_GATHER
+^^^^^^^^
+A socket of type 'ZMQ_GATHER' is used by a scatter-gather _node_ to receive messages
+from upstream scatter-gather _nodes_. Messages are fair-queued from among all
+connected upstream _nodes_. The _zmq_send()_ function is not implemented for
+this socket type.
+
+NOTE: 'ZMQ_GATHER' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
+This limits them to single part data.
+
+[horizontal]
+.Summary of ZMQ_GATHER characteristics
+Compatible peer sockets:: 'ZMQ_GATHER'
+Direction:: Unidirectional
+Send/receive pattern:: Receive only
+Incoming routing strategy:: Fair-queued
+Outgoing routing strategy:: N/A
+Action in mute state:: Block
+
 
 Exclusive pair pattern
 ~~~~~~~~~~~~~~~~~~~~~~