Connection Management

Here we exercise the connection management done by the DB class.

>>> from ZODB import DB
>>> from ZODB.MappingStorage import MappingStorage as Storage

Capturing log messages from DB is important for some of the examples:

>>> from zope.testing.loggingsupport import InstalledHandler
>>> handler = InstalledHandler('ZODB.DB')

Create a storage, and wrap it in a DB wrapper:

>>> st = Storage()
>>> db = DB(st)

By default, we can open 7 connections without any log messages:

>>> conns = [db.open() for dummy in range(7)]
>>> handler.records
[]

Open one more, and we get a warning:

>>> conns.append(db.open())
>>> len(handler.records)
1
>>> msg = handler.records[0]
>>> print msg.name, msg.levelname, msg.getMessage()
ZODB.DB WARNING DB.open() has 8 open connections with a pool_size of 7

Open 6 more, and we get 6 more warnings:

>>> conns.extend([db.open() for dummy in range(6)])
>>> len(conns)
14
>>> len(handler.records)
7
>>> msg = handler.records[-1]
>>> print msg.name, msg.levelname, msg.getMessage()
ZODB.DB WARNING DB.open() has 14 open connections with a pool_size of 7

Add another, so that it's more than twice the default, and the level rises to critical:

>>> conns.append(db.open())
>>> len(conns)
15
>>> len(handler.records)
8
>>> msg = handler.records[-1]
>>> print msg.name, msg.levelname, msg.getMessage()
ZODB.DB CRITICAL DB.open() has 15 open connections with a pool_size of 7

While it's boring, it's important to verify that the same relationships hold if the default pool size is overridden.

>>> handler.clear()
>>> st.close()
>>> st = Storage()
>>> PS = 2 # smaller pool size
>>> db = DB(st, pool_size=PS)
>>> conns = [db.open() for dummy in range(PS)]
>>> handler.records
[]

A warning for opening one more:

>>> conns.append(db.open())
>>> len(handler.records)
1
>>> msg = handler.records[0]
>>> print msg.name, msg.levelname, msg.getMessage()
ZODB.DB WARNING DB.open() has 3 open connections with a pool_size of 2

More warnings through 4 connections:

>>> conns.extend([db.open() for dummy in range(PS-1)])
>>> len(conns)
4
>>> len(handler.records)
2
>>> msg = handler.records[-1]
>>> print msg.name, msg.levelname, msg.getMessage()
ZODB.DB WARNING DB.open() has 4 open connections with a pool_size of 2

And critical for going beyond that:

>>> conns.append(db.open())
>>> len(conns)
5
>>> len(handler.records)
3
>>> msg = handler.records[-1]
>>> print msg.name, msg.levelname, msg.getMessage()
ZODB.DB CRITICAL DB.open() has 5 open connections with a pool_size of 2

We can change the pool size on the fly:

>>> handler.clear()
>>> db.setPoolSize(6)
>>> conns.append(db.open())
>>> handler.records  # no log msg -- the pool is bigger now
[]
>>> conns.append(db.open()) # but one more and there's a warning again
>>> len(handler.records)
1
>>> msg = handler.records[0]
>>> print msg.name, msg.levelname, msg.getMessage()
ZODB.DB WARNING DB.open() has 7 open connections with a pool_size of 6

Enough of that.

>>> handler.clear()
>>> st.close()

More interesting is the stack-like nature of connection reuse. So long as we keep opening new connections, and keep them alive, all connections returned are distinct:

>>> st = Storage()
>>> db = DB(st)
>>> c1 = db.open()
>>> c2 = db.open()
>>> c3 = db.open()
>>> c1 is c2 or c1 is c3 or c2 is c3
False

Let's put some markers on the connections, so we can identify these specific objects later:

>>> c1.MARKER = 'c1'
>>> c2.MARKER = 'c2'
>>> c3.MARKER = 'c3'

Now explicitly close c1 and c2:

>>> c1.close()
>>> c2.close()

Reaching into the internals, we can see that db's connection pool now has two connections available for reuse, and knows about three connections in all:

>>> pool = db._pools['']
>>> len(pool.available)
2
>>> len(pool.all)
3

Since we closed c2 last, it's at the top of the available stack, so will be reused by the next open():

>>> c1 = db.open()
>>> c1.MARKER
'c2'
>>> len(pool.available), len(pool.all)
(1, 3)
>>> c3.close()  # now the stack has c3 on top, then c1
>>> c2 = db.open()
>>> c2.MARKER
'c3'
>>> len(pool.available), len(pool.all)
(1, 3)
>>> c3 = db.open()
>>> c3.MARKER
'c1'
>>> len(pool.available), len(pool.all)
(0, 3)

