| 1 |
README for Package CL-STORE. |
|---|
| 2 |
Author: Sean Ross |
|---|
| 3 |
Homepage: http://www.common-lisp.net/project/cl-store/ |
|---|
| 4 |
Version: 0.6 |
|---|
| 5 |
|
|---|
| 6 |
0. About. |
|---|
| 7 |
CL-STORE is an portable serialization package which |
|---|
| 8 |
should give you the ability to store all common-lisp |
|---|
| 9 |
data types (well not all yet) into streams. |
|---|
| 10 |
See the cl-store manual (docs/cl-store.texi) for more in depth information. |
|---|
| 11 |
|
|---|
| 12 |
!!! NOTE: The cl-store-xml backend is deprecated. |
|---|
| 13 |
|
|---|
| 14 |
1. Usage |
|---|
| 15 |
The main entry points are |
|---|
| 16 |
- [Method] cl-store:store (obj place &optional (backend *default-backend*)) |
|---|
| 17 |
=> obj |
|---|
| 18 |
Where place is a path designator or stream and |
|---|
| 19 |
backend is one of the registered backends. |
|---|
| 20 |
|
|---|
| 21 |
- [Method] cl-store:restore (place &optional (backend *default-backend*)) |
|---|
| 22 |
=> restored-objects |
|---|
| 23 |
Where place and backend is as above. |
|---|
| 24 |
|
|---|
| 25 |
- cl-store:restore is setfable, which I think makes |
|---|
| 26 |
for a great serialized hit counter. |
|---|
| 27 |
eg. (incf (restore place)) |
|---|
| 28 |
|
|---|
| 29 |
NOTE. |
|---|
| 30 |
All errors signalled within store and restore can |
|---|
| 31 |
be handled by catching store-error and restore-error respectively. |
|---|
| 32 |
|
|---|
| 33 |
2. Optimizing. |
|---|
| 34 |
|
|---|
| 35 |
While cl-store is generally quickish it still has a tendency to |
|---|
| 36 |
do a lot of consing. Thanks to profilers this has been pinned down |
|---|
| 37 |
to the rehashing of the hash-tables which track object circularities. |
|---|
| 38 |
From 0.4.0 cl-store has three new variables *store-hash-size*, *restore-hash-size* |
|---|
| 39 |
and *check-for-circs*, proper usage of these new variables can greatly reduce |
|---|
| 40 |
the consing (and time taken) when storing and restoring large objects. |
|---|
| 41 |
|
|---|
| 42 |
- *store-hash-size* and *restore-hash-size |
|---|
| 43 |
At the beginning of storing and restoring an eq hash-table is created with a |
|---|
| 44 |
default size of 50 to track objects which have been (re)stored. On large objects however |
|---|
| 45 |
the rehashing of these hash-tables imposes a severe drain on performance. |
|---|
| 46 |
By binding these two variables to appropriately large values |
|---|
| 47 |
about (100010 for a hash-table with 100000 int->string mappings) you |
|---|
| 48 |
can obtain a decent performance improvement. This may require a bit |
|---|
| 49 |
of fiddling to find the best tradeoff between rehashing and creating |
|---|
| 50 |
a large hash-table. |
|---|
| 51 |
|
|---|
| 52 |
- *check-for-circs* |
|---|
| 53 |
Binding this variable to nil when storing or restoring |
|---|
| 54 |
an object inhibits all checks for circularities which gives a |
|---|
| 55 |
severe boost to performance. The downside of this is that no |
|---|
| 56 |
restored objects will be eq and attempting to store circular objects |
|---|
| 57 |
will hang. The speed improvements are definitely worth it if you |
|---|
| 58 |
know that there will be no circularities or shared references in |
|---|
| 59 |
your data (eg spam-filter hash-tables). |
|---|
| 60 |
|
|---|
| 61 |
Enjoy |
|---|
| 62 |
Sean. |
|---|
