Add comment

1 files changed, 8 insertions, 0 deletions

diff --git a/synapse/util/async.py b/synapse/util/async.py
index 408c86be91..14a3dfd43f 100644
--- a/synapse/util/async.py
+++ b/synapse/util/async.py
@@ -164,6 +164,14 @@ class Linearizer(object):
 
     @defer.inlineCallbacks
     def queue(self, key):
+        # If there is already a deferred in the queue, we pull it out so that
+        # we can wait on it later.
+        # Then we replace it with a deferred that we resolve *after* the
+        # context manager has exited.
+        # We only return the context manager after the previous deferred has
+        # resolved.
+        # This all has the net effect of creating a chain of deferreds that
+        # wait for the previous deferred before starting their work.
         current_defer = self.key_to_defer.get(key)
 
         new_defer = defer.Deferred()