[SQL-CVS] r2416 - SQLObject/branches/0.7/docs

[<sub...@co...>]

Author: phd
Date: 2007-03-16 09:46:23 -0600 (Fri, 16 Mar 2007)
New Revision: 2416

Modified:
   SQLObject/branches/0.7/docs/SQLObject.txt
Log:
Documentation update - connection pooling and transactions.


Modified: SQLObject/branches/0.7/docs/SQLObject.txt
===================================================================
--- SQLObject/branches/0.7/docs/SQLObject.txt	2007-03-16 15:46:03 UTC (rev 2415)
+++ SQLObject/branches/0.7/docs/SQLObject.txt	2007-03-16 15:46:23 UTC (rev 2416)
@@ -1313,6 +1313,19 @@
 Similar to `MultipleJoin`, but returns just one object, not a list.
 
 
+Connection pooling
+------------------
+
+Connection object acquires a new low-level DB API connection from the pool
+and stores it; the low-level connection is removed from the pool;
+"releasing" means "return it to the pool". For single-threaded programs
+there is one connection in the pool.
+
+If the pool is empty a new low-level connection opened; if one has
+disabled pooling (by setting conn._pool = None) the connection will be
+closed instead of returning to the pool.
+
+
 Transactions
 ------------
 
@@ -1331,15 +1344,19 @@
 database connection, and `commit` and `rollback` just pass that
 message to the low-level connection.
 
-If you want to begin a new transaction after a .rollback() call .begin().
+One can call as much .commit()'s, but after a .rollback() one has to call
+.begin().
 
 If you want to use transactions you should also turn `_cacheValues`
-off, like:
+off, like::
 
     class Person(SQLObject):
-        _cacheValue = False
-        # ...
+        _cacheValues = False
 
+This, though, makes attribute access very slow (SQLObject queries database
+for an every attribute access). If one wants to set `_cacheValues = True`
+one has to synchronize objects between threads herself.
+
 Automatic Schema Generation
 ---------------------------