nkallen-cash 0.1.1

data/README

@@ -0,0 +1,132 @@
+=== A single index ===
+
+{{{
+    $memcache = MemCache.new(config)
+    $memcache.servers = config['servers']
+    $lock = Cash::Lock.new($memcache)
+    $cache = Cash::Transactional.new($memcache, $lock)
+
+    class User
+      is_cached :repository => $cache
+      index :id
+    end
+}}}
+
+The `index :id` declaration:
+
+ * Adds a number of annotation to populate the cache when a `user` is created, updated, or deleted.
+ * Overrides some finders to first look in the cache, then the database. For example: `User.find`, `User.find_by_id`, `User.find(:conditions => {:id => ...})`, `User.find(:conditions => ['id = ?', ...])`, `User.find(:conditions => 'id = ...')`, `User.find(:conditions => 'users.id = ...')`, and `User.find(:conditions => '`users`.id = ...')`.
+ * Ensures that queries that must not hit the cache (e.g., if they include `:joins`) will hit the database instead.
+
+=== Multiple indices ===
+
+{{{
+    index :id
+    index :screen_name
+    index :email
+}}}
+
+This creates three indices, populates them as side effects of CUD operations, and overrides their corresponding finders (e.g., `User.find_by_screen_name` and all of the variations).
+
+=== Multi-key indices ===
+
+{{{
+    class Device
+      index [:user_id, :id]
+    end
+}}}
+
+This creates an index whose key is the concatenation of the two attributes. Finders will first look in the cache for these keys if they resemble `Device.find(:conditions => {:id => ..., :user_id => ...})`, `User.find(:conditions => "id = ... AND user_id = ...")`, etc.
+
+==== with_scope support ====
+
+`with_scope` and the like (`named_scope`, `has_many`, `belongs_to`, etc.) are fully supported. For example, `user.devices.find(1)` will first look in the `Device` cache for the index `[:user_id, :id]`.
+
+=== Collections ===
+
+{{{
+    class Devices
+      index [:user_id]
+    end
+}}}
+
+Collection indices are supported. For example, many devices may belong to the same user. Indexing devices on `user_id` will append new devices to that key on create, remove on delete, etc. `find` queries with `user_id` in the conditions will hit the cache before the database.
+
+=== Deletions ===
+
+In fact, all indices are treated as collection indices, even ones where the key is guaranteed unique (i.e., the cardinality of the index is 1). This allows us to support deletions correctly. `User.find(1)` will first hit the cache; if the cache value is `[]` (the empty array), then nil is returned--the database is never queried.
+
+=== Complex Queries ===
+
+{{{
+    class FriendRequest
+      index :requestor_id
+    end
+}}}
+
+In this example, `requestor_id` is a collection index. Limit and offset are supported. If the cache is populated, `FriendRequest.find(:all, :conditions => {:requestor_id => ...}, :limit => ..., :offset => ...)` will perform the limits and offsets with array arithmetic rather than a database query.
+
+=== Ordered indices ===
+
+{{{
+   class Message
+     index :sender_id, :order => :desc
+   end
+}}}
+
+The order declaration will ensure that the index is kept in the correctly sorted order. Only queries with order clauses compatible with the ordering in the index will use the cache: `Message.find(:all, :conditions => {:sender_id => ...})`, `Message.find(:all, :conditions => {:sender_id => ...}, :order => 'id DESC')`. Order clauses can be specified in many formats ("`messages`.id DESC", "`messages`.`id` DESC", and so forth), but ordering MUST be on the primary key column. Note that `Message.find(:all, :conditions => {:sender_id => ...}, :order => 'id ASC')` will NOT use the cache because the order in the query does not match the index.
+
+=== Window indices ===
+
+{{{
+   class Message
+     index :sender_id, :limit => 500, :buffer => 100
+   end
+}}}
+
+With a limit attribute, indices will only store limit + buffer in the cache. As new objects are created the index will be truncated, and as objects are destroyed, the cache will be refreshed if it has fewer than the limit of items. The buffer is how many "extra" items to keep around in case of deletes.
+
+=== Calculations ===
+
+`Message.count(:all, :conditions => {:sender_id => ...})` will use the cache rather than the database. This happens for "free" -- no additional declarations are necessary.
+
+=== Transactions ===
+
+Because of the parallel requests writing to the same indices, race conditions are possible. We have created a pessimistic "transactional" memcache client to handle the locking issues.
+
+The memcache client library has been enhanced to simulate transactions.
+
+{{{
+    CACHE.transaction do
+      CACHE.set(key1, value1)
+      CACHE.set(key2, value2)
+    end
+}}}
+
+The writes to the cache are buffered until the transaction is committed. Reads within the transaction read from the buffer. The writes are performed as if atomically, by acquiring locks, performing writes, and finally releasing locks. Special attention has been paid to ensure that deadlocks cannot occur and that the critical region (the duration of lock ownership) is as small as possible.
+
+Writes are not truly atomic as reads do not pay attention to locks. Therefore, it is possible to peak inside a partially committed transaction. This is a performance compromise, since acquiring a lock for a read was deemed too expensive. Again, the critical region is as small as possible, reducing the frequency of such "peeks".
+
+==== Rollbacks ====
+
+{{{
+    CACHE.transaction do
+      CACHE.set(k, v)
+      raise
+    end
+}}}
+
+Because transactions buffer writes, an exception in a transaction ensures that the writes are cleanly rolled-back (i.e., never committed to memcache). Database transactions are wrapped in memcache transactions, ensuring a database rollback also rolls back cache transactions.
+
+==== Nested transactions ====
+
+{{{
+    CACHE.transaction do
+      CACHE.set(k, v)
+      CACHE.transaction do
+        CACHE.get(k)
+      end
+    end
+}}}
+
+Nested transactions are fully supported, with partial rollback and (apparent) partial commitment (this is simulated with nested buffers).

