boourns-memcached 1.4.6

data/ext/share/man/man3/memcached_version.3

@@ -0,0 +1,176 @@
+.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "..::docs::memcached_version 3"
+.TH ..::docs::memcached_version 3 "2012-10-24" "" "libmemcached"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+memcached_lib_version, memcached_version \- Get library version
+.SH "LIBRARY"
+.IX Header "LIBRARY"
+C Client Library for memcached (libmemcached, \-lmemcached)
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\&  #include <memcached.h>
+\&
+\&  const char *
+\&    memcached_lib_version(void) 
+\&
+\&
+\&  memcached_return
+\&    memcached_version(memcached_st *ptr)
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fImemcached_lib_version()\fR is used to return a simple version string representing
+the libmemcached version (version of the client library, not server)
+.PP
+\&\fImemcached_version()\fR is used to set the major, minor, and micro versions of each
+memcached server being used by the memcached_st connection structure. It returns the 
+memcached server return code.
+.SH "RETURN"
+.IX Header "RETURN"
+A string with the version of libmemcached driver is returned from
+\&\fImemcached_lib_version()\fR
+.PP
+A value of type \f(CW\*(C`memcached_return\*(C'\fR is returned from \fImemcached_version()\fR
+On success that value will be \f(CW\*(C`MEMCACHED_SUCCESS\*(C'\fR. If called with the
+\&\f(CW\*(C`MEMCACHED_BEHAVIOR_USE_UDP\*(C'\fR behavior set, the value \f(CW\*(C`MEMCACHED_NOT_SUPPORTED\*(C'\fR 
+will be returned. Use \fImemcached_strerror()\fR to translate this value to 
+a printable string.
+.SH "HOME"
+.IX Header "HOME"
+To find out more information please check:
+<http://tangent.org/552/libmemcached.html>
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Brian Aker, <brian@tangent.org>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fImemcached\fR\|(1) \fIlibmemcached\fR\|(3) \fImemcached_strerror\fR\|(3)

data/lib/memcached.rb

@@ -0,0 +1,32 @@
+
+=begin rdoc
+The generated SWIG module for accessing libmemcached's C API.
+
+Includes the full set of libmemcached static methods (as defined in <tt>$INCLUDE_PATH/libmemcached/memcached.h</tt>), and classes for the available structs:
+
+* <b>Rlibmemcached::MemcachedResultSt</b>
+* <b>Rlibmemcached::MemcachedServerSt</b>
+* <b>Rlibmemcached::MemcachedSt</b>
+* <b>Rlibmemcached::MemcachedStatSt</b>
+* <b>Rlibmemcached::MemcachedStringSt</b>
+
+A number of SWIG typemaps and C helper methods are also defined in <tt>ext/libmemcached.i</tt>.
+
+=end
+module Rlibmemcached
+end
+
+require 'rlibmemcached'
+
+class Memcached
+  Lib = Rlibmemcached
+  raise "libmemcached 0.32 required; you somehow linked to #{Lib.memcached_lib_version}." unless "0.32" == Lib.memcached_lib_version
+  VERSION = File.read("#{File.dirname(__FILE__)}/../CHANGELOG")[/v([\d\.]+)\./, 1]
+end
+
+require 'memcached/exceptions'
+require 'memcached/behaviors'
+require 'memcached/auth'
+require 'memcached/memcached'
+require 'memcached/rails'
+require 'memcached/experimental'

data/lib/memcached/behaviors.rb

@@ -0,0 +1,77 @@
+
+class Memcached
+
+#:stopdoc:
+
+  def self.load_constants(prefix, hash = {})
+    Lib.constants.grep(/^#{prefix}/).each do |const_name|
+      hash[const_name[prefix.length..-1].downcase.to_sym] = Lib.const_get(const_name)
+    end
+    hash
+  end
+
+  BEHAVIORS = load_constants("MEMCACHED_BEHAVIOR_")
+
+  BEHAVIOR_VALUES = {
+    false => 0,
+    true => 1
+  }
+
+  HASH_VALUES = {}
+  BEHAVIOR_VALUES.merge!(load_constants("MEMCACHED_HASH_", HASH_VALUES))
+
+  DISTRIBUTION_VALUES = {}
+  BEHAVIOR_VALUES.merge!(load_constants("MEMCACHED_DISTRIBUTION_", DISTRIBUTION_VALUES))
+
+  DIRECT_VALUE_BEHAVIORS = [:retry_timeout, :connect_timeout, :rcv_timeout, :socket_recv_size, :poll_timeout, :socket_send_size, :server_failure_limit]
+
+  CONVERSION_FACTORS = {
+    :rcv_timeout => 1_000_000,
+    :poll_timeout => 1_000,
+    :connect_timeout => 1_000
+  }
+
+#:startdoc:
+
+  private
+
+  # Set a behavior option for this Memcached instance. Accepts a Symbol <tt>behavior</tt> and either <tt>true</tt>, <tt>false</tt>, or a Symbol for <tt>value</tt>. Arguments are validated and converted into integers for the struct setter method.
+  def set_behavior(behavior, value) #:doc:
+    raise ArgumentError, "No behavior #{behavior.inspect}" unless b_id = BEHAVIORS[behavior]
+
+    # Scoped validations; annoying
+    msg =  "Invalid behavior value #{value.inspect} for #{behavior.inspect}"
+    case behavior
+      when :hash then raise(ArgumentError, msg) unless HASH_VALUES[value]
+      when :distribution then raise(ArgumentError, msg) unless DISTRIBUTION_VALUES[value]
+      when *DIRECT_VALUE_BEHAVIORS then raise(ArgumentError, msg) unless value.is_a?(Numeric) and value >= 0
+      else
+        raise(ArgumentError, msg) unless BEHAVIOR_VALUES[value]
+    end
+
+    lib_value = BEHAVIOR_VALUES[value] || (value * (CONVERSION_FACTORS[behavior] || 1)).to_i
+    #STDERR.puts "Setting #{behavior}:#{b_id} => #{value} (#{lib_value})"
+    Lib.memcached_behavior_set(@struct, b_id, lib_value)
+    #STDERR.puts " -> set to #{get_behavior(behavior).inspect}"
+  end
+
+  # Get a behavior value for this Memcached instance. Accepts a Symbol.
+  def get_behavior(behavior)
+    raise ArgumentError, "No behavior #{behavior.inspect}" unless b_id = BEHAVIORS[behavior]
+    value = Lib.memcached_behavior_get(@struct, b_id)
+
+    if BEHAVIOR_VALUES.invert.has_key?(value)
+      # False, nil are valid values so we can not rely on direct lookups
+      case behavior
+        # Scoped values; still annoying
+        when :hash then HASH_VALUES.invert[value]
+        when :distribution then DISTRIBUTION_VALUES.invert[value]
+        else
+          value
+      end
+    else
+      value
+    end
+  end
+
+end

data/lib/memcached/exceptions.rb

@@ -0,0 +1,84 @@
+
+class Memcached
+
+=begin rdoc
+
+Superclass for all Memcached runtime exceptions.
+
+Subclasses correspond one-to-one with server response strings or libmemcached errors. For example, raising <b>Memcached::NotFound</b> means that the server returned <tt>"NOT_FOUND\r\n"</tt>.
+
+== Subclasses
+
+* Memcached::ABadKeyWasProvidedOrCharactersOutOfRange
+* Memcached::AKeyLengthOfZeroWasProvided
+* Memcached::ATimeoutOccurred
+* Memcached::ActionNotSupported
+* Memcached::ActionQueued
+* Memcached::ClientError
+* Memcached::ConnectionBindFailure
+* Memcached::ConnectionDataDoesNotExist
+* Memcached::ConnectionDataExists
+* Memcached::ConnectionFailure
+* Memcached::ConnectionSocketCreateFailure
+* Memcached::CouldNotOpenUnixSocket
+* Memcached::EncounteredAnUnknownStatKey
+* Memcached::Failure
+* Memcached::FetchWasNotCompleted
+* Memcached::HostnameLookupFailure
+* Memcached::ItemValue
+* Memcached::MemoryAllocationFailure
+* Memcached::NoServersDefined
+* Memcached::NotFound
+* Memcached::NotStored
+* Memcached::PartialRead
+* Memcached::ProtocolError
+* Memcached::ReadFailure
+* Memcached::ServerDelete
+* Memcached::ServerEnd
+* Memcached::ServerError
+* Memcached::ServerIsMarkedDead
+* Memcached::ServerValue
+* Memcached::SomeErrorsWereReported
+* Memcached::StatValue
+* Memcached::SystemError
+* Memcached::TheHostTransportProtocolDoesNotMatchThatOfTheClient
+* Memcached::UnknownReadFailure
+* Memcached::WriteFailure
+
+=end
+  class Error < RuntimeError
+    attr_accessor :no_backtrace
+
+    def set_backtrace(*args)
+      @no_backtrace ? [] : super
+    end
+
+    def backtrace(*args)
+      @no_backtrace ? [] : super
+    end
+  end
+
+#:stopdoc:
+
+  class << self
+    private
+    def camelize(string)
+      string.downcase.gsub('/', ' or ').split(' ').map {|s| s.capitalize}.join
+    end
+  end
+
+  ERRNO_HASH = Hash[*Errno.constants.grep(/^E/).map{ |c| [Errno.const_get(c)::Errno, Errno.const_get(c).new.message] }.flatten]
+
+  EXCEPTIONS = []
+  empty_struct = Lib.memcached_create(nil)
+  Lib.memcached_create(empty_struct)
+
+  # Generate exception classes
+  Lib::MEMCACHED_MAXIMUM_RETURN.times do |index|
+    description = Lib.memcached_strerror(empty_struct, index).gsub("!", "")
+    exception_class = eval("class #{camelize(description)} < Error; self; end")
+    EXCEPTIONS << exception_class
+  end
+
+#:startdoc:
+end

data/lib/memcached/experimental.rb

@@ -0,0 +1,48 @@
+class Memcached
+  module Experimental
+
+    # TOUCH is used to set a new expiration time for an existing item
+    def touch(key, ttl=@default_ttl)
+      check_return_code(
+        Lib.memcached_touch(@struct, key, ttl),
+        key
+      )
+    rescue => e
+      tries ||= 0
+      raise unless tries < options[:exception_retry_limit] && should_retry(e)
+      tries += 1
+      retry
+    end
+
+    def get_len(bytes, keys)
+      if keys.is_a? ::Array
+        # Multi get
+        ret = Lib.memcached_mget_len(@struct, keys, bytes);
+        check_return_code(ret, keys)
+
+        hash = {}
+        keys.each do
+          value, key, flags, ret = Lib.memcached_fetch_rvalue(@struct)
+          break if ret == Lib::MEMCACHED_END
+          if ret != Lib::MEMCACHED_NOTFOUND
+            check_return_code(ret, key)
+            # Assign the value
+            hash[key] = value
+          end
+        end
+        hash
+      else
+        # Single get_len
+        value, flags, ret = Lib.memcached_get_len_rvalue(@struct, keys, bytes)
+        check_return_code(ret, keys)
+        value
+      end
+    rescue => e
+      tries ||= 0
+      raise unless tries < options[:exception_retry_limit] && should_retry(e)
+      tries += 1
+      retry
+    end
+
+  end
+end

data/lib/memcached/memcached.rb

@@ -0,0 +1,683 @@
+=begin rdoc
+The Memcached client class.
+=end
+class Memcached
+  FLAGS = 0x0
+
+  DEFAULTS = {
+    :hash => :fnv1_32,
+    :no_block => false,
+    :noreply => false,
+    :distribution => :consistent_ketama,
+    :ketama_weighted => true,
+    :buffer_requests => false,
+    :cache_lookups => true,
+    :support_cas => false,
+    :tcp_nodelay => false,
+    :show_backtraces => false,
+    :retry_timeout => 30,
+    :timeout => 0.25,
+    :rcv_timeout => nil,
+    :poll_timeout => nil,
+    :connect_timeout => 4,
+    :prefix_key => '',
+    :prefix_delimiter => '',
+    :hash_with_prefix_key => true,
+    :default_ttl => 604800,
+    :default_weight => 8,
+    :sort_hosts => false,
+    :auto_eject_hosts => true,
+    :server_failure_limit => 2,
+    :verify_key => true,
+    :use_udp => false,
+    :binary_protocol => false,
+    :credentials => nil,
+    :experimental_features => false,
+    :exception_retry_limit => 5,
+    :exceptions_to_retry => [
+        Memcached::ServerIsMarkedDead,
+        Memcached::ATimeoutOccurred,
+        Memcached::ConnectionBindFailure,
+        Memcached::ConnectionFailure,
+        Memcached::ConnectionSocketCreateFailure,
+        Memcached::Failure,
+        Memcached::MemoryAllocationFailure,
+        Memcached::ReadFailure,
+        Memcached::ServerEnd,
+        Memcached::ServerError,
+        Memcached::SystemError,
+        Memcached::UnknownReadFailure,
+        Memcached::WriteFailure,
+        Memcached::SomeErrorsWereReported]
+  }
+
+#:stopdoc:
+  IGNORED = 0
+#:startdoc:
+
+  attr_reader :options # Return the options Hash used to configure this instance.
+
+###### Configuration
+
+=begin rdoc
+Create a new Memcached instance. Accepts string or array of server strings, as well an an optional configuration hash.
+
+  Memcached.new('localhost', ...) # A single server
+  Memcached.new(['web001:11212', 'web002:11212'], ...) # Two servers with custom ports
+  Memcached.new(['web001:11211:2', 'web002:11211:8'], ...) # Two servers with default ports and explicit weights
+
+Weights only affect Ketama hashing.  If you use Ketama hashing and don't specify a weight, the client will poll each server's stats and use its size as the weight.
+
+Valid option parameters are:
+
+<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>: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.
+<tt>:retry_timeout</tt>:: How long to wait until retrying a dead server. Has no effect unless <tt>:server_failure_limit</tt> is non-zero. Defaults to <tt>30</tt>.
+<tt>:auto_eject_hosts</tt>:: Whether to temporarily eject dead hosts from the pool. Defaults to <tt>true</tt>. Note that in the event of an ejection, <tt>:auto_eject_hosts</tt> will remap the entire pool unless <tt>:distribution</tt> is set to <tt>:consistent</tt>.
+<tt>:exception_retry_limit</tt>:: How many times to retry before raising exceptions in <tt>:exceptions_to_retry</tt>. Defaults to <tt>5</tt>.
+<tt>:exceptions_to_retry</tt>:: Which exceptions to retry. Defaults to <b>ServerIsMarkedDead</b>, <b>ATimeoutOccurred</b>, <b>ConnectionBindFailure</b>, <b>ConnectionFailure</b>, <b>ConnectionSocketCreateFailure</b>, <b>Failure</b>, <b>MemoryAllocationFailure</b>, <b>ReadFailure</b>, <b>ServerError</b>, <b>SystemError</b>, <b>UnknownReadFailure</b>, and <b>WriteFailure</b>.
+<tt>:cache_lookups</tt>:: Whether to cache hostname lookups for the life of the instance. Defaults to <tt>true</tt>.
+<tt>:support_cas</tt>:: Flag CAS support in the client. Accepts <tt>true</tt> or <tt>false</tt>. Defaults to <tt>false</tt> because it imposes a slight performance penalty. Note that your server must also support CAS or you will trigger <b>ProtocolError</b> exceptions.
+<tt>:tcp_nodelay</tt>:: Turns on the no-delay feature for connecting sockets. Accepts <tt>true</tt> or <tt>false</tt>. Performance may or may not change, depending on your system.
+<tt>:no_block</tt>:: Whether to use pipelining for writes. Defaults to <tt>false</tt>.
+<tt>:buffer_requests</tt>:: Whether to use an internal write buffer. Accepts <tt>true</tt> or <tt>false</tt>. Calling <tt>get</tt> or closing the connection will force the buffer to flush. Client behavior is undefined unless <tt>:no_block</tt> is enabled. Defaults to <tt>false</tt>.
+<tt>:noreply</tt>:: Ask server not to reply for storage commands. Client behavior is undefined unless <tt>:no_block</tt> and <tt>:buffer_requests</tt> are enabled. Defaults to <tt>false</tt>.
+<tt>:show_backtraces</tt>:: Whether <b>NotFound</b> and <b>NotStored</b> exceptions should include backtraces. Generating backtraces is slow, so this is off by default. Turn it on to ease debugging.
+<tt>:connect_timeout</tt>:: How long to wait for a connection to a server. Defaults to 2 seconds. Set to <tt>0</tt> if you want to wait forever.
+<tt>:timeout</tt>:: How long to wait for a response from the server. Defaults to 0.25 seconds. Set to <tt>0</tt> if you want to wait forever.
+<tt>:default_ttl</tt>:: The <tt>ttl</tt> to use on set if no <tt>ttl</tt> is specified, in seconds. Defaults to one week. Set to <tt>0</tt> if you want things to never expire.
+<tt>:default_weight</tt>:: The weight to use if <tt>:ketama_weighted</tt> is <tt>true</tt>, but no weight is specified for a server.
+<tt>:hash_with_prefix_key</tt>:: Whether to include the prefix when calculating which server a key falls on. Defaults to <tt>true</tt>.
+<tt>:use_udp</tt>:: Use the UDP protocol to reduce connection overhead. Defaults to false.
+<tt>:binary_protocol</tt>:: Use the binary protocol. Defaults to false. Please note that using the binary protocol is usually <b>slower</b> than the ASCII protocol.
+<tt>:sort_hosts</tt>:: Whether to force the server list to stay sorted. This defeats consistent hashing and is rarely useful.
+<tt>:verify_key</tt>:: Validate keys before accepting them. Never disable this.
+
+Please note that when <tt>:no_block => true</tt>, update methods do not raise on errors. For example, if you try to <tt>set</tt> an invalid key, it will appear to succeed. The actual setting of the key occurs after libmemcached has returned control to your program, so there is no way to backtrack and raise the exception.
+
+=end
+
+  def initialize(servers = nil, opts = {})
+    @struct = Lib.memcached_create(nil)
+
+    # Merge option defaults and discard meaningless keys
+    @options = DEFAULTS.merge(opts)
+    @options.delete_if { |k,v| not DEFAULTS.keys.include? k }
+    @default_ttl = options[:default_ttl]
+
+    if servers == nil || servers == []
+      if ENV.key?("MEMCACHE_SERVERS")
+        servers = ENV["MEMCACHE_SERVERS"].split(",").map do | s | s.strip end
+      else
+        servers = "127.0.0.1:11211"
+      end
+    end
+
+    if !options[:credentials] and ENV["MEMCACHE_USERNAME"] and ENV["MEMCACHE_PASSWORD"]
+      options[:credentials] = [ENV["MEMCACHE_USERNAME"], ENV["MEMCACHE_PASSWORD"]]
+    end
+
+    instance_eval { send(:extend, Experimental) } if options[:experimental_features]
+
+    # SASL requires binary protocol
+    options[:binary_protocol] = true if options[:credentials]
+
+    # UDP requires noreply
+    options[:noreply] = true if options[:use_udp]
+
+    # Buffering requires non-blocking
+    # FIXME This should all be wrapped up in a single :pipeline option.
+    options[:no_block] = true if options[:buffer_requests]
+
+    # Disallow weights without ketama
+    options.delete(:ketama_weighted) if options[:distribution] != :consistent_ketama
+
+    # Disallow :sort_hosts with consistent hashing
+    if options[:sort_hosts] and options[:distribution] == :consistent
+      raise ArgumentError, ":sort_hosts defeats :consistent hashing"
+    end
+
+    # Read timeouts
+    options[:rcv_timeout] ||= options[:timeout]
+    options[:poll_timeout] ||= options[:timeout]
+
+    # Set the prefix key. Support the legacy name.
+    set_prefix_key(options[:prefix_key] || options[:namespace])
+
+    # Set the behaviors and credentials on the struct
+    set_behaviors
+    set_credentials
+
+    # Freeze the hash
+    options.freeze
+
+    # Set the servers on the struct
+    set_servers(servers)
+
+    # Not found exceptions
+    if options[:show_backtraces]
+      # Raise classes for full context
+      @not_found = NotFound
+      @not_stored = NotStored
+    else
+      # Raise fast context-free exception instances
+      @not_found = NotFound.new
+      @not_found.no_backtrace = true
+      @not_stored = NotStored.new
+      @not_stored.no_backtrace = true
+    end
+  end
+
+  # Set the server list.
+  # FIXME Does not necessarily free any existing server structs.
+  def set_servers(servers)
+    Array(servers).each_with_index do |server, index|
+      # Socket
+      check_return_code(
+        if server.is_a?(String) and File.socket?(server)
+          args = [@struct, server, options[:default_weight].to_i]
+          Lib.memcached_server_add_unix_socket_with_weight(*args)
+        # Network
+        elsif server.is_a?(String) and server =~ /^[\w\d\.-]+(:\d{1,5}){0,2}$/
+          host, port, weight = server.split(":")
+          args = [@struct, host, port.to_i, (weight || options[:default_weight]).to_i]
+          if options[:use_udp]
+            Lib.memcached_server_add_udp_with_weight(*args)
+          else
+            Lib.memcached_server_add_with_weight(*args)
+          end
+        else
+          raise ArgumentError, "Servers must be either in the format 'host:port[:weight]' (e.g., 'localhost:11211' or  'localhost:11211:10') for a network server, or a valid path to a Unix domain socket (e.g., /var/run/memcached)."
+        end
+      )
+    end
+  end
+
+  # Return the array of server strings used to configure this instance.
+  def servers
+    server_structs.map do |server|
+      inspect_server(server)
+    end
+  end
+
+  # Set the prefix key.
+  def set_prefix_key(key)
+    check_return_code(
+      if key
+        key += options[:prefix_delimiter]
+        raise ArgumentError, "Max prefix key + prefix delimiter size is #{Lib::MEMCACHED_PREFIX_KEY_MAX_SIZE - 1}" unless
+          key.size < Lib::MEMCACHED_PREFIX_KEY_MAX_SIZE
+        Lib.memcached_callback_set(@struct, Lib::MEMCACHED_CALLBACK_PREFIX_KEY, key)
+      else
+        Lib.memcached_callback_set(@struct, Lib::MEMCACHED_CALLBACK_PREFIX_KEY, "")
+      end
+    )
+  end
+  alias :set_namespace :set_prefix_key
+
+  # Return the current prefix key.
+  def prefix_key
+    if @struct.prefix_key.size > 0
+      @struct.prefix_key[0..-1 - options[:prefix_delimiter].size]
+    else
+      ""
+    end
+  end
+  alias :namespace :prefix_key
+
+  # Safely copy this instance. Returns a Memcached instance.
+  #
+  # <tt>clone</tt> is useful for threading, since each thread must have its own unshared Memcached
+  # object.
+  #
+  def clone
+    memcached = super
+    struct = Lib.memcached_clone(nil, @struct)
+    memcached.instance_variable_set('@struct', struct)
+    memcached
+  end
+
+  # Reset the state of the libmemcached struct. This is useful for changing the server list at runtime.
+  def reset(current_servers = nil)
+    # Store state and teardown
+    current_servers ||= servers
+    prev_prefix_key = prefix_key
+    quit
+
+    # Create
+    # FIXME Duplicates logic with initialize()
+    @struct = Lib.memcached_create(nil)
+    set_prefix_key(prev_prefix_key)
+    set_behaviors
+    set_credentials
+    set_servers(current_servers)
+  end
+
+  # Disconnect from all currently connected servers
+  def quit
+    Lib.memcached_quit(@struct)
+    self
+  end
+
+  # Should retry the exception
+  def should_retry(e)
+    options[:exceptions_to_retry].each {|ex_class| return true if e.instance_of?(ex_class)}
+    false
+  end
+
+  #:stopdoc:
+  alias :dup :clone #:nodoc:
+  #:startdoc:
+
+### Configuration helpers
+
+  private
+
+  # Return an array of raw <tt>memcached_host_st</tt> structs for this instance.
+  def server_structs
+    array = []
+    if @struct.hosts
+      @struct.hosts.count.times do |i|
+        array << Lib.memcached_select_server_at(@struct, i)
+      end
+    end
+    array
+  end
+
+###### Operations
+
+  public
+
+### Setters
+
+  # Set a key/value pair. Accepts a String <tt>key</tt> and an arbitrary Ruby object. Overwrites any existing value on the server.
+  #
+  # 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 a <tt>marshal</tt> value, which defaults to <tt>true</tt>. Set <tt>marshal</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, marshal=true, flags=FLAGS)
+    value = marshal ? Marshal.dump(value) : value
+    begin
+      check_return_code(
+        Lib.memcached_set(@struct, key, value, ttl, flags),
+        key
+      )
+    rescue => e
+      tries ||= 0
+      retry if e.instance_of?(ClientError) && !tries
+      raise unless tries < options[:exception_retry_limit] && should_retry(e)
+      tries += 1
+      retry
+    end
+  end
+
+  # 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, marshal=true, flags=FLAGS)
+    value = marshal ? Marshal.dump(value) : value
+    begin
+      check_return_code(
+        Lib.memcached_add(@struct, key, value, ttl, flags),
+        key
+      )
+    rescue => e
+      tries ||= 0
+      raise unless tries < options[:exception_retry_limit] && should_retry(e)
+      tries += 1
+      retry
+    end
+  end
+
+  # Increment a key's value. Accepts a String <tt>key</tt>. Raises <b>Memcached::NotFound</b> if the key does not exist.
+  #
+  # Also accepts an optional <tt>offset</tt> paramater, which defaults to 1. <tt>offset</tt> must be an integer.
+  #
+  # Note that the key must be initialized to an unmarshalled integer first, via <tt>set</tt>, <tt>add</tt>, or <tt>replace</tt> with <tt>marshal</tt> set to <tt>false</tt>.
+  def increment(key, offset=1)
+    ret, value = Lib.memcached_increment(@struct, key, offset)
+    check_return_code(ret, key)
+    value
+  rescue => e
+    tries ||= 0
+    raise unless tries < options[:exception_retry_limit] && should_retry(e)
+    tries += 1
+    retry
+  end
+
+  # Decrement a key's value. The parameters and exception behavior are the same as <tt>increment</tt>.
+  def decrement(key, offset=1)
+    ret, value = Lib.memcached_decrement(@struct, key, offset)
+    check_return_code(ret, key)
+    value
+  rescue => e
+    tries ||= 0
+    raise unless tries < options[:exception_retry_limit] && should_retry(e)
+    tries += 1
+    retry
+  end
+
+  #:stopdoc:
+  alias :incr :increment
+  alias :decr :decrement
+  #:startdoc:
+
+  # 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, marshal=true, flags=FLAGS)
+    value = marshal ? Marshal.dump(value) : value
+    begin
+      check_return_code(
+         Lib.memcached_replace(@struct, key, value, ttl, flags),
+        key
+      )
+    rescue => e
+      tries ||= 0
+      raise unless tries < options[:exception_retry_limit] && should_retry(e)
+      tries += 1
+      retry
+    end
+  end
+
+  # Appends a string to a key's value. Accepts a String <tt>key</tt> and a String <tt>value</tt>. Raises <b>Memcached::NotFound</b> if the key does not exist on the server.
+  #
+  # Note that the key must be initialized to an unmarshalled string first, via <tt>set</tt>, <tt>add</tt>, or <tt>replace</tt> with <tt>marshal</tt> set to <tt>false</tt>.
+  def append(key, value)
+    # Requires memcached 1.2.4
+    check_return_code(
+      Lib.memcached_append(@struct, key, value.to_s, IGNORED, IGNORED),
+      key
+    )
+  rescue => e
+    tries ||= 0
+    raise unless tries < options[:exception_retry_limit] && should_retry(e)
+    tries += 1
+    retry
+  end
+
+  # Prepends a string to a key's value. The parameters and exception behavior are the same as <tt>append</tt>.
+  def prepend(key, value)
+    # Requires memcached 1.2.4
+    check_return_code(
+      Lib.memcached_prepend(@struct, key, value.to_s, IGNORED, IGNORED),
+      key
+    )
+  rescue => e
+    tries ||= 0
+    raise unless tries < options[:exception_retry_limit] && should_retry(e)
+    tries += 1
+    retry
+  end
+
+  # Reads a key's value from the server and yields it to a block. Replaces the key's value with the result of the block as long as the key hasn't been updated in the meantime, otherwise raises <b>Memcached::NotStored</b>. Accepts a String <tt>key</tt> and a block.
+  #
+  # Also accepts an optional <tt>ttl</tt> value.
+  #
+  # CAS stands for "compare and swap", and avoids the need for manual key mutexing. CAS support must be enabled in Memcached.new or a <b>Memcached::ClientError</b> will be raised. Note that CAS may be buggy in memcached itself.
+  # :retry_on_exceptions does not apply to this method
+  def cas(key, ttl=@default_ttl, marshal=true, flags=FLAGS)
+    raise ClientError, "CAS not enabled for this Memcached instance" unless options[:support_cas]
+
+    begin
+      value, flags, ret = Lib.memcached_get_rvalue(@struct, key)
+      check_return_code(ret, key)
+    rescue => e
+      tries_for_get ||= 0
+      raise unless tries_for_get < options[:exception_retry_limit] && should_retry(e)
+      tries_for_get += 1
+      retry
+    end
+
+    cas = @struct.result.cas
+
+    value = Marshal.load(value) if marshal
+    value = yield value
+    value = Marshal.dump(value) if marshal
+
+    begin
+      check_return_code(
+        Lib.memcached_cas(@struct, key, value, ttl, flags, cas),
+        key
+      )
+    rescue => e
+      tries_for_cas ||= 0
+      raise unless tries_for_cas < options[:exception_retry_limit] && should_retry(e)
+      tries_for_cas += 1
+      retry
+    end
+  end
+
+  alias :compare_and_swap :cas
+
+### Deleters
+
+  # Deletes a key/value pair from the server. Accepts a String <tt>key</tt>. Raises <b>Memcached::NotFound</b> if the key does not exist.
+  def delete(key)
+    check_return_code(
+      Lib.memcached_delete(@struct, key, IGNORED),
+      key
+    )
+  rescue => e
+    tries ||= 0
+    raise unless tries < options[:exception_retry_limit] && should_retry(e)
+    tries += 1
+    retry
+  end
+
+  # Flushes all key/value pairs from all the servers.
+  def flush
+    check_return_code(
+      Lib.memcached_flush(@struct, IGNORED)
+    )
+  rescue => e
+    tries ||= 0
+    raise unless tries < options[:exception_retry_limit] && should_retry(e)
+    tries += 1
+    retry
+  end
+
+### Getters
+
+  # Gets a key's value from the server. Accepts a String <tt>key</tt> or array of String <tt>keys</tt>.
+  #
+  # Also accepts a <tt>marshal</tt> value, which defaults to <tt>true</tt>. Set <tt>marshal</tt> to <tt>false</tt> if you want the <tt>value</tt> to be returned directly as a String. Otherwise it will be assumed to be a marshalled Ruby object and unmarshalled.
+  #
+  # If you pass a String key, and the key does not exist on the server, <b>Memcached::NotFound</b> will be raised. If you pass an array of keys, memcached's <tt>multiget</tt> mode will be used, and a hash of key/value pairs will be returned. The hash will contain only the keys that were found.
+  #
+  # The multiget behavior is subject to change in the future; however, for multiple lookups, it is much faster than normal mode.
+  #
+  # Note that when you rescue Memcached::NotFound exceptions, you should use a the block rescue syntax instead of the inline syntax. Block rescues are very fast, but inline rescues are very slow.
+  #
+  def get(keys, marshal=true)
+    if keys.is_a? Array
+      # Multi get
+      ret = Lib.memcached_mget(@struct, keys);
+      check_return_code(ret, keys)
+
+      hash = {}
+      value, key, flags, ret = Lib.memcached_fetch_rvalue(@struct)
+      while ret != 21 do # Lib::MEMCACHED_END
+        if ret == 0 # Lib::MEMCACHED_SUCCESS
+          hash[key] = value
+        elsif ret != 16 # Lib::MEMCACHED_NOTFOUND
+          check_return_code(ret, key)
+        end
+        value, key, flags, ret = Lib.memcached_fetch_rvalue(@struct)
+      end
+      if marshal
+        hash.each do |key, value|
+          hash[key] = Marshal.load(value)
+        end
+      end
+      hash
+    else
+      # Single get
+      value, flags, ret = Lib.memcached_get_rvalue(@struct, keys)
+      check_return_code(ret, keys)
+      marshal ? Marshal.load(value) : value
+    end
+  rescue => e
+    tries ||= 0
+    raise unless tries < options[:exception_retry_limit] && should_retry(e)
+    tries += 1
+    retry
+  end
+
+  # Check if a key exists on the server. It will return nil if the value is found, or raise
+  # <tt>Memcached::NotFound</tt> if the key does not exist.
+  def exist(key)
+    check_return_code(
+      Lib.memcached_exist(@struct, key),
+      key
+    )
+  end
+
+  # Gets a key's value from the previous server. Only useful with random distribution.
+  def get_from_last(key, marshal=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)
+    marshal ? Marshal.load(value) : value
+  end
+
+  ### Information methods
+
+  # Return the server used by a particular key.
+  def server_by_key(key)
+    ret = Lib.memcached_server_by_key(@struct, key)
+    if ret.is_a?(Array)
+      check_return_code(ret.last)
+      inspect_server(ret.first)
+    else
+      check_return_code(ret)
+    end
+  rescue ABadKeyWasProvidedOrCharactersOutOfRange
+  end
+
+  # Return a Hash of statistics responses from the set of servers. Each value is an array with one entry for each server, in the same order the servers were defined.
+  def stats(subcommand = nil)
+    stats = Hash.new([])
+
+    stat_struct, ret = Lib.memcached_stat(@struct, subcommand)
+    check_return_code(ret)
+
+    keys, ret = Lib.memcached_stat_get_keys(@struct, stat_struct)
+    check_return_code(ret)
+
+    keys.each do |key|
+       server_structs.size.times do |index|
+
+         value, ret = Lib.memcached_stat_get_value(
+           @struct,
+           Lib.memcached_select_stat_at(@struct, stat_struct, index),
+           key)
+         check_return_code(ret, key)
+
+         value = case value
+           when /^\d+\.\d+$/ then value.to_f
+           when /^\d+$/ then value.to_i
+           else value
+         end
+
+         stats[key.to_sym] += [value]
+       end
+    end
+
+    Lib.memcached_stat_free(@struct, stat_struct)
+    stats
+  rescue Memcached::SomeErrorsWereReported => _
+    e = _.class.new("Error getting stats")
+    e.set_backtrace(_.backtrace)
+    raise e
+  end
+
+  ### Operations helpers
+
+  private
+
+  # Checks the return code from Rlibmemcached against the exception list. Raises the corresponding exception if the return code is not Memcached::Success or Memcached::ActionQueued. Accepts an integer return code and an optional key, for exception messages.
+  def check_return_code(ret, key = nil) #:doc:
+    if ret == 0 # Lib::MEMCACHED_SUCCESS
+    elsif ret == 32 # Lib::MEMCACHED_BUFFERED
+    elsif ret == 16
+      raise @not_found # Lib::MEMCACHED_NOTFOUND
+    elsif ret == 14
+      raise @not_stored # Lib::MEMCACHED_NOTSTORED
+    else
+      reraise(key, ret)
+    end
+  rescue TypeError
+    reraise(key, ret)
+  end
+
+  def reraise(key, ret)
+    message = "Key #{inspect_keys(key, (detect_failure if ret == Lib::MEMCACHED_SERVER_MARKED_DEAD)).inspect}"
+    if key.is_a?(String)
+      if ret == Lib::MEMCACHED_ERRNO
+        if (server = Lib.memcached_server_by_key(@struct, key)).is_a?(Array)
+          errno = server.first.cached_errno
+          message = "Errno #{errno}: #{ERRNO_HASH[errno].inspect}. #{message}"
+        end
+      elsif ret == Lib::MEMCACHED_SERVER_ERROR
+        if (server = Lib.memcached_server_by_key(@struct, key)).is_a?(Array)
+          message = "\"#{server.first.cached_server_error}\". #{message}."
+        end
+      end
+    end
+    if EXCEPTIONS[ret]
+      raise EXCEPTIONS[ret], message
+    else
+      raise Memcached::Error, "Unknown return code: #{ret}"
+    end
+  end
+
+  # Turn an array of keys into a hash of keys to servers.
+  def inspect_keys(keys, server = nil)
+    Hash[*Array(keys).map do |key|
+      [key, server || server_by_key(key)]
+    end.flatten]
+  end
+
+  # Find which server failed most recently.
+  # FIXME Is this still necessary with cached_errno?
+  def detect_failure
+    time = Time.now
+    server = server_structs.detect do |server|
+      server.next_retry > time
+    end
+    inspect_server(server) if server
+  end
+
+  # Set the behaviors on the struct from the current options.
+  def set_behaviors
+    BEHAVIORS.keys.each do |behavior|
+      set_behavior(behavior, options[behavior]) if options.key?(behavior)
+    end
+    # BUG Hash must be last due to the weird Libmemcached multi-behaviors
+    set_behavior(:hash, options[:hash])
+  end
+
+  # Set the SASL credentials from the current options. If credentials aren't provided, try to get them from the environment.
+  def set_credentials
+    if options[:credentials]
+      check_return_code(
+        Lib.memcached_set_sasl_auth_data(@struct, *options[:credentials])
+      )
+    end
+  end
+
+  def is_unix_socket?(server)
+    server.type == Lib::MEMCACHED_CONNECTION_UNIX_SOCKET
+  end
+
+  # Stringify an opaque server struct
+  def inspect_server(server)
+    strings = [server.hostname]
+    if !is_unix_socket?(server)
+      strings << ":#{server.port}"
+      strings << ":#{server.weight}" if options[:ketama_weighted]
+    end
+    strings.join
+  end
+end