salewski / cl-store Goto Github PK

README for Package CL-STORE.
Author: Sean Ross 
Homepage: http://www.common-lisp.net/project/cl-store/
Version: 0.6

0. About.
   CL-STORE is an portable serialization package which 
   should give you the ability to store all common-lisp
   data types (well not all yet) into streams.
   See the cl-store manual (docs/cl-store.texi) for more in depth information.
   
   !!! NOTE: The cl-store-xml backend is deprecated.

1. Usage
   The main entry points are 
    - [Method] cl-store:store (obj place &optional (backend *default-backend*)) 
          => obj
       Where place is a path designator or stream and
       backend is one of the registered backends.

    - [Method] cl-store:restore (place &optional (backend *default-backend*)) 
          => restored-objects
       Where place and backend is as above.

    - cl-store:restore is setfable, which I think makes
      for a great serialized hit counter.
      eg. (incf (restore place))
  
    NOTE.
     All errors signalled within store and restore can 
     be handled by catching store-error and restore-error respectively.

2. Optimizing.
    
   While cl-store is generally quickish it still has a tendency to 
   do a lot of consing. Thanks to profilers this has been pinned down 
   to the rehashing of the hash-tables which track object circularities.
   From 0.4.0 cl-store has three new variables *store-hash-size*, *restore-hash-size*
   and *check-for-circs*, proper usage of these new variables can greatly reduce
   the consing (and time taken) when storing and restoring large objects.
  
   - *store-hash-size* and *restore-hash-size
     At the beginning of storing and restoring an eq hash-table is created with a 
     default size of 50 to track objects which have been (re)stored. On large objects however
     the rehashing of these hash-tables imposes a severe drain on performance.
     By binding these two variables to appropriately large values 
     about (100010 for a hash-table with 100000 int->string mappings) you
     can obtain a decent performance improvement. This may require a bit 
     of fiddling to find the best tradeoff between rehashing and creating 
     a large hash-table.
 
   - *check-for-circs*
     Binding this variable to nil when storing or restoring
     an object inhibits all checks for circularities which gives a 
     severe boost to performance. The downside of this is that no 
     restored objects will be eq and attempting to store circular objects 
     will hang. The speed improvements are definitely worth it if you 
     know that there will be no circularities or shared references in 
     your data (eg spam-filter hash-tables). 

Enjoy
 Sean.