Why do we increment the counter after the insert?

This patchs adds a comment explaining why the counter in the mongodb
driver is incremented *after* the insert happens.

Change-Id: I143c8e214736eec4261e09561824088775eb6ac1

zaqar/queues/storage/mongodb/messages.py

@@ -514,6 +514,13 @@ class MessageController(storage.Message):
         collection = self._collection(queue_name, project)
 
         # Set the next basis marker for the first attempt.
+        #
+        # Note that we don't increment the counter right away because
+        # if 2 concurrent posts happen and the one with the higher counter
+        # ends before the one with the lower counter, there's a window
+        # where a client paging through the queue may get the messages
+        # with the higher counter and skip the previous ones. This would
+        # make our FIFO guarantee unsound.
         next_marker = self._queue_ctrl._get_counter(queue_name, project)
 
         # Unique transaction ID to facilitate atomic batch inserts