[elephant-cvs] CVS elephant/doc
ieslick
ieslick at common-lisp.net
Thu Apr 12 02:47:23 UTC 2007
Update of /project/elephant/cvsroot/elephant/doc
In directory clnet:/tmp/cvs-serv28241/doc
Modified Files:
elephant.texinfo installation.texinfo make-ref.lisp
reference.texinfo scenarios.texinfo tutorial.texinfo
user-guide.texinfo
Log Message:
Mostly documentation edits + fixing copyright in all source files
--- /project/elephant/cvsroot/elephant/doc/elephant.texinfo 2007/04/01 14:33:29 1.7
+++ /project/elephant/cvsroot/elephant/doc/elephant.texinfo 2007/04/12 02:47:23 1.8
@@ -123,5 +123,4 @@
@uref{http://www.common-lisp.net/project/elephant/}) and submit a
patch.
-
@bye
--- /project/elephant/cvsroot/elephant/doc/installation.texinfo 2007/04/04 15:28:28 1.8
+++ /project/elephant/cvsroot/elephant/doc/installation.texinfo 2007/04/12 02:47:23 1.9
@@ -198,6 +198,8 @@
(:use :common-lisp :elephant))
@end lisp
+The symbols that are imported are captured in @ref{User API Reference}
+
@subsection Opening a Store
As discussed in the tutoral, you need to open a store to begin using
@@ -485,11 +487,11 @@
If you want to compile the documentation youself, for example, if you can
think of a way to improve this manual, then you will do something similar
to this in a shell or command-line prompt:
- at code
+ at lisp
cd doc
make
make pdf
- at end code
+ at end lisp
This process will populate the ``./includes'' directory with references
automatically extracted from the list code. It will then compile the
--- /project/elephant/cvsroot/elephant/doc/make-ref.lisp 2007/04/02 00:51:06 1.7
+++ /project/elephant/cvsroot/elephant/doc/make-ref.lisp 2007/04/12 02:47:23 1.8
@@ -1,5 +1,5 @@
(require 'asdf)
-(asdf:operate 'asdf:load-op 'elephant)
+(asdf:operate 'asdf:load-op 'elephant :force t)
(load (merge-pathnames
#p"src/elephant/query"
(asdf:component-pathname (asdf:find-system 'elephant))))
@@ -29,12 +29,13 @@
(setf (controller-spec sc) nil)
(make-instance 'elephant::persistent-collection :sc sc :from-oid 10)
(make-instance 'elephant::secondary-cursor)
- (make-instance 'elephant::indexed-btree :sc sc :from-oid 10)
+ (make-instance 'elephant::indexed-btree :sc sc :from-oid 11)
+ (make-instance 'elephant::pset :sc sc :from-oid 12)
;; (sb-texinfo:generate-includes #p"/Users/eslick/Work/fsrc/elephant-cvs/doc/includes/"
- (sb-texinfo:generate-includes #p"."
+ (sb-texinfo:generate-includes include-dir-path
(find-package :elephant)
(find-package :elephant-backend)
- (find-package :elephant-memutil)
+ (find-package :elephant-memutil)
(find-package :elephant-system))))
(make-docs)
--- /project/elephant/cvsroot/elephant/doc/reference.texinfo 2007/04/01 14:33:29 1.9
+++ /project/elephant/cvsroot/elephant/doc/reference.texinfo 2007/04/12 02:47:23 1.10
@@ -8,10 +8,11 @@
@menu
* Store Controllers:: Connecting to a data store.
-* Persistent Objects:: Creating and using persistent objects.
-* Persistent Object Indexing:: Convenient indexing.
-* Query Interfaces:: Finding instances.
-* Collections:: BTrees and indices.
+* Persistent Class:: Defining persistent classes and creating and manipulating persistent indices.
+* Class Indexing:: Convenient indexing of persistent classes.
+* Persistent Sets:: Maintaining persistent collections the easy way.
+ at c * Query Interfaces:: Finding instances.
+* BTrees:: BTrees and indices, a low level persistent data structure.
* Cursors:: Traversing BTrees.
* Transactions:: Transactions.
* Migration and Upgrading:: Migration and upgrading.
@@ -91,29 +92,49 @@
@include includes/fun-elephant-add-class-derived-index.texinfo
@include includes/fun-elephant-remove-class-derived-index.texinfo
- at node Query Interfaces
+ at node Persistent Sets
@comment node-name, next, previous, up
- at section Query Interfaces
- at cindex Query Interfaces
+ at section Persistent Sets
+ at cindex Persistent Sets
-Query interfaces are currently unimplemented. An example query
-interface is provided for reference only, a new system is under
-development for the 0.7 release.
+Persistent sets are a simple persistent collection abstraction. They
+maintain an unordered collection of objects. Unlike the normal
+list-oriented sets of Lisp, persistent sets use the equivalent of
+ at code{pushnew} such that only one copy of any object or value is
+maintained using the serializer's @code{equal} implementation.
+
+ at include includes/class-elephant-pset.texinfo
+ at include includes/fun-elephant-insert-item.texinfo
+ at include includes/fun-elephant-remove-item.texinfo
+ at include includes/fun-elephant-find-item.texinfo
+ at include includes/fun-elephant-map-pset.texinfo
+ at include includes/fun-elephant-pset-list.texinfo
+
+ at c @node Query Interfaces
+ at c @comment node-name, next, previous, up
+ at c @section Query Interfaces
+ at c @cindex Query Interfaces
+
+ at c The query interface is currently unsupported. See @code{query.lisp}
+ at c and @code{query-example.lisp} for a sketch of what the query interface
+ at c will eventually look like. The upcoming version 0.9.1 will include
+ at c the query system and associated documentation system.
@c @include includes/fun-elephant-get-query-results.texinfo
@c @include includes/fun-elephant-map-class-query.texinfo
- at node Collections
+ at node BTrees
@comment node-name, next, previous, up
- at section Collections
- at cindex Collections
+ at section BTrees
+ at cindex BTrees
-Persistent collections inherit from @ref{Class
-elephant:persistent-collection} and consist of the @ref{Class
-elephant:btree}, @ref{Class elephant:indexed-btree} and @ref{Class
-elephant:btree-index} classes. The following operations are defined
-on most of these classes. More information can be found in @ref{Using
-BTrees} and @ref{Secondary Indices}.
+Persistent collections inherit from @ref{Class elephant:persistent-collection}
+and consist of the @ref{Class elephant:btree}, @ref{Class elephant:indexed-btree} and
+ @ref{Class elephant:btree-index} classes. The following operations are defined
+on most of these classes. More information can be found in @ref{Using BTrees}
+and @ref{Secondary Indices}.
+
+ at include includes/fun-elephant-make-btree.texinfo
@include includes/fun-elephant-get-value.texinfo
@include includes/fun-elephant-setf-get-value.texinfo
@@ -175,10 +196,26 @@
@include includes/macro-elephant-with-transaction.texinfo
+The following functions are an advanced use of the transaction system.
+They may be useful if, or example, you want to integrate Elephant
+transactions with non-Elephant side-effects that you explicitely make
+transactional.
+
+ at include includes/fun-elephant-controller-start-transaction.texinfo
+ at include includes/fun-elephant-controller-abort-transaction.texinfo
+ at include includes/fun-elephant-controller-commit-transaction.texinfo
+
@node Migration and Upgrading
@comment node-name, next, previous, up
@section Migration and Upgrading
@cindex Migration and Upgrading
- at include includes/fun-elephant-migrate.texinfo
+Upgrade is a call to Migrate with checks for compatability. The
+migrate methods are included here in case you wish to develop a more
+specific ``partial upgrade'' or ``partial migrate'' of data from one
+store to another instead of using the top-level copy which migrates all
+live objects.
+
@include includes/fun-elephant-upgrade.texinfo
+ at include includes/fun-elephant-migrate.texinfo
+
--- /project/elephant/cvsroot/elephant/doc/scenarios.texinfo 2007/04/04 15:28:28 1.3
+++ /project/elephant/cvsroot/elephant/doc/scenarios.texinfo 2007/04/12 02:47:23 1.4
@@ -48,7 +48,7 @@
(let ((newval (get-from-root name)))
(if newval
(setq name (add-to-root name newval))
- (setq name (add-to-root name (call-initializer
+ (setq name (add-to-root name (call-initializer
@end lisp
@node Persistent System Objects
@@ -93,7 +93,7 @@
@uref{http://konsenti.com}.
Konsenti uses the Data Collection Management (DCM) package, found in
-the @verbatim{src/contrib/rread directory}. DCM provides
+the @code{src/contrib/rread directory}. DCM provides
prevalence-style in-memory write-through caching. The most enjoyable
feature about Elephant for this project is that new Business Layer
objects can be created without having to deal with an
--- /project/elephant/cvsroot/elephant/doc/tutorial.texinfo 2007/04/04 15:35:44 1.15
+++ /project/elephant/cvsroot/elephant/doc/tutorial.texinfo 2007/04/12 02:47:23 1.16
@@ -1048,9 +1048,8 @@
more than two levels of transactional accesses with the top using
with-transaction and the bottom using ensure-transaction.
- at xref{Transaction Details} for more details and @pxref{Usage
-Scenarios} for examples of how systems can be designed and tuned using
-transactions.
+See @ref{Transaction Details} for more details and @ref{Usage Scenarios}
+for examples of how systems can be designed and tuned using transactions.
@node Advanced Topics
@comment node-name, next, previous, up
--- /project/elephant/cvsroot/elephant/doc/user-guide.texinfo 2007/04/06 02:51:47 1.10
+++ /project/elephant/cvsroot/elephant/doc/user-guide.texinfo 2007/04/12 02:47:23 1.11
@@ -108,7 +108,7 @@
by @emph{value}. This policy has a number of consequences which are
detailed below.
- at subsection{Restrictions of Store-by-Value}
+ at subsection Restrictions of Store-by-Value
@enumerate
@item @strong{Lisp identity can't be preserved}.
@@ -212,7 +212,7 @@
@end enumerate
- at subsection{Atomic Types}
+ at subsection Atomic Types
Atomic types have no recursive substructure. That is they cannot
contain arbitrary objects and are of a bounded size. (Bignums are an
@@ -272,14 +272,14 @@
Symbols are stored as two strings, the package name and the symbol name in that package. When deserialized, the target package is searched for and the symbol is interned in that package.
@end itemize
- at subsection{Aggregate Types}
+ at subsection Aggregate Types
The next list are @emph{aggregate} types, meaning that elements of
that type can contain references to elements of type @code{T}. That
means, in theory, that storing an aggregate type to disk that refers
to other objects can copy every reachable object! This is a direct
and dire consequence of the ``store-by-value'' restriction.
-(@xref{Persistent Classes and Objects} for how to design around the
+(@pxref{Persistent Classes and Objects} for how to design around the
store-by-value restriction}).
This list describes how aggregates are handled by the serializer.
@@ -320,8 +320,7 @@
have less slots) of ordinary classes.
@end itemize
-
-One final strategic consideration is whether you plan on sharing the binary
+One final strategic consideration is to whether you plan on sharing the binary
database between machines or between different lisp platforms on the
same machine. This is almost possible today, but there are some
restrictions. In the section @ref{Repository Migration and Upgrade}
@@ -332,40 +331,88 @@
@comment node-name, next, previous, up
@section Persistent Classes and Objects
-Persistent classes are Elephant's answer to the limitations of
-ordinary lisp object serialization, namely support for persistent
-references. Any persistent object, when serialized, only serializes a
-reference to the object and not the whole object. For example you can
-serialize a node in the graph of persistent objects without worrying
-about serializing the entire graph.
-
- at subsection{Persistent Class Definition}
-
-Other than specifying the metaclass or using @code{defpclass} the only
-important differences in the @code{defclass} form is the specification
-of a slot storage policy. Slot storage policy can be specified by a
-boolean argument to the slot initargs @code{:persistent} or
- at code{:transient}. Slots are @code{:persistent} by default
+Persistent classes are instances of the @code{persistent-metaclass}
+metaclass. All instances of this persistent class have a unique ID
+and a pointer to the @code{store-controller} specification they are
+associated with. Accesses to slot values become direct reads and
+writes to the data store and are thus always persisted. When the
+instance itself is writtent to the database, for example as a key or
+value in a @code{btree}, only the unique ID is stored.
+
+Thus serialization of persistent objects is exceedingly cheap compared
+to standard objects, but slot access can be much more expensive.
+Persistent objects are excellent at, for example, storing the link
+structure of a graph. A graph of persistent objects can itself be
+persisted by storing the head node of a fully-connected graph to the
+store controller root.
+
+ at subsection Persistent Class Definition
+
+To create persistent classes, the user needs to specify the
+ at code{persistent-metaclass} to the class initarg @code{:metaclass}.
+The only differences between standard and persistent class definitions
+is the specification of a slot storage policy and an index policy.
+
+Storage policies are specified by a boolean argument to the slot
+initargs @code{:persistent} or @code{:transient}. Slots are
+ at code{:persistent} by default
@lisp
(defclass my-pclass ()
((pslot1 :accessor pslot1 :initarg :pslot1 :initform 'one)
(pslot2 :accessor pslot2 :initarg :pslot2 :initform 'two :persistent t)
- (tslot1 :accessor tslot3 :initarg :tslot3 :initform nil :transient t))
+ (tslot1 :accessor tslot1 :initarg :tslot1 :initform 'three :transient t))
(:metaclass persistent-metaclass))
@end lisp
-The :index options to persistent classes are discussed in persistent
-indices.
-
Slot storage class implications are straightforward. Persistent slot
-writes are durably stored to disk in an automatic or encompassing
-transaction. Transient slots are initialized on instance creation
-according to initforms or to initargs. They are never stored to nor
-loaded from the database.
+writes are durably stored to disk. Transient slots are initialized on
+instance creation according to initforms or to initargs. Transient
+slot values are never stored to nor loaded from the database.
+
+During a given lisp session transient values will be cached as long as
+they are not collected by the Lisps GC. After GC, if you retrieve an
+object from the store its transient slots will be reset to the slot
+initforms from the class definition.
+
+ at lisp
+(setf pobj1 (make-instance 'my-pclass :pslot1 1 :tslot3 3))
+=> #<MY-PCLASS>
+
+(pslot1 pobj1) => 1
+(pslot2 pobj1) => 'two
+(tslot1 pobj1) => 3
+
+(add-to-root 'pobj1 pobj1)
+
+(setf pobj2 (get-from-root 'pobj1))
+=> #<MY-PCLASS>
+
+(pslot1 pobj2) => 1
+(pslot2 pobj2) => 'two
+(tslot1 pobj2) => 3
+
+(setf pobj1 nil)
+(setf pobj2 nil)
+(gc)
+
+(setf pobj3 (get-from-root 'pobj1))
+(pslot1 pobj2) => 1
+(pslot2 pobj2) => 'two
+(tslot1 pobj2) => 'three
+ at end lisp
+The implications of this behavior is that you need to think carefully
+about using transient values. Primarily you cannot make assumptions
+about the state of transient values in objects loaded from the store
+unless you know that they were loaded and cannot be GC'ed.
+
+Finally, the index policy tells the data store whether to maintain an
+inverted index that maps slot values back to their parent objects.
+The :index options and behaviors of persistent classes are discussed in
+depth in @ref{Class Indices}.
- at subsection{Instance Creation}
+ at subsection Instance Creation
Persistent objects are instances of the persistent classes defined
above. All persistent objects inherit from the class
More information about the Elephant-cvs
mailing list