data/TODO

@@ -0,0 +1,19 @@
+TOP PRIORITY
+* cache_fu adapter
+
+REFACTOR
+* Reorganize transactional spec
+* Clarify terminology around cache/key/index, etc.
+
+INFRASTRUCTURE
+
+NEW FEATURES
+* transactional get multi isn't really multi
+
+BUGS
+* Handle append strategy (using add rather than set?) to avoid race condition
+
+MISSING TESTS:
+* missing tests for Klass.transaction do ... end
+* non "id" pks work but lack test coverage
+* expire_cache

data/UNSUPPORTED_FEATURES

@@ -0,0 +1,14 @@
+* does not work with :dependent => nullify because
+  def nullify_has_many_dependencies(record, reflection_name, association_class, primary_key_name, dependent_conditions)
+    association_class.update_all("#{primary_key_name} = NULL", dependent_conditions)
+  end
+  This does not trigger callbacks
+* update_all, delete, update_counter, increment_counter, decrement_counter, counter_caches in general - counter caches are replaced by this gem, bear that in mind.
+* attr_readonly - no technical obstacle, just not yet supported
+* attributes before typecast behave unpredictably - hard to support
+* ActiveRecord::Rollback is unsupported - the exception gets swallowed so there isn't an opportunity to rollback the cache transaction - not hard to support
+* Named bind variables :conditions => ["name = :name", { :name => "37signals!" }] - not hard to support
+* printf style binds: :conditions => ["name = '%s'", "37signals!"] - not too hard to support
+* objects as attributes that are serialized. story.title = {:foo => :bar}; customer.balance = Money.new(...) - these could be coerced using Column#type_cast?
+
+With a lot of these features the issue is not technical but performance. Every special case costs some overhead.

data/config/environment.rb

@@ -0,0 +1,13 @@
+require 'activerecord'
+
+ActiveRecord::Base.establish_connection(
+  :adapter => 'mysql',
+  :socket => '/tmp/mysql.sock',
+  :host => 'web030',
+  :port => 3306,
+  :username => 'root',
+  :password => '',
+  :encoding => 'UTF8',
+  :host => 'localhost',
+  :database => 'cash_test'
+)

data/config/memcache.yml

@@ -0,0 +1,6 @@
+test:
+  ttl: 604800
+  namespace: cache
+  sessions: false
+  debug: false
+  servers: localhost:11211

data/db/schema.rb

@@ -0,0 +1,11 @@
+ActiveRecord::Schema.define(:version => 1) do
+  create_table "stories", :force => true do |t|
+    t.string "title", "subtitle"
+    t.string  "type"
+  end
+
+  create_table "characters", :force => true do |t|
+    t.integer "story_id"
+    t.string "name"
+  end
+end

data/lib/cash.rb

@@ -0,0 +1,49 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'rubygems'
+require 'activesupport'
+require 'activerecord'
+
+require 'cash/lock'
+require 'cash/transactional'
+require 'cash/write_through'
+require 'cash/finders'
+require 'cash/buffered'
+require 'cash/index'
+require 'cash/config'
+require 'cash/accessor'
+
+require 'cash/query/abstract'
+require 'cash/query/select'
+require 'cash/query/primary_key'
+require 'cash/query/calculation'
+
+require 'cash/util/array'
+
+class ActiveRecord::Base
+  def self.is_cached(options = {})
+    include Cash
+    Config.create(self, options)
+  end
+end
+
+module Cash
+  def self.included(active_record_class)
+    active_record_class.class_eval do
+      include Config, Accessor, WriteThrough, Finders
+      extend ClassMethods
+    end
+  end
+
+  module ClassMethods
+    def self.extended(active_record_class)
+      class << active_record_class
+        alias_method_chain :transaction, :cache_transaction
+      end
+    end
+    
+    def transaction_with_cache_transaction(&block)
+      repository.transaction { transaction_without_cache_transaction(&block) }
+    end
+  end
+end

data/lib/cash/accessor.rb

