Cleanup and documentation.

Manifest

@@ -224,9 +224,9 @@ ext/rlibmemcached_wrap.c
 lib/memcached.rb
 lib/memcached/auth.rb
 lib/memcached/behaviors.rb
-lib/memcached/encoder/marshal.rb
 lib/memcached/exceptions.rb
 lib/memcached/experimental.rb
+lib/memcached/marshal_codec.rb
 lib/memcached/memcached.rb
 lib/memcached/rails.rb
 memcached.gemspec

lib/memcached.rb

@@ -27,7 +27,7 @@ class Memcached
 require 'memcached/exceptions'
 require 'memcached/behaviors'
 require 'memcached/auth'
-require 'memcached/encoder/marshal'
+require 'memcached/marshal_codec'
 require 'memcached/memcached'
 require 'memcached/rails'
 require 'memcached/experimental'

lib/memcached/encoder/marshal.rb → lib/memcached/marshal_codec.rb

@@ -1,12 +1,10 @@
 class Memcached
-  class Encoder
-    class Marshal
+  module MarshalCodec
       def self.encode(key, value, flags)
-        [::Marshal.dump(value), flags]
+        [Marshal.dump(value), flags]
       end
       def self.decode(key, value, flags)
-        ::Marshal.load(value)
+        Marshal.load(value)
       end
-    end
   end
 end

lib/memcached/memcached.rb

@@ -33,7 +33,7 @@ class Memcached
     :binary_protocol => false,
     :credentials => nil,
     :experimental_features => false,
-    :encoder => Memcached::Encoder::Marshal,
+    :codec => Memcached::MarshalCodec,
     :exception_retry_limit => 5,
     :exceptions_to_retry => [
         Memcached::ServerIsMarkedDead,
@@ -73,6 +73,7 @@ class Memcached
 
 <tt>:prefix_key</tt>:: A string to prepend to every key, for namespacing. Max length is 127. Defaults to the empty string.
 <tt>:prefix_delimiter</tt>:: A character to append to the prefix key. Defaults to the empty string.
+<tt>:codec</tt>:: An object to use as the codec for encoded requests. Defaults to Memcached::MarshalCodec.
 <tt>:hash</tt>:: The name of a hash function to use. Possible values are: <tt>:crc</tt>, <tt>:default</tt>, <tt>:fnv1_32</tt>, <tt>:fnv1_64</tt>, <tt>:fnv1a_32</tt>, <tt>:fnv1a_64</tt>, <tt>:hsieh</tt>, <tt>:md5</tt>, <tt>:murmur</tt>, and <tt>:none</tt>. <tt>:fnv1_32</tt> is fast and well known, and is the default. Use <tt>:md5</tt> for compatibility with other ketama clients. <tt>:none</tt> is for use when there is a single server, and performs no actual hashing.
 <tt>:distribution</tt>:: Either <tt>:modula</tt>, <tt>:consistent_ketama</tt>, <tt>:consistent_wheel</tt>, or <tt>:ketama</tt>. Defaults to <tt>:ketama</tt>.
 <tt>:server_failure_limit</tt>:: How many consecutive failures to allow before marking a host as dead. Has no effect unless <tt>:retry_timeout</tt> is also set.
@@ -110,7 +111,7 @@ def initialize(servers = nil, opts = {})
 
     # Marginally speed up settings access for hot paths
     @default_ttl = options[:default_ttl]
-    @encoder = options[:encoder]
+    @codec = options[:codec]
 
     if servers == nil || servers == []
       if ENV.key?("MEMCACHE_SERVERS")
@@ -301,10 +302,10 @@ def server_structs
   #
   # Accepts an optional <tt>ttl</tt> value to specify the maximum lifetime of the key on the server, in seconds. <tt>ttl</tt> must be a <tt>FixNum</tt>. <tt>0</tt> means no ttl. Note that there is no guarantee that the key will persist as long as the <tt>ttl</tt>, but it will not persist longer.
   #
-  # Also accepts an <tt>encode</tt> value, which defaults to <tt>true</tt> and uses the default Marshal encoder. Set <tt>encode</tt> to <tt>false</tt>, and pass a String as the <tt>value</tt>, if you want to set a raw byte array.
+  # Also accepts an <tt>encode</tt> value, which defaults to <tt>true</tt> and uses the default Marshal codec. Set <tt>encode</tt> to <tt>false</tt>, and pass a String as the <tt>value</tt>, if you want to set a raw byte array.
   #
   def set(key, value, ttl=@default_ttl, encode=true, flags=FLAGS)
-    value, flags = @encoder.encode(key, value, flags) if encode
+    value, flags = @codec.encode(key, value, flags) if encode
     begin
       check_return_code(
         Lib.memcached_set(@struct, key, value, ttl, flags),
@@ -321,7 +322,7 @@ def set(key, value, ttl=@default_ttl, encode=true, flags=FLAGS)
 
   # Add a key/value pair. Raises <b>Memcached::NotStored</b> if the key already exists on the server. The parameters are the same as <tt>set</tt>.
   def add(key, value, ttl=@default_ttl, encode=true, flags=FLAGS)
-    value, flags = @encoder.encode(key, value, flags) if encode
+    value, flags = @codec.encode(key, value, flags) if encode
     begin
       check_return_code(
         Lib.memcached_add(@struct, key, value, ttl, flags),
@@ -370,7 +371,7 @@ def decrement(key, offset=1)
 
   # Replace a key/value pair. Raises <b>Memcached::NotFound</b> if the key does not exist on the server. The parameters are the same as <tt>set</tt>.
   def replace(key, value, ttl=@default_ttl, encode=true, flags=FLAGS)
-    value, flags = @encoder.encode(key, value, flags) if encode
+    value, flags = @codec.encode(key, value, flags) if encode
     begin
       check_return_code(
         Lib.memcached_replace(@struct, key, value, ttl, flags),
@@ -435,9 +436,9 @@ def cas(key, ttl=@default_ttl, encode=true, flags=FLAGS)
 
     cas = @struct.result.cas
 
-    value = @encoder.decode(key, value, flags) if encode
+    value = @codec.decode(key, value, flags) if encode
     value = yield value
-    value, flags = @encoder.encode(key, value, flags) if encode
+    value, flags = @codec.encode(key, value, flags) if encode
 
     begin
       check_return_code(
@@ -511,15 +512,15 @@ def get(keys, encode=true)
       end
       if encode
         hash.each do |key, value_and_flags|
-          hash[key] = @encoder.decode(key, *value_and_flags)
+          hash[key] = @codec.decode(key, *value_and_flags)
         end
       end
       hash
     else
       # Single get
       value, flags, ret = Lib.memcached_get_rvalue(@struct, keys)
       check_return_code(ret, keys)
-      encode ? @encoder.decode(keys, value, flags) : value
+      encode ? @codec.decode(keys, value, flags) : value
     end
   rescue => e
     tries ||= 0
@@ -542,7 +543,7 @@ def get_from_last(key, encode=true)
     raise ArgumentError, "get_from_last() is not useful unless :random distribution is enabled." unless options[:distribution] == :random
     value, flags, ret = Lib.memcached_get_from_last_rvalue(@struct, key)
     check_return_code(ret, key)
-    encode ? @encoder.decode(key, value, flags) : value
+    encode ? @codec.decode(key, value, flags) : value
   end
 
   ### Information methods