relstorage.cache.local_client#

interface ICachedValue[source]#

Extends: relstorage.cache.interfaces.ILRUEntry

Data stored in the cache for a single OID.

This may be a single (state, tid) pair, or it may be multiple such pairs, representing evolution of the object.

Memory and time efficiency both matter. These objects do not know their own OID, just the state and tid.

Freezing objects

For any given OID, one TID may be frozen. It may then be looked up without knowing its actual TID (using a TID of None). This is useful for objects that do not change. Invalidations of frozen states happen automatically during the MVCC vacuuming process:

  • Freezing happens after a poll, when we have determined that an object has not changed within the range of transactions visible to all database viewers. The index entry is removed, and we begin looking for it at None.

    At this time, any older states cached for the object are removed. By definition, there can be no newer states, so only one state is accessible. (Of course, if we’ve just completed a transaction and not yet polled, then that’s not strictly true; there could be cached data from the future not yet visible to any viewers.)

  • If an object previously frozen is changed, we see that in our index and won’t ask for frozen states anymore.

    If we then load the new state from the DB, we cache it, leaving it with two cached states. Older viewers unaware of the change and accessing the database prior to it, can still use the frozen revision.

    Eventually that index entry reaches the end of its lifetime. If the object has not changed again, we will freeze it. This will discard the older frozen value and replace it with a new one. If it has changed again, we will invalidate the cache for anything older than that TID, which includes the first frozen state.

The implementation and usage of frozen objects is contained entirely within this module. Clients are then responsible for making sure that the returned tid, if any, is within their viewing range.

weight#

The cost (size) of this cached value. (required? False)

max_tid#

The newest TID cached for the object. (required? False)

newest_value#

The (state, tid) pair that is the newest.

get_if_tid_matches(tid)#

Return the (state, tid) for the given TID.

A special value of None matches any previously frozen TID.

If no TID matches, returns None.

freeze_to_tid(tid)#

Mark the given TID, if it exists, as frozen.

Returns a new value to store in the cache. If it returns None, this entry is removed from the cache (because the TID didn’t match, and must have been older.)

with_later(value)#

Add the (state, tid) (another ICachedValue) to the list of cached entries. Return the new value to place in the cache.

discarding_tids_before(tid)#

Remove the tid, and anything older, from the list of cached entries.

Return the new value to place in the cache. Return None if all values were removed and the cached entry should be removed.