@@ -0,0 +1,78 @@
+module Cash
+  module Accessor
+    def self.included(a_module)
+      a_module.module_eval do
+        extend ClassMethods
+        include InstanceMethods
+      end
+    end
+
+    module ClassMethods
+      def fetch(keys, options = {}, &block)
+        case keys
+        when Array
+          keys = keys.collect { |key| cache_key(key) }
+          hits = repository.get_multi(keys)
+          if (missed_keys = keys - hits.keys).any?
+            missed_values = block.call(missed_keys)
+            hits.merge!(Hash[*missed_keys.zip(Array(missed_values)).flatten])
+          end
+          hits
+        else
+          repository.get(cache_key(keys), options[:raw]) || (block ? block.call : nil)
+        end
+      end
+
+      def get(keys, options = {}, &block)
+        case keys
+        when Array
+          fetch(keys, options, &block)
+        else
+          fetch(keys, options) do
+            if block_given?
+              add(keys, result = yield(keys))
+              result
+            end
+          end
+        end
+      end
+
+      def add(key, value, options = {})
+        repository.add(cache_key(key), value, options[:ttl] || 0, options[:raw])
+      end
+
+      def set(key, value, options = {})
+        repository.set(cache_key(key), value, options[:ttl] || 0, options[:raw])
+      end
+
+      def incr(key, delta = 1, ttl = 0)
+        repository.incr(cache_key(key), delta) || begin
+          repository.set(cache_key(key), (result = yield).to_s, ttl, true)
+          result
+        end
+      end
+      
+      def decr(key, delta = 1, ttl = 0)
+        repository.decr(cache_key(key), delta) || begin
+          repository.set(cache_key(key), (result = yield).to_s, ttl, true)
+          result
+        end
+      end
+
+      def expire(key)
+        repository.delete(cache_key(key))
+      end
+
+      def cache_key(key)
+        "#{name}/#{key.to_s.gsub(' ', '+')}"
+      end
+    end
+    
+    module InstanceMethods
+      def expire
+        self.class.expire(id)
+      end
+      alias_method :expire_cache, :expire
+    end
+  end
+end

data/lib/cash/buffered.rb

@@ -0,0 +1,129 @@
+module Cash
+  class Buffered
+    def self.push(cache, lock)
+      if cache.is_a?(Buffered)
+        cache.push
+      else
+        Buffered.new(cache, lock)
+      end
+    end
+
+    def initialize(memcache, lock)
+      @buffer = {}
+      @commands = []
+      @cache = memcache
+      @lock = lock
+    end
+
+    def pop
+      @cache
+    end
+
+    def push
+      NestedBuffered.new(self, @lock)
+    end
+
+    def get(key, *options)
+      if @buffer.has_key?(key)
+        @buffer[key]
+      else
+        @buffer[key] = @cache.get(key, *options)
+      end
+    end
+
+    def set(key, value, *options)
+      @buffer[key] = value
+      buffer_command Command.new(:set, key, value, *options)
+    end
+
+    def incr(key, amount = 1)
+      return unless value = get(key, true)
+
+      @buffer[key] = value.to_i + amount
+      buffer_command Command.new(:incr, key, amount)
+      @buffer[key]
+    end
+
+    def decr(key, amount = 1)
+      return unless value = get(key, true)
+
+      @buffer[key] = [value.to_i - amount, 0].max
+      buffer_command Command.new(:decr, key, amount)
+      @buffer[key]
+    end
+
+    def add(key, value, *options)
+      @buffer[key] = value
+      buffer_command Command.new(:add, key, value, *options)
+    end
+
+    def delete(key, *options)
+      @buffer[key] = nil
+      buffer_command Command.new(:delete, key, *options)
+    end
+
+    def get_multi(args)
+      values = args.collect { |arg| get(arg) }
+      keys_and_values = args.zip(values)
+      keys_and_values_without_nils = keys_and_values.reject { |key, value| value.nil? }
+      shallow_flattened_keys_and_values_without_nils = keys_and_values_without_nils.inject([]) { |result, pair| result += pair }
+      Hash[*shallow_flattened_keys_and_values_without_nils]
+    end
+
+    def flush
+      sorted_keys = @commands.select(&:requires_lock?).collect(&:key).uniq.sort
+      sorted_keys.each do |key|
+        @lock.acquire_lock(key)
+      end
+      perform_commands
+    ensure
+      @buffer = {}
+      sorted_keys.each do |key|
+        @lock.release_lock(key)
+      end
+    end
+
+    def method_missing(method, *args, &block)
+      @cache.send(method, *args, &block)
+    end
+
+    def respond_to?(method)
+      @cache.respond_to?(method)
+    end
+
+    protected
+    def perform_commands
+      @commands.each do |command|
+        command.call(@cache)
+      end
+    end
+
+    def buffer_command(command)
+      @commands << command
+    end
+  end
+
+  class NestedBuffered < Buffered
+    def flush
+      perform_commands
+    end
+  end
+
+  class Command
+    attr_accessor :key
+
+    def initialize(name, key, *args)
+      @name = name
+      @key = key
+      @args = args
+    end
+
+    def requires_lock?
+      @name == :set
+    end
+
+    def call(cache)
+      cache.send @name, @key, *@args
+    end
+  end
+end