[CalendarServer-changes] [8156] CalendarServer/branches/users/glyph/shared-pool-take2/twext/ enterprise/ienterprise.py

[source_changes at macosforge.org]

Revision: 8156
          http://trac.macosforge.org/projects/calendarserver/changeset/8156
Author:   glyph at apple.com
Date:     2011-10-10 08:01:29 -0700 (Mon, 10 Oct 2011)
Log Message:
-----------
start documenting commandBlock, which until now has been implicit

Modified Paths:
--------------
    CalendarServer/branches/users/glyph/shared-pool-take2/twext/enterprise/ienterprise.py

Modified: CalendarServer/branches/users/glyph/shared-pool-take2/twext/enterprise/ienterprise.py
===================================================================
--- CalendarServer/branches/users/glyph/shared-pool-take2/twext/enterprise/ienterprise.py	2011-10-10 14:50:37 UTC (rev 8155)
+++ CalendarServer/branches/users/glyph/shared-pool-take2/twext/enterprise/ienterprise.py	2011-10-10 15:01:29 UTC (rev 8156)
@@ -46,12 +46,9 @@
 
 
 
-class IAsyncTransaction(Interface):
+class ISQLExecutor(Interface):
     """
-    Asynchronous execution of SQL.
-
-    Note that there is no {begin()} method; if an L{IAsyncTransaction} exists,
-    it is assumed to have been started.
+    Base SQL-execution interface, for a group of commands or a transaction.
     """
 
     paramstyle = Attribute(
@@ -87,6 +84,15 @@
         """
 
 
+
+class IAsyncTransaction(ISQLExecutor):
+    """
+    Asynchronous execution of SQL.
+
+    Note that there is no {begin()} method; if an L{IAsyncTransaction} exists at
+    all, it is assumed to have been started.
+    """
+
     def commit():
         """
         Commit changes caused by this transaction.
@@ -105,7 +111,56 @@
         """
 
 
+    def commandBlock():
+        """
+        Create an object which will cause the commands executed on it to be
+        grouped together.
 
+        This is useful when using database-specific features such as
+        sub-transactions where order of execution is importnat, but where
+        application code may need to perform I/O to determine what SQL, exactly,
+        it wants to execute.  Consider this fairly contrived example for an
+        imaginary database::
+
+            def storeWebPage(url, block):
+                block.execSQL("BEGIN SUB TRANSACTION")
+                got = getPage(url)
+                def gotPage(data):
+                    block.execSQL("INSERT INTO PAGES (TEXT) VALUES (?)", [data])
+                    block.execSQL("INSERT INTO INDEX (TOKENS) VALUES (?)",
+                                 [tokenize(data)])
+                    lastStmt = block.execSQL("END SUB TRANSACTION")
+                    block.end()
+                    return lastStmt
+                return got.addCallback(gotPage)
+            gatherResults([storeWebPage(url, txn.commandBlock())
+                          for url in urls]).addCallbacks(
+                            lambda x: txn.commit(), lambda f: txn.abort()
+                          )
+
+        This fires off all the C{getPage} requests in parallel, and prepares all
+        the necessary SQL immediately as the results arrive, but executes those
+        statements in order.  In the above example, this makes sure to store the
+        page and its tokens together, another use for this might be to store a
+        computed aggregate (such as a sum) at a particular point in a
+        transaction, without sacrificing parallelism.
+
+        @rtype: L{ICommandBlock}
+        """
+
+
+
+class ICommandBlock(ISQLExecutor):
+    """
+    This is a block of SQL commands that are grouped together.
+    """
+
+    def end():
+        """
+        """
+
+
+
 class IDerivedParameter(Interface):
     """
     A parameter which needs to be derived from the underlying DB-API cursor;
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20111010/67993684/attachment-0001.html>