Updates for release 1.1

[memstore.git] / doc / memstore.html

diff --git a/doc/memstore.html b/doc/memstore.html
new file mode 100644 (file)
index 0000000..62fbbb2
--- /dev/null
+++ b/doc/memstore.html
@@ -0,0 +1,55 @@
+<h1>Memstore</h1>
+
+<p><em>A high-level interface for the memcached and membase servers</em></p>
+
+<p>Written by Kevin M. Rosenberg <a href="&#x6D;&#97;&#x69;&#108;&#x74;&#111;:&#x6B;&#x65;&#118;&#x69;&#x6E;&#64;&#114;&#x6F;&#115;&#x65;&#110;&#x62;e&#x72;&#103;&#x2E;&#110;&#101;&#116;">&#x6B;&#x65;&#118;&#x69;&#x6E;&#64;&#114;&#x6F;&#115;&#x65;&#110;&#x62;e&#x72;&#103;&#x2E;&#110;&#101;&#116;</a></p>
+
+<h2>Downloads</h2>
+
+<ul>
+<li>The web site for memstore is <a href="http://memstore.b9.com/">http://memstore.b9.com/</a></li>
+<li>A git repository is available at <a href="http://gitpub.b9.com/memstore.git">http://gitpub.b9.com/memstore.git</a></li>
+<li>Releases are available for download at <a href="http://files.b9.com/memstore/">http://files.b9.com/memstore/</a></li>
+</ul>
+
+<h2>Prerequisites</h2>
+
+<p>This library incorporates a heavily modified version of <code>cl-memcached</code>
+version 0.4.1. The primary need for the modification is to support the
+<code>flags</code> field supported by the memcached server. The flag field is
+used to store information required to deserialize the object data from
+memcached. In addition to adding the <code>flags</code> field, the library has
+been heavily refactored. For more information on the changes in
+memcache, see <a href="memcache.html">memcache</a>.</p>
+
+<p>This library also requires Common Lisp libraries of 
+<a href="http://gitpub.b9.com/kmrcl.git">kmrcl</a>,
+<a href="http://common-lisp.net/project/cl-store/">cl-store</a>,
+<a href="http://weitz.de/flexi-streams/">flexi-streams</a>,
+and <a href="http://common-lisp.net/project/zlib/">zlib</a>.</p>
+
+<h2>Overview</h2>
+
+<p>Memstore allows efficient storing of simple objects as well as
+easy storing of complex objects and optional compression.</p>
+
+<p>When storing an object, if the object is a string then that is
+directly written to the memcached server. For non-strings, an attempt
+to made to write the object to a string with <code>*print-readably*</code> bound
+to <code>t</code>. If that succeeds, then the string is converted to a vector of
+octets. If that fails, the <code>cl-store</code> is used to serialize that object
+to a vector of octets.</p>
+
+<p>Next, optional compression is applied to the octets. First, the
+<code>*compression-enabled*</code> flag is checked to see if compression is
+enabled. Next, the length of the objects is compared to
+<code>*compression-threshold*</code>. Only objects larger than
+<code>*compression-threshold*</code> will be compressed. For objects that qualify
+for compression, the size of the compressed object is compared to the
+length of the uncompressed object to decide if the object is shrunk
+enough to make the compression worthwhile.</p>
+
+<p>The <code>flags</code> parameter to cl-memcached stores whether cl-store or
+write-to-string is used to serialize the object and whether
+compression is applied. <code>mem-restore</code> uses those flags to determine
+how to reconstruct the object.</p>