[ZODB-Dev] ZODB _v_ attributes are tricky

[Shane Hathaway]

Tim Peters wrote:
> I would love it if someone who believes they understand the intricacies of
> _v_ attributes wrote comprehensive docs.  I don't know of adequate docs for
> them now, and can't make time in the near future to reverse-engineer what
> the actual truth is from staring at the code.
> 
> Plain English text would be fine.  If we had such a writeup, it would be
> easy then to LaTeX-ify it and merge it into the ZODB/ZEO Programming Guide
> (which is generated from LaTeX source):

Here's a rough draft.

Frequently, a program needs to perform an expensive computation based on 
the state of a single ZODB object.  For example, before a Zope page 
template executes, it must be parsed and compiled into a series of 
bytecodes.  To do this on every request would be expensive.  The page 
template could store the bytecode, but page template bytecode often 
contains objects that cannot be pickled.

Therefore, ZODB provides a simple mechanism for caching.  If you set an 
attribute beginning with "_v_" on a persistent object, ZODB does not 
store that attribute.  It is called a volatile attribute.  It is not 
included in the stored pickle, and other connections to the same 
database do not see it.  ZODB destroys volatile attributes only when 
unloading objects.  ZODB unloads objects after another connection 
changes them.  Also, the ZODB garbage collector unloads objects at the 
end of transactions.

This means that volatile attributes often live beyond the duration of a 
transaction.  It is safe to compute something involving only one ZODB 
object and store the result as a volatile attribute of that same object, 
since changes by other connections will cause the object to be unloaded, 
automatically destroying the volatile attribute.  However, if the 
computation is based on the state of other objects, there is a good 
chance the volatile attribute's value will fall out of sync with the 
state of the other objects.  If an application needs to cache a value 
that depends on multiple objects, it should provide its own mechanisms 
for keeping that value in sync.

Shane