memcached 0.5

data/lib/memcached.rb

@@ -0,0 +1,6 @@
+
+require 'libmemcached'
+require 'memcached/integer'
+require 'memcached/exceptions'
+require 'memcached/behaviors'
+require 'memcached/memcached'

data/lib/memcached/behaviors.rb

@@ -0,0 +1,46 @@
+
+class Memcached
+
+  def self.load_constants(prefix, hash = {}, offset = 0)
+    Libmemcached.constants.grep(/^#{prefix}/).each do |const_name|
+      hash[const_name[prefix.length..-1].downcase.to_sym] = Libmemcached.const_get(const_name) + offset
+    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, 2))
+
+  DISTRIBUTION_VALUES = {}
+  BEHAVIOR_VALUES.merge!(load_constants("MEMCACHED_DISTRIBUTION_", DISTRIBUTION_VALUES, 2))
+
+  private
+  
+  def set_behavior(behavior, value)    
+    raise ArgumentError, "No setting #{behavior.inspect}" unless b_id = BEHAVIORS[behavior]    
+    raise ArgumentError, "No setting value #{value.inspect}" unless v_id = BEHAVIOR_VALUES[value]
+    
+    # Scoped validations
+    msg =  "Invalid setting value #{value.inspect} for #{behavior.inspect}" 
+    if behavior == :hash
+      raise ArgumentError, msg unless HASH_VALUES[value]
+    elsif behavior == :distribution
+      raise ArgumentError, msg unless DISTRIBUTION_VALUES[value]
+    end
+    # STDERR.puts "Setting #{behavior}:#{b_id} => #{value}:#{v_id}"
+    
+    unless value == false
+      # XXX Setting false still turns on the behavior; maybe a Libmemcached bug
+      Libmemcached.memcached_behavior_set(@struct, b_id, v_id)
+    end
+    
+  end  
+      
+end

data/lib/memcached/exceptions.rb

@@ -0,0 +1,30 @@
+
+class Memcached
+
+  class Error < RuntimeError
+  end
+  
+  class NotImplemented < StandardError
+  end
+
+  class << self
+    private
+    def camelize(string)
+      string.downcase.split(' ').map {|s| s.capitalize}.join
+    end   
+  end
+  
+  @@exceptions = []
+  @@empty_struct = Libmemcached::MemcachedSt.new
+  Libmemcached.memcached_create(@@empty_struct)
+  
+  # Generate exception classes
+  Libmemcached::MEMCACHED_MAXIMUM_RETURN.times do |exception_index|    
+    description = Libmemcached.memcached_strerror(@@empty_struct, exception_index)
+    exception_class = eval("class #{camelize(description)} < Error; self; end")
+    @@exceptions << exception_class
+  end
+  
+  # Verify library version
+  # XXX Impossible with current libmemcached  
+end

data/lib/memcached/integer.rb

@@ -0,0 +1,6 @@
+
+class Integer
+  def tv_sec
+    self
+  end
+end

data/lib/memcached/memcached.rb

