indexamajig: Add --zmq-request

This (re-)adds the ability to get data via a request/reply socket.
See afcb7b568947c for when it was removed.

2 files changed, 29 insertions, 7 deletions

diff --git a/doc/articles/online.rst b/doc/articles/online.rst
index 84e037ca..6183d7eb 100644
--- a/doc/articles/online.rst
+++ b/doc/articles/online.rst
@@ -7,9 +7,10 @@ socket.  Use ``--zmq-input`` instead of ``--input`` or ``-i``.  An error will
 be generated if you use ``--zmq-input`` and ``--input``  or ``-i``
 simultaneously.
 
-Indexamajig assumes that the socket is a *pub/sub* socket.  You will also need
-to specify which message prefixes to subscribe to.  Use ``--zmq-subscribe`` for
-this::
+Indexamajig can use either a SUB (subscriber) or a REQ (request) socket.  The
+SUB socket type can be used for receiving data from OnDA/OM via the same
+mechanism that the OnDA/OM GUI uses.  In this case, you will also need to
+specify which message prefixes to subscribe to using ``--zmq-subscribe``::
 
   indexamajig --zmq-input=tcp://127.0.0.1:5002 \
               --zmq-subscribe=ondaframedata \
@@ -18,8 +19,24 @@ this::
 You can use ``--zmq-subscribe`` multiple times to subscribe to multiple message
 prefixes.
 
-The option ``--no-image-data`` will be honoured, if given.  This makes it
-possible to quickly check streaming data for "indexability".
+Note that this mode of operation does not combine well with multi-threading
+in inddxamajig - all worker processes will receive the same data!  For anything
+more than "taking a peek" at the data, use the REQ socket instead by using
+``--zmq-request`` instead of ``--zmq-subscribe``.  The argument to this option
+is the string which should be sent in the request message::
+
+  indexamajig --zmq-input=tcp://127.0.0.1:5002 \
+              --zmq-request=next \
+              -o output.stream -g Eiger.geom ...
+
+Because they represent completely different modes of operation, the two options
+``--zmq-request`` and ``--zmq-subscribe`` are mutually exclusive.
+
+In both cases, the option ``--no-image-data`` will be honoured, if given.  This
+makes it possible to quickly check streaming data for "indexability".  You will
+be able to do almost all of the usual downstream analysis operations on the
+resulting stream, except that attempting to merge it using partialator or
+process_hkl will result in zeroes everywhere.
 
 
 Data format
diff --git a/doc/man/indexamajig.1 b/doc/man/indexamajig.1
index 5b4e62d4..7045d8de 100644
--- a/doc/man/indexamajig.1
+++ b/doc/man/indexamajig.1
@@ -181,12 +181,17 @@ Read the detector geometry description from \fIfilename\fR.  See \fBman crystfel
 .PD
 Receive data over ZeroMQ from \fIaddress\fR.  In this version, the ZeroMQ data will be assumed to be serialised with MsgPack, but other formats might be added in future.  The options \fB--input\fR and \fB--zmq-input\fR are mutually exclusive - you must specify exactly one of them.  Example: \fB--zmq-input=tcp://127.0.0.1:5002\fR.
 .IP
-If you use this option, you should also use \fB--zmq-subscribe\fR to add a ZeroMQ subscription.
+If you use this option, you should also use either \fB--zmq-subscribe\fR to add a ZeroMQ subscription, or \fB--zmq-request\fR to define how to request data.
 
 .PD 0
 .IP \fB--zmq-subscribe=\fItag\fR
 .PD
-Subscribe to ZeroMQ message type \fItag\fR.  You can use this option multiple times to add multiple subscriptions.
+Subscribe to ZeroMQ message type \fItag\fR.  You can use this option multiple times to add multiple subscriptions.  This option and \fB--zmq-request\fR are mutually exclusive.
+
+.PD 0
+.IP \fB--zmq-request=\fImsg\fR
+.PD
+Request new data over ZeroMQ by sending string \fImsg\fR.  This will cause indexamajig's ZeroMQ socket to use REQ mode instead of SUB.  This option and \fB--zmq-subscribe\fR are mutually exclusive.
 
 .PD 0
 .IP \fB--basename\fR