Revert of Cherry-pick buildbot 7d31a0593e2e207289511c10f68a8bc4ba13b759:

third_party/buildbot_8_4p1/buildbot/db/pool.py

Index: third_party/buildbot_8_4p1/buildbot/db/pool.py
diff --git a/third_party/buildbot_8_4p1/buildbot/db/pool.py b/third_party/buildbot_8_4p1/buildbot/db/pool.py
index 5482e1196ecfddca6a42f970da878aea1cd2bee5..ff5e67eea7bd89802dc7db9b0b7e1585d39771b8 100644
--- a/third_party/buildbot_8_4p1/buildbot/db/pool.py
+++ b/third_party/buildbot_8_4p1/buildbot/db/pool.py
@@ -21,6 +21,14 @@
 
 
 class DBThreadPool(threadpool.ThreadPool):
+    """
+    A pool of threads ready and waiting to execute queries.
+
+    If the engine has an C{optimal_thread_pool_size} attribute, then the
+    maxthreads of the thread pool will be set to that value.  This is most
+    useful for SQLite in-memory connections, where exactly one connection
+    (and thus thread) should be used.
+    """
 
     running = False
 
@@ -34,14 +42,8 @@
 
     def __init__(self, engine):
         pool_size = 5
-
-        # If the engine has an C{optimal_thread_pool_size} attribute, then the
-        # maxthreads of the thread pool will be set to that value.  This is
-        # most useful for SQLite in-memory connections, where exactly one
-        # connection (and thus thread) should be used.
         if hasattr(engine, 'optimal_thread_pool_size'):
             pool_size = engine.optimal_thread_pool_size
-
         threadpool.ThreadPool.__init__(self,
                         minthreads=1,
                         maxthreads=pool_size,
@@ -76,6 +78,12 @@
         self._stop()
 
     def do(self, callable, *args, **kwargs):
+        """
+        Call C{callable} in a thread, with a Connection as first argument.
+        Returns a deferred that will indicate the results of the callable.
+
+        Note: do not return any SQLAlchemy objects via this deferred!
+        """
         def thd():
             conn = self.engine.contextual_connect()
             if self.__broken_sqlite: # see bug #1810
@@ -90,6 +98,11 @@
         return threads.deferToThreadPool(reactor, self, thd)
 
     def do_with_engine(self, callable, *args, **kwargs):
+        """
+        Like L{do}, but with an SQLAlchemy Engine as the first argument.  This
+        is only used for schema manipulation, and is not used at master
+        runtime.
+        """
         def thd():
             if self.__broken_sqlite: # see bug #1810
                 self.engine.execute("select * from sqlite_master")