NAME

Class::Persist::Cache

DESCRIPTION

This is an object cache for Class::Persist. It stores weak references to every object retrieved from the database, and Class::Persist will attempt to return an object from the cache in preference to returning another instance of the database object. This should mean that there is only ever one instance of any given persistantable object around at any time.

You won't for the most part have to worry about this class. It's documented here so you can either pull objects from the cache explicitly, which is not recommended, or so you can subclass the object cache for some reason - for instance, in a web application, you may want the cache to be per-session or per-request, to to perform some end-of-request cleanup on the cache.

SYNOPSIS

EXCEPTIONS

Class::Persist::Error::Cache (a Class::Persist::Error)

all exceptions thrown by the cache are subclasses of this error

Class::Persist::Error::Cache::CannotStore (a Class::Persist::Error::Cache)

the object store cannot store the passed object - it's not a Class::Persist object, or there's already a similar object in the store.

Class::Persist::Error::Cache::CannotRemove (a Class::Persist::Error::Cache)

the object passed to the remove() function cannot be removed

METHODS

instance()

Naturally, the singleton cache is itself a singleton. This method should return the instance of the cache.

object_store()

Returns the hashref that we keep all the objects in. In this implementation, the store is inside the Cache singleton, not package-level.

store( object )

Store an object by its oid. This method will not store a non-Class::Persist object. You can pass Proxies to store() and they will be stored, unless there is a 'real' object with that oid in the store. store() returns the object that is in the store - this is not nessecarily the object that you told it to store.

store() performs some sanity checking. If we already know about an object with the oid of the thing we're trying to store, store() tries very hard to ensure that there is only one definitive copy. If you're trying to store a proxy, and we know about a real object, store() will return the real object from the store. If you're trying to store a real object and store only knows about a proxy, store will inflate the proxy based on the real object, and return the object from the store again, so that other references to that object now have an inflated object. Storing a proxy over a proxy just returns the proxy from the store.

Storing the exact same object twice is safe, obviously. The nasty case arises when you're trying to store two 'real' objects with the same oid. Under normal usage, this should never arise, and I'm very interested in any test case you can produce that returns two different objects with the same oid. If you try to store an object that is not in the store, but has the same oid as some other object in the store, an exception will be throw. This should not ever happen.

For this reason, in Class::Persist we are very careful to return the object that the store() method returns, as this is the singleton version of that oid, and you should too.

Things are stored in the object_store hash, and the references to them are weakened, to avoid memory leaks. If you want a given object from the database to stay around, you must hold a reference to it yourself.

remove( object )

Remove an object from the store. Throws an exception if the object isn't a class persist object, or if the object you're trying to remove is not the same object as the one for that oid already in the store.

get( id )

returns the object from the store with the given ID, or undef if the id does not correspond to an object in the store.

all_ids()

returns a list of all the oids that the object store knows about.

tidy()

removes all the keys that point to undef values. Why not?

wipe_cache()

Resets the object cache. This should be considered very dangerous, as if there are any other things holding references to objects in the cache, these objects won't go away, and you'll get duplicate objects, etc.

proxy_all()

converts every object in the cache that is from the database, to a Class::Persist::Proxy. This might be evil, I'm not sure. The objects won't be stored.

store_all()

stores all the objects in the cache. This will be slow, so watch it.

SEE ALSO

Class::Persist

AUTHOR

Tom Insam, tinsam@fotango.com