A thread-safe, process-safe object database class which uses the native
file system as its back end and allows multiple file formats.
The root directory of the db, to which paths are relative.
Create a new database object that accesses dir. Makes sure that
the directory exists on disk, but doesn't create or open any other files.
Create a new database object that accesses path relative to the
database directory. A process can have any number of dbs accessing
overlapping dirs. The cost of creating an additional db is very low; its
state is just the dir. Caching is done in structures owned by the Database class itself.
Convert a relative path (relative to the db dir) to an absolute path.
Convert an absolute path to a unique key for the cache, raising
MissingFileError if the file does not exist.
Convert an absolute path to a unique key for the cache, creating the file
if it does not exist. Raises CreateFileError if it can't be created.
For housekeeping, so that stale entries don't result in unused, but
uncollectable, CacheEntry objects.
Can be called occasionally to reduce memory footprint, esp. if cached
objects are large and infrequently used.
Abort the current transaction (browse,
edit, replace, or delete, roll back the state of the object,
and return nil from the transaction.
In the browse case, the only effect is
to end the transaction.
Note that any exception that breaks out of the transaction will also abort
the transaction, and be re-raised.
Called when browse doesn't find
anything at the path. The original caller's block is available to be
Called when edit doesn't find anything
at the path. The original caller's block is available to be yielded to.
The default behavior of both default_edit and default_browse. Raises MissingObjectError
by default, but it can yield to the original block.
Called when fetch doesn't find anything
at the path. Default definition just returns nil.
Browse the object. Yields the object to the caller's block, and returns the
value of the block. Changes to the object are not persistent, but should be
avoided (they will be seen by other threads, but only in the current
process, and only until the cache is cleared).
Edit the object in place. Changes to the yielded object made within the
caller's block become persistent. Returns the value of the block. Note that
assigning to the block argument variable does not change the state of the
object. Use destructive methods on the object.
Replace the yielded object (or nil) with the return value of the block.
Returns the object that was replaced. Use replace instead of edit when
accessing db over a drb connection. Use replace instead of insert if the
path needs to be protected while the object is prepared for insertion. Note
that (unlike edit) destructive methods
on the object do not persistently change the state of the object, unless
the object is the return value of the block.
Insert the object, replacing anything at the path. Returns the object. (The
object remains a local copy, distinct from the one which will be
given out when accessing the path through database transactions.)
Delete the object from the db. If a block is given, yields the object (or
nil if none) before deleting it from the db (but before releasing the lock
on the path), and returns the value of the block. Otherwise, just returns
the object (or nil).
Fetch a copy of the object at the path for private use by the
current thread/process. (The copy is a deep copy.)
Returns object read from f (must be open for reading).
Writes object to f (must be open for writing).
Create a hard link, using File.link. The names
are relative to the database's path.
Create a symbolic link, using File.symlink. The
names are relative to the database's path.