update docs

docs/tutorial/efficient-dataflow.md

@@ -155,6 +155,8 @@ The above script builds a DataFlow which produces jpeg-encoded ImageNet data.
 We store the jpeg string as a numpy array because the function `cv2.imdecode` later expect this format.
 Please note we can only use 1 prefetch process to speed up. If `nr_proc>1`, `ds1` will take data
 from several forks of `ds0`, then neither the content nor the order of `ds1` will be the same as `ds0`.
+See [documentation](http://localhost:8000/modules/dataflow.html#tensorpack.dataflow.PrefetchDataZMQ)
+about caveats of `PrefetchDataZMQ`.
 
 It will generate a database file of 140G. We build a DataFlow to read this LMDB file sequentially:
 ```

tensorpack/callbacks/monitor.py

@@ -151,6 +151,7 @@ class Monitors(Callback):
     def put_image(self, name, val):
         """
         Put an image.
+
         Args:
             name (str):
             val (np.ndarray): 2D, 3D (HWC) or 4D (NHWC) numpy array of images

tensorpack/dataflow/prefetch.py

@@ -126,10 +126,15 @@ class PrefetchDataZMQ(ProxyDataFlow):
     collect datapoints from `ds` in each process by ZeroMQ IPC pipe.
 
     Note:
-        1. The underlying dataflow worker will be forked multiple times When ``nr_proc>1``.
-           As a result, unless the underlying dataflow is fully shuffled, the data distribution
-           produced by this dataflow will be different.
-           (e.g. you are likely to see duplicated datapoints at the beginning)
+        1. An iterator cannot run faster automatically -- the underlying dataflow worker
+           will be forked ``nr_proc`` times. As a result, we have the following
+           guarantee on the dataflow correctness:
+
+           a. When ``nr_proc=1``, the dataflow produces the same data as ``ds`` in the same order.
+           b. When ``nr_proc>1``, the dataflow produces the same distribution
+              of data as ``ds`` if each sample from ``ds`` is i.i.d. (e.g. fully shuffled).
+              You probably only want to use it for training.
+
         2. Once :meth:`reset_state` is called, this dataflow becomes not fork-safe.
            i.e., if you fork an already reset instance of this dataflow,
            it won't be usable in the forked process.