MANARDB - API reference

This is the API reference. There is also an introduction to this library.

Abstract

The code is released under the Lisp Lesser GPL.

Download shortcut: manardb.tar.gz.

Download
The MANARDB dictionary
Acknowledgements

Download

MANARDB together with this documentation can be downloaded from manardb.tar.gz.

The MANARDB dictionary

[Macro]
doclass (var class-specifier &key fresh-instances reverse) declaration* statement* => result

For each object in the memory-mapped datastore of class denoted by
CLASS-SPECIFIER (evaluated), lexically bind VAR to a Lisp
object representing that object around BODY and execute it.

FRESH-INSTANCES (generalized boolean, not evaluated), if true means
means that a fresh Lisp object will be created for each datastore
object -- by default a single Lisp object is instantiated and it is
modified destructively to point to each object in the class.

REVERSE (generalized boolean, not evaluated), if true means that
objects will be iterated in order from newest to oldest. If false (default),
they are iterated from oldest to newest.

Also see dosubclasses.

[Function]
rewrite-gc root-objects-sequence &key progress verbose shared-classes base-shared-classes => result

An alternative, sloppier GC algorithm with a space complexity that is not proportional to the size of the datastore.

Creates a new datastore by copying each element of
ROOT-OBJECTS-SEQUENCE as if it were entirely self contained except for
any shared objects in SHARED-CLASSES.

Cannot handle pointers to the inside of arrays at all; they will be
recreated pointing to fresh objects. Note that arrays pointing to
complex objects (or any user defined classes) are stored as arrays of
mptrs, with each mptr pointing to the actual object; it is fine to
have pointers to these objects, because the actual objects are not
stored in the array.

[Macro]
with-transaction (&key message on-restart) declaration* statement* => result

Copy the datastore to a temporary directory; open the datastore
from this temporary directory and execute BODY. If, at the end of
BODY, the main datastore has had another transaction on it, then run
ON-RESTART and restart the procedure. Otherwise atomically replace
the main datastore.

Should be safe, as it uses lockfiles. The initial copy will retry if a
transaction occurs while it is being performed.

It is slow copying the datastore. (A better copy than
alexandria:copy-file should be easy to implement.)

The proposed reflink(2) system call would make a radically more
efficient implementation possible.

[Macro]
with-cached-slots slots instance declaration* statement* => result

Like with-slots, but each slot is only read from the datastore once.
It is written to the datastore immediately after every write, and the
cached version becomes the value written (not the value as serialised
and deserialised).

This is an optimization to stop repeatedly instantiating slots into
Lisp memory. Note that it also useful because it preserves
non-persistent slots of objects stored in SLOTS of INSTANCE over their
lexical scope.

[Function]
gc root-objects-sequence &key verbose collect-and-compact => result

Do a full and precise garbage collection over all objects in the memory mapped system. 
If COLLECT-AND-COMPACT is true, then unused objeccts are removed.

Uses at least two pointers of Lisp memory per object and more if
objects are densely referenced. See REWRITE-GC for a sloppier
alternative that does not need so much memory.

[Generic function]
lisp-object-to-mptr-impl object => result

Override this generic function to give an user-defined class an
alternative serialisation in the memory mapped datastore. Return the
mptr pointing to this serialisation.

Note that the serialisation for builtin types are inlined and cannot
be affected.

[Macro]
with-object-cache (name &key test) declaration* statement* => result

Lexically bind a function with NAME for BODY that, when passed an
object, will either instantiate a new memory mapped object for it, or
if the object is equal under TEST to a previous object passed to NAME,
will return the same memory mapped object.

[Macro]
defmmclass name direct-supers direct-slots &rest options => result

Define a memory mapped class, like defclass.

Automatically adds :metaclass mm-metaclass to options, if it is not
present, finalizes the class immediately, and puts in an assertion
that the class layout in the loaded datastore is compatible.

[Macro]
direct-slot-numeric-maref class object slot element-type index => result

Access element INDEX of an array of ELEMENT-TYPE that is stored in
slot SLOT of OBJECT, which is an instance of class CLASS, without
instantiating the array into the memory of the host Lisp
implementation.

[Function]
make-mm-fixed-string length &key value => result

Create a fixed length string object of size LENGTH; stores into it the string in VALUE if given.

A fixed length string allows string objects to be modified in the
datastore without allocating more space.

[Accessor]
mm-fixed-string-value mfs => result
(setf (mm-fixed-string-value mfs) string)

The string stored in the fixed length string MFS. If the string was cropped, then append ... to the stored value.

Can be set with setf. If the new value is too long then it will be silently cropped.

[Function]
clean-mmap-dir &optional dir => result

Unsafely remove all temporary directories from failed transactions
that were not cleaned up because the transactor crashed.

[Not tested or used.]

[Function]
mptr obj => result

If OBJ is already an integer, return it. If it is a memory mapped object, return the MPTR corresponding to it.
Otherwise, raise an error.

[Function]
close-all-mmaps => result

Closes the datastore, unmapping and closing all files. Afterwards, a new datastore can be opened in a different locaiton.

[Function]
meq a b => result

True iff either (eq a b) or A and B are both datastore objects
representing the same object in the datastore.

[Function]
mptr-to-lisp-object mptr => result

Deference the object at location MPTR in the memory mapped datastore and create a Lisp representation of it.

[Special variable]
*mmap-may-allocate*

If this is not true, and an attempt is made to extend a memory mapped region, an error will be signalled.

[Macro]
dosubclasses (var class-specifier &rest options) declaration* statement* => result

For the class itself and each subclass of the class denoted by CLASS-SPECIFIER (evaluated) run doclass.

[Function]
count-all-instances class => result

Return a count of the number of instances of the class denoted by CLASS and any subclasses of it.

[Function]
make-marray length &key initial-element initial-contents marray-class => result

Create a new marray (memory-mapped array) structure in the datastore, similarly to make-array.

[Function]
lisp-object-to-mptr obj => result

Stores the object OBJ in the memory mapped datastore and returns the mptr referring to it

[Function]
list-to-marray list => result

Converts a Lisp list to a memory-mapped array object; nil is converted to nil

[Function]
marray-to-list marray => result

Converts a memory mapped array to a Lisp list; nil is converted to nil

[Special variable]
*mmap-base-pathname*

The base path in which the datastore files are to be found.

[Function]
use-mmap-dir dir &key if-does-not-exist => result

Set the memory mapped datastore to map files inside DIR.

[Standard class]
marray

The base representation of a memory-mapped vector.

[Function]
retrieve-all-instances class => result

Returns a list of all instances of CLASS.

[Standard class]
mm-object

Base class for all memory mapped objects.

[Accessor]
marray-ref marray i => result
(setf (marray-ref marray i) new)

Like aref, but for memory mapped arrays

[Method]
marray-length (object marray) => result

automatically generated reader method

[Function]
wipe-all-mmaps => result

Delete all objects from all classes.

[Standard class]
mm-metaclass

Metaclass for memory mapped objects.

[Function]
print-all-mmaps &optional stream => result

Describe the state of the datastore

[Function]
open-all-mmaps => result

Maps the datastore into memory.

[Generic function]
marray-length object => result

Acknowledgements

This documentation was prepared with a modified version of DOCUMENTATION-TEMPLATE.

$Header: /usr/local/cvsrep/documentation-template/output.lisp,v 1.14 2008/05/29 08:23:37 edi Exp $

BACK TO THE MAIN PROJECT PAGE

MANARDB - API reference

Abstract

Contents

Download

The MANARDB dictionary

Acknowledgements