Common Lisp Package: ELEPHANT-DATA-STORE

Data stores should use this to get access to internal symbols of elephant that importers of elephant shouldn't see. Backends should also import elephant to get use-api generic function symbols, classes and globals

README:

FUNCTION

Public

DESERIALIZE (BS SC &OPTIONAL OID-ONLY)

Generic interface to serialization that dispatches based on the current Elephant version

DESERIALIZE-DATABASE-VERSION-VALUE (BS)

Deserializes the 3 integer list from buffer stream bs

DESERIALIZE-FROM-BASE64-STRING (X SC)

Decode a base64-string using the store controller's deserialize method

GET-USER-CONFIGURATION-PARAMETER

This function pulls a value from the key-value pairs stored in my-config.sexp so data stores can have their own pairs for appropriate customization after loading.

LISP-COMPARE-EQUAL

A lisp compare equal in same spirit as lisp-compare<. Case insensitive for strings.

LISP-COMPARE<

A comparison function that mirrors the ordering of the data stores for < on all sortable types. It does not provide ordering on non-sorted values other than by type class (i.e. not serialized lexical values)

LISP-COMPARE<=

A comparison function that mirrors the ordering of the data stores for <= on all sortable types. It does not provide ordering on non-sorted values other than by type class (i.e. not serialized lexical values)

MAKE-TRANSACTION-RECORD (SC TXN &OPTIONAL PRIOR)

Backends must use this to assign values to *current-transaction* binding

REGISTER-DATA-STORE-CON-INIT

Data stores must call this function during the loading/compilation process to register their initialization function for the tag name in *elephant-data-stores*. The initialization function returns a fresh instance of the data stores store-controller subclass

SERIALIZE (FROB BS SC)

Generic interface to serialization that dispatches based on the current Elephant version

SERIALIZE-DATABASE-VERSION-KEY (BS)

Given a buffer-stream, encode a key indicating the version using the constant +elephant-version+

SERIALIZE-DATABASE-VERSION-VALUE (VERSION BS)

Serializes a list containing three integers to the buffer stream bs

SERIALIZE-TO-BASE64-STRING (X SC)

Encode object using the store controller's serializer format, but encoded in a base64

SLOTS-AND-VALUES (O)

List of slot names followed by values for object

STRUCT-SLOTS-AND-VALUES (OBJECT)

List of slot names followed by values for structure object

TRANSACTION-OBJECT (TXNREC)

Get the backend-specific transaction object

TRANSACTION-STORE (TXNREC)

Get the store that owns the transaction from a transaction record

Undocumented

LOOKUP-DATA-STORE-CON-INIT

SCHEMA-CLASSNAME-KEYFORM

MACRO

Public

