From 40de45396f0493f2f77e4bce1bdbc0636ebbb4bf Mon Sep 17 00:00:00 2001
From: Doron Somech <somdoron@gmail.com>
Date: Wed, 5 Feb 2020 02:33:38 +0200
Subject: [PATCH] problem: no docs for scatter-gather

---
 doc/zmq_socket.txt | 54 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt
index a990e9bd..a0ff7c7c 100644
--- a/doc/zmq_socket.txt
+++ b/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
 ~~~~~~~~~~~~~~~~~~~~~~