@@ -0,0 +1,218 @@
+
+class Memcached
+
+  FLAGS = 0x0
+
+  DEFAULTS = {
+    :hash => :default,
+    :distribution => :consistent,
+    :buffer_requests => false,
+    :support_cas => false,
+    :tcp_nodelay => false,
+    :no_block => false
+  }
+  
+  IGNORED = 0
+  
+  attr_reader :namespace
+  attr_reader :options
+
+  ### Configuration
+  
+  def initialize(servers, opts = {})
+    @struct = Libmemcached::MemcachedSt.new
+    Libmemcached.memcached_create(@struct)
+
+    # Servers
+    Array(servers).each_with_index do |server, index|
+      unless server.is_a? String and server =~ /^(\d{1,3}\.){3}\d{1,3}:\d{1,5}$/
+        raise ArgumentError, "Servers must be in the format ip:port (e.g., '127.0.0.1:11211')" 
+      end
+      host, port = server.split(":")
+      Libmemcached.memcached_server_add(@struct, host, port.to_i)
+
+      # XXX To be removed once Krow fixes the write_ptr bug
+      Libmemcached.memcached_repair_server_st(@struct, 
+        Libmemcached.memcached_select_server_at(@struct, index)
+      )
+    end  
+    
+    # Namespace
+    @namespace = opts[:namespace]
+    raise ArgumentError, "Invalid namespace" if namespace.to_s =~ / /
+
+    # Behaviors
+    @options = DEFAULTS.merge(opts)
+    options.each do |option, value|
+      set_behavior(option, value) unless option == :namespace
+    end
+  end
+
+  def servers
+    server_structs.map do |server|
+      "#{server.hostname}:#{server.port}"
+    end
+  end
+  
+  def clone
+    # XXX Could be more efficient if we used Libmemcached.memcached_clone(@struct)
+    self.class.new(servers, options)
+  end
+  
+  alias :dup :clone
+
+  ### Configuration helpers
+
+  private
+    
+  def server_structs
+    array = []
+    @struct.hosts.count.times do |i|
+      array << Libmemcached.memcached_select_server_at(@struct, i)
+    end
+    array
+  end    
+    
+  ### Operations
+  
+  public
+  
+  # Setters
+  
+  def set(key, value, timeout=0, marshal=true)
+    value = marshal ? Marshal.dump(value) : value.to_s
+    check_return_code(
+      Libmemcached.memcached_set(@struct, ns(key), value, timeout, FLAGS)
+    )
+  end
+
+  def add(key, value, timeout=0, marshal=true)
+    value = marshal ? Marshal.dump(value) : value.to_s
+    check_return_code(
+      Libmemcached.memcached_add(@struct, ns(key), value, timeout, FLAGS)
+    )
+  end
+  
+  def increment(key, offset=1)
+    ret, value = Libmemcached.memcached_increment(@struct, ns(key), offset)
+    check_return_code(ret)
+    value
+  end
+  
+  def decrement(key, offset=1)
+    ret, value = Libmemcached.memcached_decrement(@struct, ns(key), offset)
+    check_return_code(ret)
+    value
+  end
+  
+  alias :incr :increment
+  alias :decr :decrement
+  
+  def replace(key, value, timeout=0, marshal=true)
+    value = marshal ? Marshal.dump(value) : value.to_s
+    check_return_code(
+      Libmemcached.memcached_replace(@struct, ns(key), value, timeout, FLAGS)
+    )
+  end
+  
+  def append(key, value)
+    # Requires memcached 1.2.4
+    check_return_code(
+      Libmemcached.memcached_append(@struct, ns(key), value.to_s, IGNORED, FLAGS)
+    )
+  end
+  
+  def prepend(key, value)
+    # Requires memcached 1.2.4
+    check_return_code(
+      Libmemcached.memcached_prepend(@struct, ns(key), value.to_s, IGNORED, FLAGS)
+    )
+  end
+  
+  def cas
+    # Requires memcached HEAD
+    raise NotImplemented
+    raise "CAS not enabled" unless options[:support_cas]
+  end
+
+  # Deleters
+
+  def delete(key, timeout=0)
+    check_return_code(
+      Libmemcached.memcached_delete(@struct, ns(key), timeout)
+    )  
+  end
+  
+  # Getters
+  
+  def get(key, marshal=true)
+    if key.is_a? Array
+      # Multi get
+      # XXX Waiting on the real implementation
+      key.map do |this_key|
+        begin
+          get(this_key, marshal)
+        rescue NotFound
+          # XXX Not sure how this behavior should be defined
+        end
+      end
+    else
+      # Single get
+      # XXX Server doesn't validate. Possibly a performance problem.
+      raise ClientError, "Invalid key" if !key.is_a? String or key =~ /\s/ 
+        
+      value, flags, ret = Libmemcached.memcached_get_ruby_string(@struct, ns(key))
+      check_return_code(ret)
+      value = Marshal.load(value) if marshal
+      value
+    end
+  end    
+  
+  # Information methods
+  
+  def stats
+    stats = Hash.new([])
+    
+    stat_struct, ret = Libmemcached.memcached_stat(@struct, "")
+    check_return_code(ret)
+    
+    keys, ret = Libmemcached.memcached_stat_get_keys(@struct, stat_struct)
+    check_return_code(ret)
+    
+    keys.each do |key|
+       server_structs.size.times do |index|
+
+         value, ret = Libmemcached.memcached_stat_get_value(
+           @struct, 
+           Libmemcached.memcached_select_stat_at(@struct, stat_struct, index),
+           key)
+         check_return_code(ret)
+
+         value = case value
+           when /^\d+\.\d+$/: value.to_f 
+           when /^\d+$/: value.to_i
+           else value
+         end           
+         
+         stats[key.to_sym] += [value]
+       end
+    end
+    
+    Libmemcached.memcached_stat_free(@struct, stat_struct)
+    stats
+  end  
+  
+  ### Operations helpers
+  
+  private
+
+  def ns(key)
+    "#{@namespace}#{key}"
+  end
+    
+  def check_return_code(ret)
+    return if ret == 0
+    raise @@exceptions[ret]
+  end  
+    
+end

