backend: document pipeline_dispatch behavior

It's tricky, but possible to get right (at least for list_keys)

1 files changed, 4 insertions, 1 deletions

diff --git a/lib/mogilefs/backend.rb b/lib/mogilefs/backend.rb
index 93bcfe6..596e320 100644
--- a/lib/mogilefs/backend.rb
+++ b/lib/mogilefs/backend.rb
@@ -209,7 +209,10 @@ class MogileFS::Backend
   end
 
   # dispatch a request like do_request, but queue +block+ for execution
-  # upon receiving a response.
+  # upon receiving a response.  It is the users' responsibility to ensure
+  # &block is executed in the correct order.  Trackers with multiple
+  # queryworkers are not guaranteed to return responses in the same
+  # order they were requested.
   def pipeline_dispatch(cmd, args, &block) # :nodoc:
     request = make_request(cmd, args)
     timeout = @timeout