API Changes

This article describes the changes to the ZODB API that are part of the new pickle cache implementation. You probably want to read this documentation about why a change was needed, the FAQ, and implementation notes before continuing. See also these release notes.

This document could be considered as an appendix to the UML Model at http://www.zope.org/Documentation/Developer/Models/ZODB, however it also documents changes to things not previously documented.

Changes

1. Caches have a new attribute cache_non_ghost_count which contains the number of items in the cache excluding ghosts. This is a good measure of memory usage, and is the main control input to incremental garbage collector. len(cache) still includes all objects, including ghosts, in its total.
2. Caches have a new attribute cache_drain_resistance which controls how quickly the cache size will drop when it is lower than the configured size. A value of zero means it will not drop below the configured size. Otherwise, it will remove cache_non_ghost_count/cache_drain_resistance items from the cache.
3. This cache no longer uses any time-related values. cache_age still exists as a writable attribute, but will always have the value 0 when read. The functions full_sweep and minimize still have the optional age parameters, but it is not used.
4. The cache API has two functions full_sweep and minimize which previously made different compromises between thoroughness and performance. In the new implementation both functions do the same thing.
5. Cache attribute data now gives a copy of the cache content.
6. Caches have a new attribute lru_items which returns a list of (oid,object) non-ghost items in least-recently-used order.
7. Any persistent classes that previously included code self->state=cPersistent_GHOST_STATE; should be changed to PER_GHOSTIFY(self);