# sqlobject.cache module

This implements the instance caching in SQLObject. Caching is relatively aggressive. All objects are retained so long as they are in memory, by keeping weak references to objects. We also keep other objects in a cache that doesn’t allow them to be garbage collected (unless caching is turned off).

class `sqlobject.cache.``CacheFactory`(cullFrequency=100, cullFraction=2, cache=True)

  Bases: `object`

  CacheFactory caches object creation. Each object should be referenced by a single hashable ID (note tuples of hashable values are also hashable).

  `allIDs`()

    Returns the IDs of all objects in the cache.

  `clear`()

    Removes everything from the cache. Warning! This can cause duplicate objects in memory.

  `created`(id, obj)

    Inserts and object into the cache. Should be used when no one else knows about the object yet, so there cannot be any object already in the cache. After a database INSERT is an example of this situation.

  `cull`()

    Runs through the cache and expires objects

    E.g., if `cullFraction` is 3, then every third object is moved to the ‘expired’ (aka weakref) cache.

  `expire`(id)

    Expires a single object. Typically called after a delete. Doesn’t even keep a weakref. (@@: bad name?)

  `expireAll`()

    Expires all objects, moving them all into the expired/weakref cache.

  `finishPut`()

    Releases the lock that is retained when .get() is called and returns None.

  `get`(id)

    This method can cause deadlocks! tryGet is safer

    This returns the object found in cache, or None. If None, then the cache will remain locked! This is so that the calling function can create the object in a threadsafe manner before releasing the lock. You should use this like (note that `cache` is actually a CacheSet object in this example):

        obj = cache.get(some_id, my_class)
        if obj is None:
            try:
                obj = create_object(some_id)
                cache.put(some_id, my_class, obj)
            finally:
                cache.finishPut(cls)

    This method checks both the main cache (which retains references) and the ‘expired’ cache, which retains only weak references.

  `getAll`()

    Return all the objects in the cache.

  `put`(id, obj)

    Puts an object into the cache. Should only be called after .get(), so that duplicate objects don’t end up in the cache.

  `tryGet`(id)

    This returns None, or the object in cache.

class `sqlobject.cache.``CacheSet`(*args, **kw)

  Bases: `object`

  A CacheSet is used to collect and maintain a series of caches. In SQLObject, there is one CacheSet per connection, and one Cache in the CacheSet for each class, since IDs are not unique across classes. It contains methods similar to Cache, but that take a `cls` argument.

  `allIDs`(cls)
  `allSubCaches`()
  `allSubCachesByClassNames`()
  `clear`(cls=None)
  `created`(id, cls, obj)
  `expire`(id, cls)
  `finishPut`(cls)
  `get`(id, cls)
  `getAll`(cls=None)

    Returns all instances in the cache for the given class or all classes.

  `put`(id, cls, obj)
  `tryGet`(id, cls)
  `tryGetByName`(id, clsname)
  `weakrefAll`(cls=None)

    Move all objects in the cls (or if not given, then in all classes) to the weakref dictionary, where they can be collected.