data/memcached.gemspec

@@ -0,0 +1,38 @@
+
+# Gem::Specification for Memcached-0.5
+# Originally generated by Echoe
+
+Gem::Specification.new do |s|
+  s.name = %q{memcached}
+  s.version = "0.5"
+
+  s.specification_version = 2 if s.respond_to? :specification_version=
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Evan Weaver"]
+  s.date = %q{2008-01-20}
+  s.description = %q{An interface to the libmemcached C client.}
+  s.email = %q{}
+  s.extensions = ["ext/extconf.rb"]
+  s.files = ["CHANGELOG", "ext/extconf.rb", "ext/libmemcached.h", "ext/libmemcached.i", "ext/libmemcached_wrap.c", "lib/memcached/behaviors.rb", "lib/memcached/exceptions.rb", "lib/memcached/integer.rb", "lib/memcached/memcached.rb", "lib/memcached.rb", "LICENSE", "Manifest", "README", "test/benchmark/benchmark_test.rb", "test/setup.rb", "test/teardown.rb", "test/test_helper.rb", "test/unit/binding_test.rb", "test/unit/memcached_test.rb", "memcached.gemspec"]
+  s.has_rdoc = true
+  s.homepage = %q{http://blog.evanweaver.com/files/doc/fauna/memcached/}
+  s.require_paths = ["lib", "ext"]
+  s.rubyforge_project = %q{fauna}
+  s.rubygems_version = %q{1.0.1}
+  s.summary = %q{An interface to the libmemcached C client.}
+  s.test_files = ["test/benchmark/benchmark_test.rb", "test/test_helper.rb", "test/unit/binding_test.rb", "test/unit/memcached_test.rb"]
+end
+
+
+# # Original Rakefile source (requires the Echoe gem):
+# 
+# require 'echoe'
+# 
+# Echoe.new("memcached") do |p|
+#   p.author = "Evan Weaver"
+#   p.project = "fauna"
+#   p.summary = "An interface to the libmemcached C client."
+#   p.url = "http://blog.evanweaver.com/files/doc/fauna/memcached/"
+#   p.docs_host = "blog.evanweaver.com:~/www/bax/public/files/doc/"
+# end

data/test/benchmark/benchmark_test.rb

@@ -0,0 +1,42 @@
+
+require "#{File.dirname(__FILE__)}/../test_helper"
+
+require 'rubygems'
+require 'benchmark/unit'
+require 'memcache'
+
+class BenchmarkTest < Test::Unit::TestCase
+
+  def setup
+    @value = OpenStruct.new(:a => 1, :b => 2, :c => GenericClass)
+    @opts = [
+      ['127.0.0.1:43042', '127.0.0.1:43043'], 
+      {:namespace => "benchmark_namespace"}
+    ]
+  end
+
+  def test_original_speed
+    @cache = MemCache.new(*@opts)
+    assert_faster(0.02) do
+      @cache.set 'key1', @value
+      @cache.get 'key1'
+      @cache.set 'key2', @value
+      @cache.set 'key3', @value
+      @cache.get 'key2'
+      @cache.get 'key3'
+    end
+  end
+  
+  def test_new_speed
+    @cache = Memcached.new(*@opts)
+    assert_faster(0.005) do
+      @cache.set 'key1', @value
+      @cache.get 'key1'
+      @cache.set 'key2', @value
+      @cache.set 'key3', @value
+      @cache.get 'key2'
+      @cache.get 'key3'
+    end  
+  end
+  
+end

data/test/setup.rb

@@ -0,0 +1,14 @@
+
+# Start memcached
+
+HERE = File.dirname(__FILE__)
+
+`ps awx`.split("\n").grep(/4304[1-3]/).map do |process| 
+  system("kill -9 #{process.to_i}")
+end
+
+log = "#{HERE}/log/memcached.log"
+system "touch #{log}"
+
+system "memcached -vv -p 43042 >> #{log} 2>&1 &"
+system "memcached -vv -p 43043 >> #{log} 2>&1 &"  

data/test/test_helper.rb

@@ -0,0 +1,19 @@
+
+$LOAD_PATH << "#{File.dirname(__FILE__)}/../lib"
+
+if ENV['DEBUG']
+  require 'rubygems'
+  require 'ruby-debug' 
+end
+  
+require 'memcached'
+require 'test/unit'
+require 'ostruct'
+
+class GenericClass
+end
+
+class Memcached
+  class StubError < Error
+  end
+end

data/test/unit/binding_test.rb

@@ -0,0 +1,8 @@
+
+require "#{File.dirname(__FILE__)}/../test_helper"
+
+class BindingTest < Test::Unit::TestCase
+  def test_libmemcached_loaded
+    assert_nothing_raised { Libmemcached }
+  end
+end

data/test/unit/memcached_test.rb

@@ -0,0 +1,325 @@
+
+require "#{File.dirname(__FILE__)}/../test_helper"
+
+class MemcachedTest < Test::Unit::TestCase
+
+  def setup
+    @servers = ['127.0.0.1:43042', '127.0.0.1:43043']
+    @cache = Memcached.new(
+      @servers, 
+      :namespace => 'class_test_namespace'
+    )
+    @value = OpenStruct.new(:a => 1, :b => 2, :c => GenericClass)
+    @marshalled_value = Marshal.dump(@value)
+  end
+
+  def test_initialize
+    cache = Memcached.new @servers, :namespace => 'test'
+    assert_equal 'test', cache.namespace
+    assert_equal 2, cache.send(:server_structs).size
+    assert_equal '127.0.0.1', cache.send(:server_structs).first.hostname
+    assert_equal '127.0.0.1', cache.send(:server_structs).last.hostname
+    assert_equal 43043, cache.send(:server_structs).last.port
+  end
+  
+  def test_initialize_with_invalid_server_strings
+    assert_raise(ArgumentError) { Memcached.new "localhost:43042" }
+    assert_raise(ArgumentError) { Memcached.new "127.0.0.1:memcached" }
+    assert_raise(ArgumentError) { Memcached.new "127.0.0.1:43043:1" }
+  end
+
+  def test_initialize_without_namespace
+    cache = Memcached.new @servers
+    assert_equal nil, cache.namespace
+    assert_equal 2, cache.send(:server_structs).size
+  end
+  
+  def test_initialize_positive_behavior
+    cache = Memcached.new @servers,
+      :buffer_requests => true
+    assert_raise(Memcached::ActionQueued) do
+      cache.set key, @value
+    end
+  end
+
+  def test_initialize_negative_behavior
+    cache = Memcached.new @servers,
+      :buffer_requests => false
+    assert_nothing_raised do
+      cache.set key, @value
+    end
+  end
+
+  def test_initialize_single_server
+    cache = Memcached.new '127.0.0.1:43042'
+    assert_equal nil, cache.namespace
+    assert_equal 1, cache.send(:server_structs).size
+  end
+
+  def test_initialize_strange_argument
+    assert_raise(ArgumentError) { Memcached.new 1 }
+  end
+
+  def test_get
+    @cache.set key, @value
+    result = @cache.get key
+    assert_equal @value, result
+  end
+  
+  def test_get_with_namespace
+    @cache.set key, @value
+    result = @cache.get key, false
+    direct_result = Libmemcached.memcached_get(
+      @cache.instance_variable_get("@struct"), 
+      "#{@cache.namespace}#{key}"
+    ).first  
+    assert_equal result, direct_result
+  end
+
+  def test_get_nil
+    @cache.set key, nil, 0
+    result = @cache.get key
+    assert_equal nil, result
+  end
+  
+  def test_get_missing
+    @cache.delete key rescue nil
+    assert_raise(Memcached::NotFound) do
+      result = @cache.get key
+    end
+  end
+
+  def test_truncation_issue_is_covered
+    value = OpenStruct.new(:a => Object.new) # Marshals with a null \000
+    @cache.set key, value
+    result = @cache.get key, false
+    non_wrapped_result = Libmemcached.memcached_get(
+      @cache.instance_variable_get("@struct"), 
+      "#{@cache.namespace}#{key}"
+    ).first
+    assert result.size > non_wrapped_result.size      
+  end  
+
+  def test_get_invalid_key
+    assert_raise(Memcached::ClientError) { @cache.get(key * 100) }
+    assert_raise(Memcached::ClientError) { @cache.get "I'm so bad" }
+  end
+
+  def test_get_multi
+    @cache.set "#{key}_1", 1
+    @cache.set "#{key}_2", 2
+    assert_equal [1, 2], 
+      @cache.get(["#{key}_1", "#{key}_2"])
+  end
+
+  def test_set_and_get_unmarshalled
+    @cache.set key, @value
+    result = @cache.get key, false
+    assert_equal @marshalled_value, result
+  end
+
+  def test_set
+    assert_nothing_raised do
+      @cache.set(key, @value)
+    end
+  end
+  
+  def test_set_invalid_key
+    assert_raise(Memcached::ProtocolError) do
+      @cache.set "I'm so bad", @value
+    end
+  end
+  
+  def test_set_expiry
+    @cache.set key, @value, 1
+    assert_nothing_raised do
+      @cache.get key
+    end
+    sleep(1)
+    assert_raise(Memcached::NotFound) do
+      @cache.get key
+    end
+  end
+
+  def test_set_object_too_large
+    assert_raise(Memcached::ServerError) do
+      @cache.set key, "I'm big" * 1000000
+    end
+  end
+  
+  def test_delete
+    @cache.set key, @value
+    @cache.delete key
+    assert_raise(Memcached::NotFound) do
+      @cache.get key
+    end
+  end  
+
+  def test_missing_delete
+    @cache.delete key rescue nil
+    assert_raise(Memcached::NotFound) do
+      @cache.delete key
+    end
+  end  
+
+  def test_add
+    @cache.delete key rescue nil
+    @cache.add key, @value
+    assert_equal @value, @cache.get(key)
+  end
+
+  def test_existing_add
+    @cache.set key, @value
+    assert_raise(Memcached::NotStored) do
+      @cache.add key, @value
+    end
+  end
+
+  def test_add_expiry
+    @cache.delete key rescue nil
+    @cache.set key, @value, 1
+    assert_nothing_raised do
+      @cache.get key
+    end
+    sleep(1)
+    assert_raise(Memcached::NotFound) do
+      @cache.get key
+    end  
+  end
+
+  def test_unmarshalled_add
+    @cache.delete key rescue nil
+    @cache.add key, @marshalled_value, 0, false
+    assert_equal @marshalled_value, @cache.get(key, false)
+    assert_equal @value, @cache.get(key)
+  end
+
+  def test_increment
+    @cache.set key, 10, 0, false
+    assert_equal 11, @cache.increment(key)
+  end
+  
+  def test_increment_offset
+    @cache.set key, 10, 0, false
+    assert_equal 15, @cache.increment(key, 5)
+  end
+
+  def test_missing_increment
+    # XXX Fails due to libmemcached bug
+    @cache.delete key rescue nil
+    assert_raise(Memcached::NotFound) do
+      @cache.increment key
+    end
+  end
+
+  def test_decrement
+    @cache.set key, 10, 0, false
+    assert_equal 9, @cache.decrement(key)
+  end
+  
+  def test_decrement_offset
+    @cache.set key, 10, 0, false
+    assert_equal 5, @cache.decrement(key, 5)
+  end  
+
+  def test_missing_decrement
+    # XXX Fails due to libmemcached bug
+    @cache.delete key rescue nil
+    assert_raise(Memcached::NotFound) do
+      @cache.decrement key
+    end
+  end
+  
+  def test_replace
+    @cache.set key, nil
+    assert_nothing_raised do
+      @cache.replace key, @value
+    end
+    assert_equal @value, @cache.get(key)
+  end
+
+  def test_missing_replace
+    @cache.delete key rescue nil
+    assert_raise(Memcached::NotStored) do
+      @cache.replace key, @value
+    end
+    assert_raise(Memcached::NotFound) do    
+      assert_equal @value, @cache.get(key)    
+    end
+  end
+
+  def test_append
+    @cache.set key, "start", 0, false
+    assert_nothing_raised do
+      @cache.append key, "end"
+    end
+    assert_equal "startend", @cache.get(key, false)
+  end
+
+  def test_missing_append
+    @cache.delete key rescue nil
+    assert_raise(Memcached::NotStored) do
+      @cache.append key, "end"
+    end
+    assert_raise(Memcached::NotFound) do    
+      assert_equal @value, @cache.get(key)    
+    end
+  end
+
+  def test_prepend
+    @cache.set key, "end", 0, false
+    assert_nothing_raised do
+      @cache.prepend key, "start"
+    end
+    assert_equal "startend", @cache.get(key, false)
+  end
+
+  def test_missing_prepend
+    @cache.delete key rescue nil
+    assert_raise(Memcached::NotStored) do
+      @cache.prepend key, "end"
+    end
+    assert_raise(Memcached::NotFound) do    
+      assert_equal @value, @cache.get(key)    
+    end
+  end
+
+  def test_cas
+    # XXX Not implemented
+  end
+
+  def test_stats
+    stats = @cache.stats
+    assert_equal 2, stats[:pid].size
+    assert_instance_of Fixnum, stats[:pid].first
+    assert_instance_of String, stats[:version].first
+  end
+  
+  def test_clone
+    cache = @cache.clone
+    assert_equal cache.servers, @cache.servers
+    assert_not_equal cache, @cache
+  end
+
+  def test_thread_contention
+    threads = []
+    4.times do |index|
+      threads << Thread.new do 
+        cache = @cache.clone
+        assert_nothing_raised do
+          cache.set("test_thread_contention_#{index}", index)
+        end
+        assert_equal index, cache.get("test_thread_contention_#{index}")
+      end
+    end
+    threads.each {|thread| thread.join}
+  end
+  
+  private
+  
+  def key
+    caller.first[/`(.*)'/, 1]
+  end
+
+end
+