From 639cd07d6d4e22e3413349bbd3bfb33db37a8d2f Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Thu, 7 Apr 2016 14:24:12 +0100
Subject: [PATCH] Add comment

---
 synapse/util/async.py | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/synapse/util/async.py b/synapse/util/async.py
index 408c86be9..14a3dfd43 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()