From c8cb828eab3325dc4a8517c1b0f572aa7dc9dead Mon Sep 17 00:00:00 2001
From: Matthias Vogelgesang <matthias.vogelgesang@kit.edu>
Date: Tue, 28 Nov 2017 09:57:56 +0100
Subject: Add zmq-pub and zmq-sub tasks

---
 docs/examples.rst   | 29 +++++++++++++++++++++++++++++
 docs/generators.rst | 15 +++++++++++++++
 docs/sinks.rst      | 14 ++++++++++++++
 3 files changed, 58 insertions(+)

(limited to 'docs')

diff --git a/docs/examples.rst b/docs/examples.rst
index f530eb9..1653a45 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -128,6 +128,35 @@ space. To reconstruct, you have to feed the sinograms into :gobj:class:`zeropad`
         null
 
 
+=================
+Data distribution
+=================
+
+To distribute data in a compute network you can use the :gobj:class:`zmq-pub`
+sink and :gobj:class:`zmq-sub` generator. For example, to read data on machine A
+and store it on machine B, you would run
+
+.. code-block:: bash
+
+    ufo-launch read path=/data ! zmq-pub
+
+on machine A and
+
+.. code-block:: bash
+
+    ufo-launch zmq-sub address=tcp://hostname-of-machine-a ! write
+
+on machine B. Note that by default :gobj:class:`zmq-pub` publishes data as soon
+as it receives it, thus some of the data will get lost if the
+:gobj:class:`zmq-sub` is run after :gobj:class:`zmq-pub`. You can prevent this
+by telling the :gobj:class:`zmq-pub` task to wait for a certain number of
+subscribers to subscribe:
+
+.. code-block:: bash
+
+    ufo-launch read path=/data ! zmq-pub expected-subscribers=1
+
+
 .. rubric:: References
 
 .. [KaSl01] Kak, A. C., & Slaney, M. (2001). Principles of Computerized Tomographic Imaging (Philadelphia, PA: SIAM).
diff --git a/docs/generators.rst b/docs/generators.rst
index 67e6f42..7e52fb0 100644
--- a/docs/generators.rst
+++ b/docs/generators.rst
@@ -145,6 +145,21 @@ Memory reader
         Specifies the number of items to read.
 
 
+ZeroMQ subscriber
+=================
+
+.. gobj:class:: zmq-sub
+
+    Generates a stream from a compatible ZeroMQ data stream, for example
+    published by the :gobj:class:`zmq-pub` task.
+
+    .. gobj:prop:: address:string
+
+        Host address of the ZeroMQ publisher. Note, that as of now the publisher
+        binds to a ``tcp`` endpoint, thus you have to use that as well. By
+        default, the address is set to the local host address 127.0.0.1.
+
+
 UcaCamera reader
 ================
 
diff --git a/docs/sinks.rst b/docs/sinks.rst
index d4135da..c78d083 100644
--- a/docs/sinks.rst
+++ b/docs/sinks.rst
@@ -106,6 +106,20 @@ Memory writer
         that point only.
 
 
+ZeroMQ publisher
+================
+
+.. gobj:class:: zmq-pub
+
+    Publishes the stream as a ZeroMQ data stream to compatible ZeroMQ
+    subscribers such as the :gobj:class:`zmq-sub` source.
+
+    .. gobj:prop:: expected-subscribers:uint
+
+        If set, the publisher will wait until the number of expected subscribers
+        have connected.
+
+
 Auxiliary sink
 ==============
 
-- 
cgit v1.2.1