WITH-TRANSACTION ((&REST KEYARGS &KEY (STORE-CONTROLLER '*STORE-CONTROLLER*) (PARENT '*CURRENT-TRANSACTION*) (RETRIES '*DEFAULT-RETRIES*) &ALLOW-OTHER-KEYS) &BODY BODY)

Execute a body with a transaction in place. On success, the transaction is committed. Otherwise, the transaction is aborted. If the body deadlocks, the body is re-executed in a new transaction, retrying a fixed number of iterations. If nested, the backend must support nested transactions.

GENERIC-FUNCTION

Public

BUILD-BTREE (SC)

Construct a btree of the appropriate type corresponding to this store-controller.

BUILD-DUP-BTREE (SC)

Construct a btree of the appropriate type corresponding to this store-controller.

BUILD-INDEXED-BTREE (SC)

Construct a btree of the appropriate type corresponding to this store-controller.

CLOSE-CONTROLLER (SC)

Close the db handles and environment. Should be in a state where lisp could be shut down without causing an inconsistent state in the db. Also, the object could be used by open-controller to reopen the database

CONNECTION-IS-INDEED-OPEN (CONTROLLER)

Validate the controller and the db that it is connected to

CONTROLLER-ABORT-TRANSACTION (STORE-CONTROLLER TRANSACTION &KEY &ALLOW-OTHER-KEYS)

Abort an elephant transaction

CONTROLLER-COMMIT-TRANSACTION (STORE-CONTROLLER TRANSACTION &KEY &ALLOW-OTHER-KEYS)

Commit an elephant transaction

CONTROLLER-START-TRANSACTION (STORE-CONTROLLER &KEY &ALLOW-OTHER-KEYS)

Start an elephant transaction

COPY-SPEC (TYPE SRC TARG)

Copy files associated with spec from src to targ

DATABASE-VERSION (SC)

Data stores implement this to store the serializer version. The protocol requires that data stores report their database version. On new database creation, the database is written with the *elephant-code-version* so that is returned by database-version. If a legacy database does not have a version according to the method then it should return nil

DEFAULT-CLASS-ID (BASE-TYPE SC)

A method implemented by the store controller for providing fixed class ids for basic btree derivative types

DEFAULT-CLASS-ID-TYPE (ID SC)

A method implemented by the store controller which provides the type associated with a default id or nil if the id does not match

DELETE-SPEC (TYPE SPEC)

Delete the storage associated with spec

EXECUTE-TRANSACTION (STORE-CONTROLLER TXN-FN &REST REST &KEY &ALLOW-OTHER-KEYS)

This is an interface to the backend's transaction function. The body should be executed in a dynamic environment that protects against non-local exist, provides ACID properties for DB operations within the body and properly binds any relevant parameters.

GET-CON (INSTANCE)

This is used to find and validate the connection spec maintained for in-memory persistent objects. Should we re-open the controller from the spec if it's not cached? That might be dangerous so for now we error

NEXT-CID (SC)

Provides a unique class schema id's

NEXT-OID (SC)

Provides a persistent source of unique id's

OPEN-CONTROLLER (SC &KEY RECOVER RECOVER-FATAL THREAD &ALLOW-OTHER-KEYS)

Opens the underlying environment and all the necessary database tables. Different data stores may use different keys so all methods should &allow-other-keys. There are three standard keywords: :recover, :recover-fatal and :thread. Recover means that recovery should be checked for or performed on startup. Recover fatal means a full rebuild from log files is requested. Thread merely indicates to the data store that it is a threaded application and any steps that need to be taken (for example transaction implementation) are taken. :thread is usually true.

PERSISTENT-SLOT-BOUNDP (SC INSTANCE NAME)

Data store specific slot bound test function

PERSISTENT-SLOT-MAKUNBOUND (SC INSTANCE NAME)

Data store specific slot makunbound handler

PERSISTENT-SLOT-READER (SC INSTANCE NAME &OPTIONAL OIDS-ONLY)

Data store specific slot reader function

PERSISTENT-SLOT-WRITER (SC NEW-VALUE INSTANCE NAME)

Data store specific slot writer function

RESERVED-OID-P (SC OID)

Is this OID reserved by the controller? GC doesn't touch

TEMP-SPEC (TYPE SPEC)

Create a temporary specification with source spec as hint

Undocumented

CACHE-INSTANCE (SC OBJ)

ENSURE-INDEX (IBT IDXNAME &KEY KEY-FORM POPULATE)

FLUSH-INSTANCE-CACHE (SC)

GET-CACHED-INSTANCE (SC OID)

INITIALIZE-SERIALIZER (SC)

OID->SCHEMA-ID (OID SC)

UNCACHE-INSTANCE (SC OID)

UP-TO-DATE-P (SC)

SLOT-ACCESSOR

Public

CONTROLLER-DESERIALIZE (OBJECT)

Contains the entry point for the specific serializer to be called by elephant::deserialize

SETFCONTROLLER-DESERIALIZE (NEW-VALUE OBJECT)

Contains the entry point for the specific serializer to be called by elephant::deserialize

CONTROLLER-INSTANCE-TABLE (OBJECT)

Contains btree of oid to class ids

CONTROLLER-SCHEMA-TABLE (OBJECT)

Schema id to schema database table

CONTROLLER-SERIALIZE (OBJECT)

Accessed by elephant::serialize to get the entry point to the default serializer or to a data store specific serializer

SETFCONTROLLER-SERIALIZE (NEW-VALUE OBJECT)

Accessed by elephant::serialize to get the entry point to the default serializer or to a data store specific serializer

CONTROLLER-SERIALIZER-VERSION (OBJECT)

Governs the default behavior regarding which serializer version the current elephant core is using. Data stores can override by creating a method on initialize-serializer.

SETFCONTROLLER-SERIALIZER-VERSION (NEW-VALUE OBJECT)

Governs the default behavior regarding which serializer version the current elephant core is using. Data stores can override by creating a method on initialize-serializer.

CONTROLLER-SPEC (OBJECT)

Data store initialization functions are expected to initialize :spec on the call to make-instance

SETFCONTROLLER-SPEC (NEW-VALUE OBJECT)

Data store initialization functions are expected to initialize :spec on the call to make-instance

CURSOR-INITIALIZED-P (OBJECT)

Predicate indicating whether the btree in question is initialized or not. Initialized means that the cursor has a legitimate position, not that any initialization action has been taken. The implementors of this abstract class should make sure that happens under the sheets... Cursors are initialized when you invoke an operation that sets them to something (such as cursor-first), and are uninitialized if you move them in such a way that they no longer have a legimtimate value.

SETFCURSOR-INITIALIZED-P (NEW-VALUE OBJECT)

Predicate indicating whether the btree in question is initialized or not. Initialized means that the cursor has a legitimate position, not that any initialization action has been taken. The implementors of this abstract class should make sure that happens under the sheets... Cursors are initialized when you invoke an operation that sets them to something (such as cursor-first), and are uninitialized if you move them in such a way that they no longer have a legimtimate value.

OID (OBJECT)

All persistent objects have an oid

SETFOID (NEW-VALUE OBJECT)

All persistent objects have an oid

Undocumented

CONTROLLER-DATABASE-VERSION (OBJECT)

SETFCONTROLLER-DATABASE-VERSION (NEW-VALUE OBJECT)

CURSOR-BTREE (OBJECT)

SETFCURSOR-BTREE (NEW-VALUE OBJECT)

CURSOR-OID (OBJECT)

SETFCURSOR-OID (NEW-VALUE OBJECT)

SCHEMA-CLASSNAME (OBJECT)

SETFSCHEMA-CLASSNAME (NEW-VALUE OBJECT)

SLOT-DEFINITION-NAME (SLOT-DEFINITION)

SETFSLOT-DEFINITION-NAME (NEW-VALUE SLOT-DEFINITION)

VARIABLE

Public

*CURRENT-TRANSACTION*

The transaction which is currently in effect.

*ELEPHANT-CODE-VERSION*

The current database version supported by the code base

Undocumented

*DBCONNECTION-SPEC*