binary42-remix-stash 0.9.0

data/.gitignore

@@ -0,0 +1 @@
+pkg

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2009 Paperless Post Inc.
+Copyright (c) 2009 Brian Mitchell
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.mdown

@@ -0,0 +1,18 @@
+Coming Soon!
+
+# Quick Specs
+
+It's fast (over 2x faster than memcache-client). It's simple (pure ruby and only a few hundred lines). It's tested (shoulda).
+
+It does require memcached 1.4+ but you should be running that anyway (if you aren't, upgrade already).
+
+# TODO
+
+* clear on root should do it for each host in a cluster
+* optimize option merging with cache
+* make clusters selectable per stash
+* implement the rest of the memcached 1.4 binary API
+* allow swappable cluster types for consistent hashing, ketama, etc...
+* failsafe marshal load
+* support non-marshal value dumps configured per stash
+* support intersected stashes with joined vector sets

data/Rakefile

@@ -0,0 +1,12 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = 'remix-stash'
+    gemspec.summary = 'Remix your memcache'
+    gemspec.email = 'binary42@gmail.com'
+    gemspec.homepage = 'http://github.com/binary42/remix-stash'
+    gemspec.authors = ['Brian Mitchell']
+  end
+rescue LoadError
+  puts 'Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com'
+end

data/VERSION

@@ -0,0 +1 @@
+0.9.0

data/examples/bench.rb

@@ -0,0 +1,20 @@
+require 'benchmark'
+require File.dirname(__FILE__) + '/../harness'
+require File.dirname(__FILE__) + '/../harness_cache'
+
+LARGE_NUMBER = 20_000
+
+Benchmark.bm do |b|
+  b.report('get/set stash') do
+    LARGE_NUMBER.times {|n|
+      stash[:abcxyz123] = n
+      stash[:abcxyz123]
+    }
+  end
+  b.report('get/set cache') do
+    LARGE_NUMBER.times {|n|
+      Cache.set('abcxyz123', n)
+      Cache.get('abcxyz123')
+    }
+  end
+end

data/examples/eval.rb

@@ -0,0 +1,8 @@
+require File.dirname(__FILE__) + '/../harness'
+
+stuff = stash(:stuff)
+
+stuff.eval(:answer) {42}
+p stuff.get(:answer)
+
+stuff.eval(:asnwer) {fail 'Cache miss'}

data/examples/gate.rb

@@ -0,0 +1,6 @@
+require File.dirname(__FILE__) + '/../harness'
+
+p stash.gate(:x) {p :miss}
+p :set_x
+stash[:x] = true
+p stash.gate(:x) {p :miss}

data/examples/getset.rb

@@ -0,0 +1,13 @@
+require File.dirname(__FILE__) + '/../harness'
+
+# Get and set a simple key
+stash.set('answer', 42)
+p stash.get('answer')
+
+# Alternate methods
+stash[:answer] = :fortytwo
+p stash[:answer]
+
+# Composite keys
+stash[1,2,3,4] = 5
+p stash[1,2,3,4]

data/examples/getset_cache.rb

@@ -0,0 +1,5 @@
+require File.dirname(__FILE__) + '/../harness_cache'
+
+# Simple get and set
+Cache.set('answer', 42)
+p Cache.get('answer')

data/examples/scope.rb

@@ -0,0 +1,17 @@
+require File.dirname(__FILE__) + '/../harness'
+
+a = 0
+
+stash(:x).scope {a}
+
+stash(:x)[1] = 2
+
+p stash(:x)[1]
+
+a += 1
+
+p stash(:x)[1]
+
+a = 0
+
+p stash(:x)[1]

data/examples/stash.rb

@@ -0,0 +1,16 @@
+require File.dirname(__FILE__) + '/../harness'
+
+one = stash(:one)
+two = stash(:two)
+
+one[:x] = 10
+two[:x] = 12
+
+p one[:x]
+p two[:x]
+
+p :clearing
+one.clear
+
+p one[:x]
+p two[:x]

data/harness.rb

@@ -0,0 +1,4 @@
+$LOAD_PATH << File.dirname(__FILE__) + '/lib'
+require 'remix/stash'
+
+stash.clear

data/harness_cache.rb

@@ -0,0 +1,5 @@
+require 'rubygems'
+require 'memcache'
+
+Cache = MemCache.new(%[localhost:11211])
+Cache.flush_all

data/lib/remix/stash.rb

@@ -0,0 +1,210 @@
+class Stash
+  require 'remix/stash/extension'
+  require 'remix/stash/cluster'
+  require 'remix/stash/protocol'
+
+  attr_accessor :name
+
+  @@instances = {}
+  @@clusters = {:default => Cluster.new(%w[localhost:11211])}
+
+  def self.cluster(name)
+    @@clusters[name]
+  end
+
+  def self.cycle_action
+    @@instances.each {|name, stash|
+      stash.cycle if stash.default[:coherency] == :action}
+  end
+
+  def self.define_cluster(clusters)
+    clusters.each do |k,v|
+      @@clusters[k] = Cluster.new(v)
+    end
+  end
+
+  def self.new(name)
+    @@instances[name] ||= super
+  end
+
+  def initialize(name)
+    @name = name
+    @scope = nil
+    @opts = name == :root ? {:coherency => :action, :ttl => 0} : {}
+  end
+
+  def clear(*keys)
+    if keys.empty?
+      if @name == :root
+        cluster.each {|io| Protocol.flush(io)}
+      else
+        vk = vector_key
+        cluster.select(vk) {|io|
+          unless Protocol.incr(io, vk, 1)
+            Protocol.add(io, vk, '0')
+            Protocol.incr(io, vk, 1)
+          end
+        }
+      end
+      cycle
+    else
+      # remove a specific key
+      key = canonical_key(keys)
+      cluster.select(key) {|io| Protocol.delete(io, key)}
+    end
+  end
+
+  def clear_scope
+    @scope = nil
+  end
+
+  def cycle
+    @vector = nil
+  end
+
+  def decr(*keys)
+    step = keys.pop
+    key = canonical_key(keys)
+    cluster.select(key) {|io| Protocol.decr(io, key, step)}
+  end
+
+  def default(opts = {})
+    base = @opts.merge!(opts)
+    if opts.has_key? :coherency
+      [:dynamic, :action, :transaction].include?(opts[:coherency]) or raise ArgumentError,
+        "Invalid coherency setting used (#{opts[:coherency].inspect})"
+    end
+    root = @@instances[:roto] || Stash.new(:root)
+    self == root ?
+      base :
+      root.default.merge(base)
+  end
+
+  def delete(*keys)
+    key = canonical_key(keys)
+    cluster.select(key) {|io| Protocol.delete(io, key)}
+  end
+
+  def eval(*keys)
+    opts = default_opts(keys)
+    key = canonical_key(keys)
+    cluster.select(key) {|io|
+      value = Protocol.get_value(io, key)
+      unless value
+        value = yield(*keys)
+        Protocol.set_value(io, key, value, opts[:ttl])
+      end
+      value
+    }
+  end
+
+  def gate(*keys)
+    key = canonical_key(keys)
+    cluster.select(key) {|io|
+      if Protocol.get(io, key)
+        true
+      else
+        yield(*keys)
+        false
+      end
+    }
+  end
+
+  def get(*keys)
+    key = canonical_key(keys)
+    cluster.select(key) {|io| Protocol.get_value(io, key)}
+  end
+  alias [] get
+
+  def incr(*keys)
+    step = keys.pop
+    key = canonical_key(keys)
+    cluster.select(key) {|io| Protocol.incr(io, key, step)}
+  end
+
+  def read(*keys)
+    key = canonical_key(keys)
+    cluster.select(key) {|io| Protocol.get(io, key)}
+  end
+
+  def release
+    @@instances.delete(@name)
+  end
+
+  def scope(&b)
+    @scope = b
+    self
+  end
+
+  def set(*keys)
+    opts = default_opts(keys)
+    value = keys.pop
+    key = canonical_key(keys)
+    cluster.select(key) {|io| Protocol.set_value(io, key, value, opts[:ttl])}
+  end
+  alias []= set
+
+  def transaction
+    yield self
+  ensure
+    cycle
+  end
+
+  def write(*keys)
+    opts = default_opts(keys)
+    value = keys.pop
+    key = canonical_key(keys)
+    cluster.select(key) {|io| Protocol.set(io, key, value, opts[:ttl])}
+  end
+
+private
+
+  def canonical_key(keys)
+    "#{implicit_scope}#{keys.join('/')}@#@name:#{vector}"
+  end
+
+  def cluster
+    @@clusters[:default]
+  end
+
+  def coherency
+    default[:coherency]
+  end
+
+  def default_opts(params)
+    params.last.is_a?(Hash) ? default.merge(params.pop) : default
+  end
+
+  def implicit_scope
+    if @scope
+      scope = @scope.call(self)
+      scope ? "#{scope}/" : ''
+    else
+      ''
+    end
+  end
+
+  def vector
+    return 'static' if @name == :root
+    return @vector.to_s if @vector && coherency != :dynamic
+    vk = vector_key
+    cluster.select(vk) do |io|
+      @vector = Protocol.get(io, vk)
+      unless @vector
+        Protocol.add(io, vk, '0')
+        @vector = Protocol.get(io, vk)
+      end
+      @vector
+    end
+  end
+
+  def vector_key
+    "#@name#{implicit_scope}_vector"
+  end
+
+  class ProtocolError < RuntimeError; end
+  class ClusterError < RuntimeError; end
+
+end
+
+class Object; include Stash::Extension end

data/lib/remix/stash/cluster.rb

@@ -0,0 +1,62 @@
+require 'socket'
+require 'digest/md5'
+
+class Stash::Cluster
+  include Socket::Constants
+
+  @@connections = {}
+
+  attr_reader :hosts
+
+  def initialize(hosts)
+    @hosts = hosts.map {|x|
+      host, port = x.split(':')
+      [x, host, (port || 11211).to_i]
+    }.sort_by {|(_,h,p)| [h,p]}
+  end
+
+  def each
+    @hosts.each do |h|
+      yield(host_to_io(*h))
+    end
+  end
+
+  # Note: Later, I'd like to support richer cluster definitions.
+  # This should do the trick for now... and it's fast.
+  def select(key)
+    count = @hosts.size
+    hash = nil
+    if count > 1
+      digest = Digest::MD5.digest(key)
+      hash = digest.unpack("L")[0]
+    else
+      hash = 0
+    end
+    count.times do |try|
+      begin
+        break yield(host_to_io(*@hosts[(hash + try) % count]))
+      rescue Stash::ProtocolError
+        next
+      end
+      raise Stash::ClusterError,
+        "Unable to find suitable host to communicate with for #{key.inspect} (MD5-32=#{hash})"
+    end
+  end
+
+private
+
+  def connect(host, port)
+    address = Socket.getaddrinfo(host, nil).first
+    socket = Socket.new(Socket.const_get(address[0]), SOCK_STREAM, 0)
+    timeout = [2,0].pack('l_2') # 2 seconds
+    socket.setsockopt(SOL_SOCKET, SO_SNDTIMEO, timeout)
+    socket.setsockopt(SOL_SOCKET, SO_RCVTIMEO, timeout)
+    socket.connect(Socket.pack_sockaddr_in(port, address[3]))
+    socket
+  end
+
+  def host_to_io(key, host, port)
+    @@connections[key] ||= connect(host, port)
+  end
+
+end

data/lib/remix/stash/extension.rb

@@ -0,0 +1,8 @@
+module Stash::Extension
+  extend self
+
+  def stash(name = :root)
+    Stash.new(name)
+  end
+
+end

data/lib/remix/stash/protocol.rb

@@ -0,0 +1,253 @@
+module Stash::Protocol
+  extend self
+
+  HEADER_FORMAT = "CCnCCnNa4a8"
+
+  # Magic codes
+  REQUEST   = 0x80
+  RESPONSE = 0x81
+
+  # Command codes
+  GET         = 0x00
+  SET         = 0x01
+  ADD         = 0x02
+  REPLACE     = 0x03
+  DELETE      = 0x04
+  INCREMENT   = 0x05
+  DECREMENT   = 0x06
+  QUIT        = 0x07
+  FLUSH       = 0x08
+  GET_Q       = 0x09
+  NO_OP       = 0x0A
+  VERSION     = 0x0B
+  GET_K       = 0x0C
+  GET_K_Q     = 0x0D
+  APPEND      = 0x0E
+  PREPEND     = 0x0F
+  STAT        = 0x10
+  SET_Q       = 0x11
+  ADD_Q       = 0x12
+  REPLACE_Q   = 0x13
+  DELETE_Q    = 0x14
+  INCREMENT_Q = 0x15
+  DECREMENT_Q = 0x16
+  QUIT_Q      = 0x17
+  FLUSH_Q     = 0x18
+  APPEND_Q    = 0x19
+  PREPEND_Q   = 0x20
+
+  # Response codes
+  NO_ERROR                  = 0x0000
+  KEY_NOT_FOUND             = 0x0001
+  KEY_EXISTS                = 0x0002
+  VALUE_TOO_LARGE           = 0x0003
+  INVALID_ARGUMENTS         = 0x0004
+  ITEM_NOT_STORED           = 0x0005
+  INCR_ON_NON_NUMERIC_VALUE = 0x0006
+  UNKNOWN_COMMAND           = 0x0081
+  OUT_OF_MEMORY             = 0x0082
+
+  # Extras
+  COUNTER_FAULT_EXPIRATION = 0xFFFFFFFF
+
+  def add(io, key, data)
+    # Field        (offset) (value)
+    # Magic        (0)    : 0x80
+    # Opcode       (1)    : 0x02
+    # Key length   (2,3)  : 0x0005
+    # Extra length (4)    : 0x08
+    # Data type    (5)    : 0x00
+    # Reserved     (6,7)  : 0x0000
+    # Total body   (8-11) : 0x00000012
+    # Opaque       (12-15): 0x00000000
+    # CAS          (16-23): 0x0000000000000000
+    # Extras              :
+    #   Flags      (24-27): 0xdeadbeef
+    #   Expiry     (28-31): 0x00000e10
+    # Key          (32-36): The textual string "Hello"
+    # Value        (37-41): The textual string "World"
+    header = [REQUEST, ADD, key.size, 8, 0, 0, data.size + key.size + 8, '', '', 0, 0, key, data].pack(HEADER_FORMAT + 'NNa*a*')
+    io.write(header)
+    resp = read_resp(io)
+    resp[:status] == NO_ERROR
+  end
+
+  def decr(io, key, step)
+    # Field        (offset) (value)
+    # Magic        (0)    : 0x80
+    # Opcode       (1)    : 0x06
+    # Key length   (2,3)  : 0x0007
+    # Extra length (4)    : 0x14
+    # Data type    (5)    : 0x00
+    # Reserved     (6,7)  : 0x0000
+    # Total body   (8-11) : 0x0000001b
+    # Opaque       (12-15): 0x00000000
+    # CAS          (16-23): 0x0000000000000000
+    # Extras              :
+    #   delta      (24-31): 0x0000000000000001
+    #   initial    (32-39): 0x0000000000000000
+    #   exipration (40-43): 0x00000e10
+    # Key                 : Textual string "counter"
+    # Value               : None
+    low, high = split64(step)
+    header = [REQUEST, DECREMENT, key.size, 20, 0, 0, key.size + 20, '', '', high, low, 0, COUNTER_FAULT_EXPIRATION, key].pack(HEADER_FORMAT + 'NNQNa*')
+    io.write(header)
+    resp = read_resp(io)
+    if resp[:status] == NO_ERROR
+      parse_counter(resp[:body])
+    end
+  end
+
+  def delete(io, key, ttl = 0)
+    # Field        (offset) (value)
+    # Magic        (0)    : 0x80
+    # Opcode       (1)    : 0x04
+    # Key length   (2,3)  : 0x0005
+    # Extra length (4)    : 0x00
+    # Data type    (5)    : 0x00
+    # Reserved     (6,7)  : 0x0000
+    # Total body   (8-11) : 0x00000005
+    # Opaque       (12-15): 0x00000000
+    # CAS          (16-23): 0x0000000000000000
+    # Extras              : None
+    # Key                 : The textual string "Hello"
+    # Value               : None
+    header = [REQUEST, DELETE, key.size, 0, 0, 0, key.size, '', '', key].pack(HEADER_FORMAT + 'a*')
+    io.write(header)
+    resp = read_resp(io)
+    resp[:status] == NO_ERROR
+  end
+
+  def flush(io)
+    # Field        (offset) (value)
+    # Magic        (0)    : 0x80
+    # Opcode       (1)    : 0x08
+    # Key length   (2,3)  : 0x0000
+    # Extra length (4)    : 0x04
+    # Data type    (5)    : 0x00
+    # Reserved     (6,7)  : 0x0000
+    # Total body   (8-11) : 0x00000004
+    # Opaque       (12-15): 0x00000000
+    # CAS          (16-23): 0x0000000000000000
+    # Extras              :
+    #    Expiry    (24-27): 0x000e10
+    header = [REQUEST, FLUSH, 0, 4, 0, 0, 4, '', '', 0].pack(HEADER_FORMAT + 'N')
+    io.write(header)
+    resp = read_resp(io)
+    resp[:status] == NO_ERROR
+  end
+
+  def get(io, key)
+    # Field        (offset) (value)
+    # Magic        (0)    : 0x80
+    # Opcode       (1)    : 0x00
+    # Key length   (2,3)  : 0x0005
+    # Extra length (4)    : 0x00
+    # Data type    (5)    : 0x00
+    # Reserved     (6,7)  : 0x0000
+    # Total body   (8-11) : 0x00000005
+    # Opaque       (12-15): 0x00000000
+    # CAS          (16-23): 0x0000000000000000
+    # Extras              : None
+    # Key          (24-29): The textual string: "Hello"
+    # Value               : None
+    header = [REQUEST, GET, key.size, 0, 0, 0, key.size, '', '', key].pack(HEADER_FORMAT + 'a*')
+    io.write(header)
+    resp = read_resp(io)
+    resp[:status] == NO_ERROR ? parse_get(resp[:body])[:value] : nil
+  end
+
+  def get_value(io, key)
+    load_ruby_value(get(io, key))
+  end
+
+  def incr(io, key, step)
+    # Field        (offset) (value)
+    # Magic        (0)    : 0x80
+    # Opcode       (1)    : 0x05
+    # Key length   (2,3)  : 0x0007
+    # Extra length (4)    : 0x14
+    # Data type    (5)    : 0x00
+    # Reserved     (6,7)  : 0x0000
+    # Total body   (8-11) : 0x0000001b
+    # Opaque       (12-15): 0x00000000
+    # CAS          (16-23): 0x0000000000000000
+    # Extras              :
+    #   delta      (24-31): 0x0000000000000001
+    #   initial    (32-39): 0x0000000000000000
+    #   exipration (40-43): 0x00000e10
+    # Key                 : Textual string "counter"
+    # Value               : None
+    low, high = split64(step)
+    header = [REQUEST, INCREMENT, key.size, 20, 0, 0, key.size + 20, '', '', high, low, 0, COUNTER_FAULT_EXPIRATION, key].pack(HEADER_FORMAT + 'NNQNa*')
+    io.write(header)
+    resp = read_resp(io)
+    if resp[:status] == NO_ERROR
+      parse_counter(resp[:body])
+    end
+  end
+
+  def set(io, key, data, ttl = 0)
+    # Field        (offset) (value)
+    # Magic        (0)    : 0x80
+    # Opcode       (1)    : 0x01
+    # Key length   (2,3)  : 0x0005
+    # Extra length (4)    : 0x08
+    # Data type    (5)    : 0x00
+    # Reserved     (6,7)  : 0x0000
+    # Total body   (8-11) : 0x00000012
+    # Opaque       (12-15): 0x00000000
+    # CAS          (16-23): 0x0000000000000000
+    # Extras              :
+    #   Flags      (24-27): 0xdeadbeef
+    #   Expiry     (28-31): 0x00000e10
+    # Key          (32-36): The textual string "Hello"
+    # Value        (37-41): The textual string "World"
+    header = [REQUEST, SET, key.size, 8, 0, 0, data.size + key.size + 8, '', '', 0, 0, key, data].pack(HEADER_FORMAT + 'NNa*a*')
+    io.write(header)
+    resp = read_resp(io)
+    resp[:status] == NO_ERROR
+  end
+
+  def set_value(io, key, value, ttl = 0)
+    set(io, key, Marshal.dump(value), ttl)
+  end
+
+  def method_missing(message, *a)
+    fail [:NOT_IMPLEMENTED, self, message, *a].inspect
+  end
+
+private
+
+  def load_ruby_value(data)
+    return unless data
+    # TODO: Catch errors and try to fix them
+    Marshal.load(data)
+  end
+
+  def parse_get(body)
+    extra, value = body.unpack('Na*')
+    {:extra => extra, :value => value}
+  end
+
+  def parse_counter(body)
+    a, b = body.unpack('NN')
+    b | (a << 32)
+  end
+
+  def read_resp(io)
+    magic, opcode, key_length,
+    extra, type, status,
+    body_length, opaque, cas = *io.read(24).unpack(HEADER_FORMAT)
+    resp = { :magic => magic, :opcode => opcode, :key_length => key_length,
+      :extra => extra, :type => type, :status => status,
+      :body_length => body_length, :opaque => opaque, :cas => cas }
+    resp[:body] = io.read(resp[:body_length]) if resp[:body_length] > 0
+    resp
+  end
+
+  def split64(n)
+    [0xFFFFFFFF & n, n >> 32]
+  end
+
+end

data/remix-stash.gemspec

@@ -0,0 +1,70 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{remix-stash}
+  s.version = "0.9.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Brian Mitchell"]
+  s.date = %q{2009-08-29}
+  s.email = %q{binary42@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.mdown"
+  ]
+  s.files = [
+    ".gitignore",
+     "LICENSE",
+     "README.mdown",
+     "Rakefile",
+     "VERSION",
+     "examples/bench.rb",
+     "examples/eval.rb",
+     "examples/gate.rb",
+     "examples/getset.rb",
+     "examples/getset_cache.rb",
+     "examples/scope.rb",
+     "examples/stash.rb",
+     "harness.rb",
+     "harness_cache.rb",
+     "lib/remix/stash.rb",
+     "lib/remix/stash/cluster.rb",
+     "lib/remix/stash/extension.rb",
+     "lib/remix/stash/protocol.rb",
+     "remix-stash.gemspec",
+     "spec/extension_spec.rb",
+     "spec/spec.rb",
+     "spec/stash_spec.rb"
+  ]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/binary42/remix-stash}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{Remix your memcache}
+  s.test_files = [
+    "spec/extension_spec.rb",
+     "spec/spec.rb",
+     "spec/stash_spec.rb",
+     "examples/bench.rb",
+     "examples/eval.rb",
+     "examples/gate.rb",
+     "examples/getset.rb",
+     "examples/getset_cache.rb",
+     "examples/scope.rb",
+     "examples/stash.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/spec/extension_spec.rb

@@ -0,0 +1,25 @@
+require File.dirname(__FILE__) + '/spec'
+
+class ExtensionSpec < Spec
+
+  context '#stash' do
+
+    should 'return a stash object with the correct name' do
+      s = stash(:a)
+      assert_instance_of Stash, s
+      assert_equal :a, s.name
+    end
+
+    should 'return the same object when given the same name' do
+      assert_equal stash(:b), stash(:b)
+      assert_not_equal stash(:a), stash(:b)
+    end
+
+    should 'allow access to a default root stash' do
+      assert_equal stash, stash(:root)
+      assert_equal :root, stash.name
+    end
+
+  end
+
+end

data/spec/spec.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH << File.dirname(__FILE__) + '/../lib'
+require 'remix/stash'
+
+Spec = Test::Unit::TestCase

data/spec/stash_spec.rb

@@ -0,0 +1,389 @@
+require File.dirname(__FILE__) + '/spec'
+
+class StashSpec < Spec
+
+  def setup
+    stash.clear
+    Stash.class_eval("@@instances.clear")
+  end
+
+  context 'coherency' do
+
+    should 'only allow valid coherency settings' do
+      stash.default(:coherency => :action)
+      stash.default(:coherency => :dynamic)
+      stash.default(:coherency => :transaction)
+      assert_raises ArgumentError do
+        stash.default(:coherency => :other)
+      end
+    end
+
+    should 'support :action coherency' do
+      one = stash(:one).release
+      two = stash(:one)
+      two.default(:coherency => :action)
+      one[:value] = 42
+      assert_equal 42, two[:value]
+      one.clear
+      one[:value] = 43
+      assert_equal 42, two[:value]
+      Stash.cycle_action
+      assert_equal 43, two[:value]
+    end
+
+    should 'support :dynamic coherency' do
+      one = stash(:one).release
+      two = stash(:one)
+      two.default(:coherency => :dynamic)
+      one[:value] = 42
+      assert_equal 42, two[:value]
+      one.clear
+      one[:value] = 43
+      assert_equal 43, two[:value]
+    end
+
+    should 'support :explicit coherency' do
+      one = stash(:one).release
+      two = stash(:one)
+      two.default(:coherency => :transaction)
+      one[:value] = 42
+      assert_equal 42, two[:value]
+      one.clear
+      one[:value] = 43
+      assert_equal 42, two[:value]
+      Stash.cycle_action
+      assert_equal 42, two[:value]
+      two.cycle
+      assert_equal 43, two[:value]
+    end
+
+  end
+
+  context 'defaults' do
+
+    should 'default to :action coherency' do
+      assert_equal :action, stash.default[:coherency]
+    end
+
+    should 'use a default cluster on localhost:11211' do
+      local = Stash.cluster(:default)
+      assert_equal [['localhost:11211', 'localhost', 11211]], local.hosts
+    end
+
+  end
+
+  context '.cycle_action' do
+
+    setup do
+      @cycle = stash(:action).release
+      @stash = stash(:action)
+      @stash.default(:coherency => :action)
+    end
+
+    should 'cycle all action conherent scopes' do
+      @stash.set('a', 42)
+      @cycle.clear
+      assert_equal 42, @stash.get('a')
+      Stash.cycle_action
+      assert_nil @stash.get('a')
+    end
+
+  end
+
+  context '.define_cluster' do
+
+    should 'setup a cluster using an array of host/port pairs' do
+      Stash.define_cluster(:simple => %w[one:1 two:2], :sample => %w[miro.local:11211])
+      assert Stash.cluster(:simple)
+      assert Stash.cluster(:sample)
+    end
+
+    should 'default to port 11211' do
+      Stash.define_cluster(:default_port => 'default')
+      assert_equal [['default', 'default', 11211]], Stash.cluster(:default_port).hosts
+    end
+
+  end
+
+  context '#clear' do
+
+    setup do
+      stash(:a).default(:coherency => :dynamic)
+    end
+
+    should 'flush all when called without keys on root' do
+      stash(:a).set(:b, :c)
+      stash.set(:d, :e)
+      stash.clear
+      assert_nil stash(:a).get(:b)
+      assert_nil stash.get(:d)
+    end
+
+    should 'clear just a scope when called without keys on a non-root node' do
+      stash(:a).set(:b, :c)
+      stash.set(:d, :e)
+      stash(:a).clear
+      assert_nil stash(:a).get(:b)
+      assert_equal :e, stash.get(:d)
+    end
+
+    should 'clear just a key when called with keys on any node' do
+      stash(:a).set(:b, :c)
+      stash.set(:d, :e)
+      stash.clear(:d)
+      assert_equal :c, stash(:a).get(:b)
+      assert_nil stash.get(:d)
+      stash(:a).clear
+      assert_nil stash(:a).get(:b)
+    end
+
+  end
+
+  context '#clear_scope' do
+
+    should 'remove the prior scope' do
+      stash[:foo] = :bar
+      stash.scope {42}
+      stash[:foo] = :qux
+      stash.clear_scope
+      assert_equal :bar, stash[:foo]
+    end
+
+  end
+
+  context '#cycle' do
+
+    should 'clear the cached vector' do
+      one = stash(:one).release
+      two = stash(:one)
+      one[:a] = :b
+      assert_equal :b, two[:a]
+      one.clear
+      one[:a] = :c
+      two.cycle
+      assert_equal :c, two[:a]
+    end
+
+  end
+
+  context '#decr' do
+
+    should 'decrement numeric values by a positive integer' do
+      stash.write(:a, '10')
+      stash.decr(:a, 1)
+      assert_equal 9, stash.read(:a).to_i
+      stash.decr(:a, 3)
+      assert_equal 6, stash.read(:a).to_i
+    end
+
+    should 'return the new numeric value' do
+      stash.write(:a, '45')
+      assert_equal 42, stash.decr(:a, 3)
+    end
+
+  end
+
+  context '#default' do
+
+    should 'return a Hash of default options' do
+      assert_kind_of Hash, stash(:one).default
+    end
+
+    should 'allow setting default options' do
+      s = stash(:two)
+      long_time = 5000
+      s.default(:ttl => long_time)
+      assert_equal long_time, s.default[:ttl]
+    end
+
+    should 'merge with top-level default options' do
+      s = stash(:three)
+      stash.default(:ttl => 3600)
+      assert_equal 3600, s.default[:ttl]
+      s.default(:ttl => 4800)
+      assert_equal 4800, s.default[:ttl]
+      assert_equal 3600, stash.default[:ttl]
+    end
+
+  end
+
+  context '#delete' do
+
+    should 'remove a key from the cache' do
+      stash[:foo] = 42
+      stash.delete(:foo)
+      assert_nil stash[:foo]
+    end
+
+    should 'return true when deleted' do
+      stash[:foo] = 42
+      assert stash.delete(:foo)
+    end
+
+    should 'return false when not found' do
+      assert !stash.delete(:foo)
+    end
+
+  end
+
+  context '#eval' do
+
+    should 'evaluate the block on a cache miss' do
+      ran = false
+      stash.eval(:a) {ran = true}
+      assert ran
+    end
+
+    should 'not evaluate on a cache hit' do
+      ran = false
+      stash[:a] = 42
+      stash.eval(:a) {ran = false}
+      assert !ran
+    end
+
+    should 'pass keys in as optional block arguments' do
+      assert 42, stash.eval(42) {|a| a}
+    end
+
+  end
+
+  context '#gate' do
+
+    should 'evaluate on a key miss' do
+      ran = false
+      stash.gate(:k) {ran = true}
+      assert ran
+    end
+
+    should 'not evaluate on a key hit' do
+      ran = false
+      stash[:k] = :hit
+      stash.gate(:k) {ran = true}
+      assert !ran
+    end
+
+    should 'return true on hit' do
+      stash[:k] = :hit
+      assert stash.gate(:k) {}
+    end
+
+    should 'return false on miss' do
+      assert !stash.gate(:k) {}
+    end
+
+    should 'pass keys in as optional block arguments' do
+      key = nil
+      stash.gate(42) {|k| key = k}
+      assert_equal 42, key
+    end
+
+  end
+
+  context '#get' do
+
+    should 'allow simple get on the same keyspace as eval' do
+      stash.eval(:foo) {42}
+      assert_equal 42, stash[:foo]
+    end
+
+  end
+
+  context '#incr' do
+
+    should 'increment numeric values by the passed integer' do
+      stash.write(:a, '10')
+      assert_equal 12, stash.incr(:a, 2)
+    end
+
+    should 'return nil if it failed to increment' do
+      assert_nil stash.incr(:a, 3)
+    end
+
+  end
+
+  context '#read' do
+
+    should 'read raw strings from the cache' do
+      stash[:a] = 42
+      assert_equal Marshal.dump(42), stash.read(:a)
+    end
+
+    should 'return nil when the key is not found' do
+      assert_nil stash.read(:not_found)
+    end
+
+  end
+
+  context '#release' do
+
+    should 'return itself' do
+      assert_instance_of Stash, stash(:one).release
+    end
+
+    should 'remove it from the name registery' do
+      assert_not_equal stash(:one).release, stash(:one)
+    end
+
+  end
+
+  context '#scope' do
+
+    should 'set an implicit scope variable for keyspaces' do
+      a = 1
+      stash.scope {a}
+      stash[:k] = :v
+      a = 2
+      assert_nil stash[:k]
+    end
+
+    should 'be used by the vector key' do
+      one = stash(:one).release
+      two = stash(:one)
+      a = 0
+      one.scope {a}
+      one[:a] = 1
+      two.clear
+      one.cycle
+      assert_equal 1, one[:a]
+    end
+
+    should 'return self' do
+      assert_equal stash, stash.scope {}
+    end
+
+  end
+
+  context '#set' do
+
+    should 'allow simple set on the same keyspace as eval' do
+      stash.set(:a, 42)
+      assert_equal 42, stash.eval(:a) {fail 'expected cache hit'}
+    end
+
+  end
+
+  context '#transaction' do
+
+    should 'cycle the vector at the end of the transaction block' do
+      one = stash(:one).release
+      two = stash(:one)
+      one.transaction do
+        one[:a] = 42
+        two.clear
+        assert_equal 42, one[:a]
+      end
+      assert_nil one[:a]
+    end
+
+  end
+
+  context '#write' do
+
+    should 'write raw strings to the cache' do
+      stash.write(42, '42')
+      assert_equal '42', stash.read(42)
+    end
+
+  end
+
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification 
+name: binary42-remix-stash
+version: !ruby/object:Gem::Version 
+  version: 0.9.0
+platform: ruby
+authors: 
+- Brian Mitchell
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-29 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: binary42@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.mdown
+files: 
+- .gitignore
+- LICENSE
+- README.mdown
+- Rakefile
+- VERSION
+- examples/bench.rb
+- examples/eval.rb
+- examples/gate.rb
+- examples/getset.rb
+- examples/getset_cache.rb
+- examples/scope.rb
+- examples/stash.rb
+- harness.rb
+- harness_cache.rb
+- lib/remix/stash.rb
+- lib/remix/stash/cluster.rb
+- lib/remix/stash/extension.rb
+- lib/remix/stash/protocol.rb
+- remix-stash.gemspec
+- spec/extension_spec.rb
+- spec/spec.rb
+- spec/stash_spec.rb
+has_rdoc: true
+homepage: http://github.com/binary42/remix-stash
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Remix your memcache
+test_files: 
+- spec/extension_spec.rb
+- spec/spec.rb
+- spec/stash_spec.rb
+- examples/bench.rb
+- examples/eval.rb
+- examples/gate.rb
+- examples/getset.rb
+- examples/getset_cache.rb
+- examples/scope.rb
+- examples/stash.rb