localmemcache 0.2.2 → 0.3.0

data/src/localmemcache.c

@@ -33,30 +33,35 @@ int lmc_release_lock_flag(void *base, lmc_error_t *e) {
   return 1;
 }
 
-void lmc_clean_namespace_string(char *result, const char* original) {
-  size_t n = strlen(original);
-  if (n > 256) { n = 256; }
-  const char *s = original;
-  char *d = result;
-  char ch;
-  for (; n--; d++, s++) { 
-    ch = *s;
-    if ((ch >= 'a' && ch <= 'z') || 
-        (ch >= 'A' && ch <= 'Z')) {
-      *d = ch;
-    } else {
-      *d = '-';
+int lmc_namespace_or_filename(char *result, const char* ons, const char *ofn,
+    lmc_error_t *e) {
+  if (ons) {
+    lmc_clean_string(result, ons);
+    return 1;
+  }
+  if (ofn) {
+    size_t n = strlen(ofn);
+    if (n > 1010) { n = 1010; }
+    char *d = result;
+    if (!lmc_is_filename(ofn)) {
+      strcpy(d, "./");
+      d += 2;
     }
+    strcpy(d, ofn);
+    return 1;
   }
-  *d = 0x0;
+  lmc_handle_error_with_err_string("lmc_namespace_or_filename", 
+      "Need to supply either namespace or filename argument", "ArgError", e);
+  return 0;
 }
 
-int local_memcache_clear_namespace(const char *namespace, int repair, 
-    lmc_error_t *e) {
+int local_memcache_clear_namespace(const char *namespace, const char *filename,
+    int repair, lmc_error_t *e) {
   char clean_ns[1024];
-  lmc_clean_namespace_string((char *)clean_ns, namespace);
+  if (!lmc_namespace_or_filename((char *)clean_ns, namespace, filename, e))
+      return 1;
   lmc_clean_namespace((char *)clean_ns, e);
-  if (repair) { 
+  if (repair) {
     lmc_lock_t *l = lmc_lock_init((char *)clean_ns, 1, e);
     lmc_lock_repair(l);
     free(l);
@@ -70,6 +75,8 @@ int local_memcache_clear_namespace(const char *namespace, int repair,
   return 1;
 }
 
+int __local_memcache_check_namespace(const char *clean_ns, lmc_error_t *e);
+
 local_memcache_t *__local_memcache_create(const char *namespace, size_t size, 
     int force, int *ok, lmc_error_t* e) {
   int d;
@@ -89,11 +96,11 @@ retry:
   }
   if (!lmc_is_lock_working(lmc->lock, e)) {
     if (!force) {
-      if (local_memcache_check_namespace(namespace, e))  goto retry;
+      if (__local_memcache_check_namespace(namespace, e))  goto retry;
       lmc_handle_error_with_err_string("local_memcache_create",
           "Failed to repair shared memory!", "ShmLockFailed", e);
       goto failed;
-    } 
+    }
     *ok = 0;
   }
   {
@@ -133,26 +140,26 @@ failed:
   return NULL;
 }
 
-local_memcache_t *local_memcache_create(const char *namespace, double size_mb, 
-    lmc_error_t* e) {  
+local_memcache_t *local_memcache_create(const char *namespace, 
+    const char *filename, double size_mb, lmc_error_t* e) {  
   char clean_ns[1024];
   double s = size_mb == 0.0 ? 1024.0 : size_mb;
   size_t si = s * 1024 * 1024;
   //printf("size: %f, s: %f, si: %zd\n", size_mb, s, si);
-  lmc_clean_namespace_string((char *)clean_ns, namespace);
+  if (!lmc_namespace_or_filename((char *)clean_ns, namespace, filename, e))
+      return 0;
   return __local_memcache_create((char *)clean_ns, si, 0, 0, e);
 }
 
-int local_memcache_check_namespace(const char *namespace, lmc_error_t *e) {
-  char clean_ns[1024];
-  lmc_clean_namespace_string((char *)clean_ns, namespace);
+int __local_memcache_check_namespace(const char *clean_ns, lmc_error_t *e) {
   char check_lock_name[1024];
   snprintf((char *)check_lock_name, 1023, "%s-check", (char *)clean_ns);
 
   if (!lmc_does_namespace_exist((char *)clean_ns)) { 
     lmc_clear_namespace_lock(check_lock_name);
-    lmc_clear_namespace_lock(namespace);
-    printf("namespace '%s' does not exist!\n", (char *)clean_ns);
+    lmc_clear_namespace_lock(clean_ns);
+    fprintf(stderr, "[localmemcache] namespace '%s' does not exist!\n", 
+        (char *)clean_ns);
     return 1;
   }
 
@@ -170,12 +177,14 @@ int local_memcache_check_namespace(const char *namespace, lmc_error_t *e) {
   local_memcache_t *lmc = __local_memcache_create((char *)clean_ns, ns_size, 
       1, &ok, e);
   if (!lmc) {
-    printf("WOAH: lmc == 0!\n");
+    lmc_handle_error_with_err_string("__local_memcache_create", 
+        "Unable to attach memory pool", "InitError", e);
     goto failed;
   }
   md = lmc->base;
   if (!ok) {
-    printf("[lmc] Auto repairing namespace '%s'\n", namespace);
+    fprintf(stderr, "[localmemcache] Auto repairing namespace '%s'\n", 
+        clean_ns);
     if (!md->locked) goto release;
     if (md->log.op_id == 0) goto unlock_and_release;
     if (ht_redo(lmc->base, md->va_hash, &md->log, e)) goto unlock_and_release;
@@ -208,24 +217,36 @@ failed:
   lmc_lock_release("local_memcache_check_namespace", check_l, e);
 check_lock_failed:
   free(check_l);
-  printf("[lmc] Failed to repair namespace '%s'\n", namespace);
+  fprintf(stderr, "[localmemcache] Failed to repair namespace '%s'\n", 
+      clean_ns);
   return 0;
 }
 
+int local_memcache_check_namespace(const char *namespace, const char *filename, 
+    lmc_error_t *e) {
+  char clean_ns[1024];
+  if (!lmc_namespace_or_filename((char *)clean_ns, namespace, filename, e)) 
+    return 0;
+  return __local_memcache_check_namespace(clean_ns, e);
+}
+
+
 
 int lmc_lock_shm_region(const char *who, local_memcache_t *lmc) {
   int r;
   int retry_counter = 0;
 retry:
   if (retry_counter++ > 10) {
-    printf("[lmc] Too many retries: Cannot repair namespace '%s'\n", 
-        lmc->namespace);
+    fprintf(stderr, "[localmemcache] Too many retries: "
+        "Cannot repair namespace '%s'\n", lmc->namespace);
     return 0;
   }
   r = lmc_lock_obtain(who, lmc->lock, &lmc->error);
   if (!r && (strcmp(lmc->error.error_type, "LockTimedOut") == 0)) {
-    if (local_memcache_check_namespace(lmc->namespace, &lmc->error))  goto retry;
-    printf("[lmc] Cannot repair namespace '%s'\n", lmc->namespace);
+    if (__local_memcache_check_namespace(lmc->namespace, 
+        &lmc->error))  goto retry;
+    fprintf(stderr, "[localmemcache] Cannot repair namespace '%s'\n", 
+        lmc->namespace);
   }
   if (!r) return 0;
   if (!lmc_set_lock_flag(lmc->base, &lmc->error)) {

data/src/localmemcache.h

@@ -15,6 +15,70 @@
 #define LOCAL_MEMCACHE_FAILED 0
 #define LOCAL_MEMCACHE_SUCCESS 1
 
+/*
+ * LocalMemCache provides for a Hashtable of strings in shared memory (via a
+ * memory mapped file), which thus can be shared between processes on a
+ * computer.  Here is an example of its usage:
+ *
+ * #include <stdio.h>
+ * #include <localmemcache.h>
+ * 
+ * int main() {
+ *   lmc_error_t e;
+ *   // To use a filename instead of a namespace: 
+ *   // lmc = local_memcache_create(0, "filename.lmc", 0, &e);
+ *   local_memcache_t *lmc = local_memcache_create("viewcounters", 0, 0, &e);
+ *   if (!lmc) {
+ *     fprintf(stderr, "Couldn't create localmemcache: %s\n", e.error_str);
+ *     return 1;
+ *   }
+ *   if (!local_memcache_set(lmc, "foo", 3, "1", 1)) goto failed;
+ *   size_t n_value;
+ *   char *value = local_memcache_get_new(lmc, "foo", 3, &n_value);
+ *   if (!value) goto failed;
+ *   free(value);
+ *   if (!local_memcache_delete(lmc, "foo", 3)) goto failed;
+ *   if (!local_memcache_free(lmc, &e)) {
+ *     fprintf(stderr, "Failed to release localmemcache: %s\n", e.error_str);
+ *     return 1;
+ *   }
+ * 
+ *   return 0;
+ * 
+ * failed:
+ *   fprintf(stderr, "%s\n", lmc->error.error_str);
+ *   return 1;
+ * 
+ * }
+ *
+ *  == Default sizes of memory pools
+ *
+ *  The default size for memory pools is 1024 (MB). It cannot be changed later,
+ *  so choose a size that will provide enough space for all your data.  You
+ *  might consider setting this size to the maximum filesize of your
+ *  filesystem.  Also note that while these memory pools may look large on your
+ *  disk, they really aren't, because with sparse files only those parts of the
+ *  file which contain non-null data actually use disk space.
+ *
+ *  == Automatic recovery from crashes
+ *
+ *  In case a process is terminated while accessing a memory pool, other
+ *  processes will wait for the lock up to 2 seconds, and will then try to
+ *  resume the aborted operation.  This can also be done explicitly by using
+ *  LocalMemCache.check(options).
+ *
+ *  == Clearing memory pools
+ *
+ *  Removing memory pools can be done with LocalMemCache.clear(options). 
+ *
+ *  == Environment
+ *  
+ *  If you use the :namespace parameter, the .lmc file for your namespace will
+ *  reside in /var/tmp/localmemcache.  This can be overriden by setting the
+ *  LMC_NAMESPACES_ROOT_PATH variable in the environment.
+ *
+ */
+
 typedef struct {
   char *namespace;
   size_t size;
@@ -26,22 +90,115 @@ typedef struct {
   lmc_error_t error;
 } local_memcache_t;
 
-local_memcache_t *local_memcache_create(const char *namespace, double size_mb,
-    lmc_error_t *e);
+/*
+ *  Creates a new handle for accessing a shared memory region.
+ * 
+ *  lmc_error_t e;
+ *  // open via namespace
+ *  local_memcache_t *lmc = local_memcache_create("viewcounters", 0, 0, &e);
+ *  // open via filename
+ *  local_memcache_t *lmc = local_memcache_create(0, "./foo.lmc", 0, &e);
+ * 
+ *  You must supply at least a namespace or filename parameter
+ *
+ *  The size_mb defaults to 1024 (1 GB).
+ *
+ *  If you use the namespace parameter, the .lmc file for your namespace will
+ *  reside in /var/tmp/localmemcache.  This can be overriden by setting the
+ *  LMC_NAMESPACES_ROOT_PATH variable in the environment.
+ *
+ *  When you first call .new for a previously not existing memory pool, a
+ *  sparse file will be created and memory and disk space will be allocated to
+ *  hold the empty hashtable (about 100K), so the size_mb refers
+ *  only to the maximum size of the memory pool.  .new for an already existing
+ *  memory pool will only map the already previously allocated RAM into the
+ *  virtual address space of your process.  
+ */
+local_memcache_t *local_memcache_create(const char *namespace, 
+    const char *filename, double size_mb, lmc_error_t* e);
+
+/* 
+ *  Retrieve string value from hashtable.
+ *
+ *  It will return a newly allocated string which you need to free() after use.
+ */
 char *local_memcache_get_new(local_memcache_t *lmc, const char *key, 
     size_t n_key, size_t *n_value);
+
+/* 
+ *  Set string value in hashtable.
+ */
 int local_memcache_set(local_memcache_t *lmc, const char *key, size_t n_key, 
     const char* value, size_t n_value);
+
+/* 
+ *  Deletes key from hashtable.  
+ */
 int local_memcache_delete(local_memcache_t *lmc, char *key, size_t n_key);
+
+/*
+ * Releases memory pool handle.
+ */
 int local_memcache_free(local_memcache_t *lmc, lmc_error_t *e);
+
+/*
+ * Iterate over key value pairs in memory pool
+ *
+ * example:
+ *   typedef struct {
+ *     ...
+ *   } collector_t;
+ *
+ *   int my_collect(void *ctx, const char* key, const char* value) {
+ *      collector_t *c = ctx;
+ *      ....
+ *   }
+ *
+ *   local_memcache_t *lmc;
+ *   collector_t c;
+ *   local_memcache_iterate(lmc, (void *) &c, my_collect);
+ *
+ * The memory pool will be locked while iteration takes place, so try to make
+ * sure you can iterate within under 2 seconds otherwise other waiting
+ * processes will try to remove the lock (2 seconds is the timeout for
+ * triggering the automatic recovery.)
+ *
+ */
 int local_memcache_iterate(local_memcache_t *lmc, void *ctx, 
     LMC_ITERATOR_P(iter));
-int local_memcache_clear_namespace(const char *namespace, int repair, 
+
+/*
+ * Deletes a memory pool.  If repair is 1, locked semaphores are
+ * removed as well.
+ *
+ * WARNING: Do only call this method with the repair option if you are sure
+ * that you really want to remove this memory pool and no more processes are
+ * still using it.
+ *
+ * If you delete a pool and other processes still have handles open on it, the
+ * status of these handles becomes undefined.  There's no way for a process to
+ * know when a handle is not valid anymore, so only delete a memory pool if
+ * you are sure that all handles are closed.
+ *
+ * The memory pool must be specified by either setting the filename or
+ * namespace parameter.  
+ */
+int local_memcache_clear_namespace(const char *namespace, const char *filename,
+    int repair, lmc_error_t *e);
+/*
+ * Tries to repair a corrupt namespace.  Usually one doesn't call this method
+ * directly, it's invoked automatically when operations time out.
+ *
+ * The memory pool must be specified by either setting the filename or
+ * namespace parameter. 
+ */
+int local_memcache_check_namespace(const char *namespace, const char *filename, 
     lmc_error_t *e);
-int local_memcache_check_namespace(const char *namespace, lmc_error_t *e);
 
+/* internal, do not use */
 const char *__local_memcache_get(local_memcache_t *lmc, 
     const char *key, size_t n_key, size_t *n_value);
 
+/* internal, do not use */
 int lmc_unlock_shm_region(const char *who, local_memcache_t *lmc);
 #endif

data/src/ruby-binding/localmemcache.rb

@@ -1,12 +1,5 @@
 require 'rblocalmemcache'
 
-# == Overview
-# TestRDocUsage: A useless file
-#
-# == Example
-#
-#  Usage:  ruby testRDocUsage.rb  [options]
-#
 class LocalMemCache
 
   class LocalMemCacheError < StandardError; end
@@ -15,29 +8,68 @@ class LocalMemCache
   class LockError < LocalMemCacheError; end
   class LockTimedOut < LocalMemCacheError; end
   class OutOfMemoryError < LocalMemCacheError; end
+  class ArgError < LocalMemCacheError; end
+  class InitError < LocalMemCacheError; end
   class RecoveryFailed < LocalMemCacheError; end
   class ShmLockFailed < LocalMemCacheError; end
   class ShmUnlockFailed < LocalMemCacheError; end
   class MemoryPoolClosed < LocalMemCacheError; end
 
   #  Creates a new handle for accessing a shared memory region.
-  #
+  # 
   #  LocalMemCache.new :namespace=>"foo", :size_mb=> 1
-  #
-  #  The namespace parameter is mandatory.  
+  # 
+  #  LocalMemCache.new :filename=>"./foo.lmc"
+  # 
+  #  You must supply at least a :namespace or :filename parameter
   #  The size_mb defaults to 1024 (1 GB).
   #
+  #  If you use the :namespace parameter, the .lmc file for your namespace will
+  #  reside in /var/tmp/localmemcache.  This can be overriden by setting the
+  #  LMC_NAMESPACES_ROOT_PATH variable in the environment.
+  #
+  #  When you first call .new for a previously not existing memory pool, a
+  #  sparse file will be created and memory and disk space will be allocated to
+  #  hold the empty hashtable (about 100K), so the size_mb refers
+  #  only to the maximum size of the memory pool.  .new for an already existing
+  #  memory pool will only map the already previously allocated RAM into the
+  #  virtual address space of your process.  
+  #
+  # 
   def self.new(options)
     o = { :size_mb => 0 }.update(options || {})
-    raise "Missing mandatory option ':namespace'" if !o[:namespace]
-    _new(o[:namespace].to_s, o[:size_mb].to_f);
+    _new(o);
   end
 
-  # Deletes the given namespaces, removing semaphores if necessary.
-  # Do only use if you are sure the namespace is not used anymore by other
-  # processes.
+  # NOTE: This method is deprecated, use LocalMemCache.clear(*args) instead.
+  #
+  # Deletes a memory pool.  If the repair flag is set, locked semaphores are
+  # removed as well.  
   #
+  # If you delete a pool and other processes still have handles open on it, the
+  # status of these handles becomes undefined.  There's no way for a process to
+  # know when a handle is not valid anymore, so only delete a memory pool if
+  # you are sure that all handles are closed.
+  #
+  # WARNING: Do only call this method with the repair=true flag if you are sure
+  # that you really want to remove this memory pool and no more processes are
+  # still using it.
   def self.clear_namespace(namespace, repair = false) 
-    _clear_namespace(namespace.to_s, repair)
+    clear :namespace => namespace.to_s, :repair => repair
+  end
+
+  # NOTE: This method is deprecated, use LocalMemCache.check(*args) instead.
+  #
+  # Tries to repair a corrupt namespace.  Usually one doesn't call this method
+  # directly, it's invoked automatically when operations time out.
+  # 
+  # valid options are 
+  # [:namespace] 
+  # [:filename] 
+  # 
+  # The memory pool must be specified by either setting the :filename or
+  # :namespace option.  The default for :repair is false.
+  def self.check_namespace(namespace) 
+    check :namespace => namespace.to_s
   end
 end

data/src/ruby-binding/rblocalmemcache.c

@@ -15,7 +15,6 @@
 #define RSTRING_PTR(x) RSTRING(x)->ptr
 #endif
 
-
 #if RUBY_VERSION_CODE >= 190
 #define ruby_errinfo rb_errinfo()
 #endif
@@ -32,6 +31,11 @@ char *rstring_ptr(VALUE s) {
   return r ? r : "nil";
 }
 
+char *rstring_ptr_null(VALUE s) { 
+  char* r = NIL_P(s) ? NULL : RSTRING_PTR(rb_String(s)); 
+  return r ? r : NULL;
+}
+
 /* :nodoc: */
 size_t rstring_length(VALUE s) { 
   size_t r = NIL_P(s) ? 0 : RSTRING_LEN(rb_String(s)); 
@@ -58,6 +62,10 @@ typedef struct {
 } rb_lmc_handle_t;
 
 static VALUE LocalMemCache;
+static VALUE lmc_rb_sym_namespace;
+static VALUE lmc_rb_sym_filename;
+static VALUE lmc_rb_sym_size_mb;
+static VALUE lmc_rb_sym_repair;
 
 /* :nodoc: */
 void __rb_lmc_raise_exception(const char *error_type, const char *m) {
@@ -86,12 +94,20 @@ static void rb_lmc_free_handle(rb_lmc_handle_t *h) {
   local_memcache_free(rb_lmc_check_handle_access(h), &e);
 }
 
+void lmc_check_dict(VALUE o) {
+  if (TYPE(o) != T_HASH) {
+    rb_raise(rb_eArgError, "expected a Hash");
+  }
+}
 
 /* :nodoc: */
-static VALUE LocalMemCache__new2(VALUE klass, VALUE namespace, VALUE size_mb) {
+static VALUE LocalMemCache__new2(VALUE klass, VALUE o) {
+  lmc_check_dict(o);
   lmc_error_t e;
-  local_memcache_t *l = local_memcache_create(rstring_ptr(namespace), 
-      double_value(size_mb), &e);
+  local_memcache_t *l = local_memcache_create(
+      rstring_ptr_null(rb_hash_aref(o, lmc_rb_sym_namespace)),
+      rstring_ptr_null(rb_hash_aref(o, lmc_rb_sym_filename)), 
+      double_value(rb_hash_aref(o, lmc_rb_sym_size_mb)), &e);
   if (!l)  rb_lmc_raise_exception(&e);
   rb_lmc_handle_t *h = calloc(1, sizeof(rb_lmc_handle_t));
   if (!h) rb_raise(rb_eRuntimeError, "memory allocation error");
@@ -107,21 +123,61 @@ local_memcache_t *get_LocalMemCache(VALUE obj) {
   return rb_lmc_check_handle_access(h);
 }
 
-
-/* :nodoc: */
-static VALUE LocalMemCache__clear_namespace(VALUE klass, VALUE ns, 
-    VALUE repair) {
+/*
+ * call-seq: LocalMemCache.clear(*args)
+ *
+ * Deletes a memory pool.  If the :repair option is set, locked semaphores are
+ * removed as well.
+ *
+ * WARNING: Do only call this method with the :repair option if you are sure
+ * that you really want to remove this memory pool and no more processes are
+ * still using it.
+ *
+ * If you delete a pool and other processes still have handles open on it, the
+ * status of these handles becomes undefined.  There's no way for a process to
+ * know when a handle is not valid anymore, so only delete a memory pool if
+ * you are sure that all handles are closed.
+ *
+ * valid options for clear are 
+ * [:namespace] 
+ * [:filename] 
+ * [:repair] 
+ *
+ * The memory pool must be specified by either setting the :filename or
+ * :namespace option.  The default for :repair is false.
+ */
+static VALUE LocalMemCache__clear(VALUE klass, VALUE o) {
+  lmc_check_dict(o);
   lmc_error_t e;
-  if (!local_memcache_clear_namespace(rstring_ptr(ns), bool_value(repair), &e)) {
+  if (!local_memcache_clear_namespace(
+      rstring_ptr_null(rb_hash_aref(o, lmc_rb_sym_namespace)), 
+      rstring_ptr_null(rb_hash_aref(o, lmc_rb_sym_filename)),
+      bool_value(rb_hash_aref(o, lmc_rb_sym_repair)), &e)) {
     rb_lmc_raise_exception(&e); 
   }
   return Qnil;
 }
 
-/* :nodoc: */
-static VALUE LocalMemCache__check_namespace(VALUE klass, VALUE ns) {
+/*
+ * call-seq: LocalMemCache.check(*args)
+ *
+ * Tries to repair a corrupt namespace.  Usually one doesn't call this method
+ * directly, it's invoked automatically when operations time out.
+ *
+ * valid options are 
+ * [:namespace] 
+ * [:filename] 
+ *
+ * The memory pool must be specified by either setting the :filename or
+ * :namespace option. 
+ */
+static VALUE LocalMemCache__check(VALUE klass, VALUE o) {
+  lmc_check_dict(o);
   lmc_error_t e;
-  if (!local_memcache_check_namespace(rstring_ptr(ns), &e)) {
+  if (!local_memcache_check_namespace(
+      rstring_ptr_null(rb_hash_aref(o, lmc_rb_sym_namespace)), 
+      rstring_ptr_null(rb_hash_aref(o, lmc_rb_sym_filename)),
+      &e)) {
     rb_lmc_raise_exception(&e); 
   }
   return Qnil;
@@ -140,13 +196,12 @@ static VALUE LocalMemCache__disable_test_crash(VALUE klass) {
   return Qnil;
 }
 
-
 /* 
  *  call-seq:
- *     lmc.get(key)   ->   Qnil
- *     lmc[key]       ->   Qnil
+ *     lmc.get(key)   ->   string value or nil
+ *     lmc[key]       ->   string value or nil
  *
- *  Retrieve value from hashtable.
+ *  Retrieve string value from hashtable.
  */
 static VALUE LocalMemCache__get(VALUE obj, VALUE key) {
   size_t l;
@@ -162,9 +217,9 @@ static VALUE LocalMemCache__get(VALUE obj, VALUE key) {
  *     lmc.set(key, value)   ->   Qnil
  *     lmc[key]=value        ->   Qnil
  *
- *  Set value for key in hashtable.
+ *  Set value for key in hashtable.  Value and key will be converted to
+ *  string.
  */
-
 static VALUE LocalMemCache__set(VALUE obj, VALUE key, VALUE value) {
   local_memcache_t *lmc = get_LocalMemCache(obj);
   if (!local_memcache_set(lmc, rstring_ptr(key), rstring_length(key), 
@@ -178,7 +233,7 @@ static VALUE LocalMemCache__set(VALUE obj, VALUE key, VALUE value) {
  *  call-seq:
  *     lmc.delete(key)   ->   Qnil
  *
- *  Deletes key from hashtable.
+ *  Deletes key from hashtable.  The key is converted to string.
  */
 static VALUE LocalMemCache__delete(VALUE obj, VALUE key) {
   return local_memcache_delete(get_LocalMemCache(obj), 
@@ -244,13 +299,60 @@ static VALUE LocalMemCache__keys(VALUE obj) {
   return rb_ary_entry(d, 1);
 }
 
+/*
+ * Document-class: LocalMemCache
+ * 
+ * <code>LocalMemCache</code> provides for a Hashtable of strings in shared
+ * memory (via a memory mapped file), which thus can be shared between
+ * processes on a computer.  Here is an example of its usage:
+ *
+ *   $lm = LocalMemCache.new :namespace => "viewcounters"
+ *   $lm[:foo] = 1
+ *   $lm[:foo]          # -> "1"
+ *   $lm.delete(:foo)
+ *
+ * <code>LocalMemCache</code> can also be used as a persistent key value
+ * database, just use the :filename instead of the :namespace parameter.
+ *
+ *   $lm = LocalMemCache.new :filename => "my-database.lmc"
+ *   $lm[:foo] = 1
+ *   $lm[:foo]          # -> "1"
+ *   $lm.delete(:foo)
+ *
+ *  == Default sizes of memory pools
+ *
+ *  The default size for memory pools is 1024 (MB). It cannot be changed later,
+ *  so choose a size that will provide enough space for all your data.  You
+ *  might consider setting this size to the maximum filesize of your
+ *  filesystem.  Also note that while these memory pools may look large on your
+ *  disk, they really aren't, because with sparse files only those parts of the
+ *  file which contain non-null data actually use disk space.
+ *
+ *  == Automatic recovery from crashes
+ *
+ *  In case a process is terminated while accessing a memory pool, other
+ *  processes will wait for the lock up to 2 seconds, and will then try to
+ *  resume the aborted operation.  This can also be done explicitly by using
+ *  LocalMemCache.check(options).
+ *
+ *  == Clearing memory pools
+ *
+ *  Removing memory pools can be done with LocalMemCache.clear(options). 
+ *
+ *  == Environment
+ *  
+ *  If you use the :namespace parameter, the .lmc file for your namespace will
+ *  reside in /var/tmp/localmemcache.  This can be overriden by setting the
+ *  LMC_NAMESPACES_ROOT_PATH variable in the environment.
+ *
+ */
 void Init_rblocalmemcache() {
   LocalMemCache = rb_define_class("LocalMemCache", rb_cObject);
-  rb_define_singleton_method(LocalMemCache, "_new", LocalMemCache__new2, 2);
-  rb_define_singleton_method(LocalMemCache, "_clear_namespace", 
-      LocalMemCache__clear_namespace, 2);
-  rb_define_singleton_method(LocalMemCache, "check_namespace", 
-      LocalMemCache__check_namespace, 1);
+  rb_define_singleton_method(LocalMemCache, "_new", LocalMemCache__new2, 1);
+  rb_define_singleton_method(LocalMemCache, "clear", 
+      LocalMemCache__clear, 1);
+  rb_define_singleton_method(LocalMemCache, "check", 
+      LocalMemCache__check, 1);
   rb_define_singleton_method(LocalMemCache, "disable_test_crash", 
       LocalMemCache__disable_test_crash, 0);
   rb_define_singleton_method(LocalMemCache, "enable_test_crash", 
@@ -262,4 +364,9 @@ void Init_rblocalmemcache() {
   rb_define_method(LocalMemCache, "[]=", LocalMemCache__set, 2);
   rb_define_method(LocalMemCache, "keys", LocalMemCache__keys, 0);
   rb_define_method(LocalMemCache, "close", LocalMemCache__close, 0);
+
+  lmc_rb_sym_namespace = ID2SYM(rb_intern("namespace"));
+  lmc_rb_sym_filename = ID2SYM(rb_intern("filename"));
+  lmc_rb_sym_size_mb = ID2SYM(rb_intern("size_mb"));
+  lmc_rb_sym_repair = ID2SYM(rb_intern("repair"));
 }