What about the 3 in pool.all? We've seen that closing connections doesn't reduce pool.all, and it would be bad if DB kept connections alive forever.

In fact pool.all is a "weak set" of connections -- it holds weak references to connections. That alone doesn't keep connection objects alive. The weak set allows DB's statistics methods to return info about connections that are still alive.

>>> len(db.cacheDetailSize())  # one result for each connection's cache
3

If a connection object is abandoned (it becomes unreachable), then it will vanish from pool.all automatically. However, connections are involved in cycles, so exactly when a connection vanishes from pool.all isn't predictable. It can be forced by running gc.collect():

>>> import gc
>>> dummy = gc.collect()
>>> len(pool.all)
3
>>> c3 = None
>>> dummy = gc.collect()  # removes c3 from pool.all
>>> len(pool.all)
2

Note that c3 is really gone; in particular it didn't get added back to the stack of available connections by magic:

>>> len(pool.available)
0

Nothing in that last block should have logged any msgs:

>>> handler.records
[]

If "too many" connections are open, then closing one may kick an older closed one out of the available connection stack.

>>> st.close()
>>> st = Storage()
>>> db = DB(st, pool_size=3)
>>> conns = [db.open() for dummy in range(6)]
>>> len(handler.records)  # 3 warnings for the "excess" connections
3
>>> pool = db._pools['']
>>> len(pool.available), len(pool.all)
(0, 6)

Let's mark them:

>>> for i, c in enumerate(conns):
...     c.MARKER = i

Closing connections adds them to the stack:

>>> for i in range(3):
...     conns[i].close()
>>> len(pool.available), len(pool.all)
(3, 6)
>>> del conns[:3]  # leave the ones with MARKERs 3, 4 and 5

Closing another one will purge the one with MARKER 0 from the stack (since it was the first added to the stack):

>>> [c.MARKER for c in pool.available]
[0, 1, 2]
>>> conns[0].close()  # MARKER 3
>>> len(pool.available), len(pool.all)
(3, 5)
>>> [c.MARKER for c in pool.available]
[1, 2, 3]

Similarly for the other two:

>>> conns[1].close(); conns[2].close()
>>> len(pool.available), len(pool.all)
(3, 3)
>>> [c.MARKER for c in pool.available]
[3, 4, 5]

Reducing the pool size may also purge the oldest closed connections:

>>> db.setPoolSize(2)  # gets rid of MARKER 3
>>> len(pool.available), len(pool.all)
(2, 2)
>>> [c.MARKER for c in pool.available]
[4, 5]

Since MARKER 5 is still the last one added to the stack, it will be the first popped:

>>> c1 = db.open(); c2 = db.open()
>>> c1.MARKER, c2.MARKER
(5, 4)
>>> len(pool.available), len(pool.all)
(0, 2)

Next: when a closed Connection is removed from .available due to exceeding pool_size, that Connection's cache is cleared (this behavior was new in ZODB 3.6b6). While user code may still hold a reference to that Connection, once it vanishes from .available it's really not usable for anything sensible (it can never be in the open state again). Waiting for gc to reclaim the Connection and its cache eventually works, but that can take "a long time" and caches can hold on to many objects, and limited resources (like RDB connections), for the duration.

>>> st.close()
>>> st = Storage()
>>> db = DB(st, pool_size=2)
>>> conn0 = db.open()
>>> len(conn0._cache)  # empty now
0
>>> import transaction
>>> conn0.root()['a'] = 1
>>> transaction.commit()
>>> len(conn0._cache)  # but now the cache holds the root object
1

Now open more connections so that the total exceeds pool_size (2):

>>> conn1 = db.open()
>>> conn2 = db.open()
>>> pool = db._pools['']
>>> len(pool.all), len(pool.available)  # all Connections are in use
(3, 0)

Return pool_size (2) Connections to the pool:

>>> conn0.close()
>>> conn1.close()
>>> len(pool.all), len(pool.available)
(3, 2)
>>> len(conn0._cache)  # nothing relevant has changed yet
1

When we close the third connection, conn0 will be booted from .all, and we expect its cache to be cleared then:

>>> conn2.close()
>>> len(pool.all), len(pool.available)
(2, 2)
>>> len(conn0._cache)  # conn0's cache is empty again
0
>>> del conn0, conn1, conn2

Clean up.

>>> st.close()
>>> handler.uninstall()