ngmoco-cache-money 0.2.9

Sign up to get free protection for your applications and to get access to all the features.
data/README ADDED
@@ -0,0 +1,194 @@
1
+ ## What is Cache Money ##
2
+
3
+ Cache Money is a write-through and read-through caching library for ActiveRecord.
4
+
5
+ Read-Through: Queries like `User.find(:all, :conditions => ...)` will first look in Memcached and then look in the database for the results of that query. If there is a cache miss, it will populate the cache.
6
+
7
+ Write-Through: As objects are created, updated, and deleted, all of the caches are *automatically* kept up-to-date and coherent.
8
+
9
+ ## Howto ##
10
+ ### What kinds of queries are supported? ###
11
+
12
+ Many styles of ActiveRecord usage are supported:
13
+
14
+ * `User.find`
15
+ * `User.find_by_id`
16
+ * `User.find(:conditions => {:id => ...})`
17
+ * `User.find(:conditions => ['id = ?', ...])`
18
+ * `User.find(:conditions => 'id = ...')`
19
+ * `User.find(:conditions => 'users.id = ...')`
20
+
21
+ As you can see, the `find_by_`, `find_all_by`, hash, array, and string forms are all supported.
22
+
23
+ Queries with joins/includes are unsupported at this time. In general, any query involving just equality (=) and conjunction (AND) is supported by `Cache Money`. Disjunction (OR) and inequality (!=, <=, etc.) are not typically materialized in a hash table style index and are unsupported at this time.
24
+
25
+ Queries with limits and offsets are supported. In general, however, if you are running queries with limits and offsets you are dealing with large datasets. It's more performant to place a limit on the size of the `Cache Money` index like so:
26
+
27
+ DirectMessage.index :user_id, :limit => 1000
28
+
29
+ In this example, only queries whose limit and offset are less than 1000 will use the cache.
30
+
31
+ ### Multiple indices are supported ###
32
+
33
+ class User < ActiveRecord::Base
34
+ index :screen_name
35
+ index :email
36
+ end
37
+
38
+ #### `with_scope` support ####
39
+
40
+ `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 cache if there is an index like this:
41
+
42
+ class Device < ActiveRecord::Base
43
+ index [:user_id, :id]
44
+ end
45
+
46
+ ### Ordered indices ###
47
+
48
+ class Message < ActiveRecord::Base
49
+ index :sender_id, :order => :desc
50
+ end
51
+
52
+ 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:
53
+
54
+ * `Message.find(:all, :conditions => {:sender_id => ...}, :order => 'id DESC')`.
55
+
56
+ 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.
57
+
58
+ class Message < ActiveRecord::Base
59
+ index :sender_id, :order => :asc
60
+ end
61
+
62
+ will support queries like:
63
+
64
+ * `Message.find(:all, :conditions => {:sender_id => ...}, :order => 'id ASC')`
65
+ * `Message.find(:all, :conditions => {:sender_id => ...})`
66
+
67
+ Note that ascending order is implicit in index declarations (i.e., not specifying an order is the same as ascending). This is also true of queries (order is not nondeterministic as in MySQL).
68
+
69
+ ### Window indices ###
70
+
71
+ class Message < ActiveRecord::Base
72
+ index :sender_id, :limit => 500, :buffer => 100
73
+ end
74
+
75
+ 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.
76
+
77
+ It is particularly in conjunction with window indices that the `:order` attribute is useful.
78
+
79
+ ### Calculations ###
80
+
81
+ `Message.count(:all, :conditions => {:sender_id => ...})` will use the cache rather than the database. This happens for "free" -- no additional declarations are necessary.
82
+
83
+ ### Version Numbers ###
84
+
85
+ class User < ActiveRecord::Base
86
+ version 7
87
+ index ...
88
+ end
89
+
90
+ You can increment the version number as you migrate your schema. Be careful how you deploy changes like this as during deployment independent mongrels may be using different versions of your code. Indices can be corrupted if you do not plan accordingly.
91
+
92
+ ### Transactions ###
93
+
94
+ 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.
95
+
96
+ The memcache client library has been enhanced to simulate transactions.
97
+
98
+ $cache.transaction do
99
+ $cache.set(key1, value1)
100
+ $cache.set(key2, value2)
101
+ end
102
+
103
+ 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.
104
+
105
+ 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".
106
+
107
+ #### Rollbacks ####
108
+
109
+ $cache.transaction do
110
+ $cache.set(k, v)
111
+ raise
112
+ end
113
+
114
+ 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.
115
+
116
+ Nested transactions are fully supported, with partial rollback and (apparent) partial commitment (this is simulated with nested buffers).
117
+
118
+ ### Mocks ###
119
+
120
+ For your unit tests, it is faster to use a Memcached mock than the real deal. Just place this in your initializer for your test environment:
121
+
122
+ $memcache = Cash::Mock.new
123
+
124
+ ### Locks ###
125
+
126
+ In most cases locks are unnecessary; the transactional Memcached client will take care locks for you automatically and guarantees that no deadlocks can occur. But for very complex distributed transactions, shared locks are necessary.
127
+
128
+ $lock.synchronize('lock_name') do
129
+ $memcache.set("key", "value")
130
+ end
131
+
132
+ ### Local Cache ###
133
+
134
+ Sometimes your code will request the same cache key twice in one request. You can avoid a round trip to the Memcached server by using a local, per-request cache. Add this to your initializer:
135
+
136
+ $local = Cash::Local.new($memcache)
137
+ $cache = Cash::Transactional.new($local, $lock)
138
+
139
+ ## Installation ##
140
+
141
+ #### Step 0: Install MemCached
142
+
143
+ #### Step 1: Get the GEM ####
144
+
145
+ % gem sources -a http://gems.github.com
146
+ % sudo gem install ngmoco-cache-money
147
+
148
+ #### Step 2: Configure MemCached.
149
+
150
+ Place a YAML file in `config/memcached.yml` with contents like:
151
+
152
+ test:
153
+ ttl: 604800
154
+ namespace: ...
155
+ sessions: false
156
+ debug: false
157
+ servers: localhost:11211
158
+ cache_money: true
159
+
160
+ development:
161
+ ....
162
+
163
+ #### Step 3: `config/environment.rb` ####
164
+ config.gem "ngmoco-cache-money",
165
+ :lib => "cache_money",
166
+ :source => 'http://gems.github.com',
167
+ :version => '0.2.9'
168
+
169
+ #### Step 4: Add indices to your ActiveRecord models ####
170
+
171
+ Queries like `User.find(1)` will use the cache automatically. For more complex queries you must add indices on the attributes that you will query on. For example, a query like `User.find(:all, :conditions => {:name => 'bob'})` will require an index like:
172
+
173
+ class User < ActiveRecord::Base
174
+ index :name
175
+ end
176
+
177
+ For queries on multiple attributes, combination indexes are necessary. For example, `User.find(:all, :conditions => {:name => 'bob', :age => 26})`
178
+
179
+ class User < ActiveRecord::Base
180
+ index [:name, :age]
181
+ end
182
+
183
+ ## Version ##
184
+
185
+ WARNING: This is currently a RELEASE CANDIDATE. A version of this code is in production use at Twitter but the extraction and refactoring process may have introduced bugs and/or performance problems. There are no known major defects at this point, but still.
186
+
187
+ ## Acknowledgments ##
188
+
189
+ Thanks to
190
+
191
+ * Twitter for commissioning the development of this library and supporting the effort to open-source it.
192
+ * Sam Luckenbill for pairing with me on most of the hard stuff.
193
+ * Matthew and Chris for pairing a few days, offering useful feedback on the readability of the code, and the initial implementation of the Memcached mock.
194
+ * Evan Weaver for helping to reason-through software and testing strategies to deal with replication lag, and the initial implementation of the Memcached lock.
data/TODO ADDED
@@ -0,0 +1,17 @@
1
+ TOP PRIORITY
2
+
3
+ REFACTOR
4
+ * Clarify terminology around cache/key/index, etc.
5
+
6
+ INFRASTRUCTURE
7
+
8
+ NEW FEATURES
9
+ * transactional get multi isn't really multi
10
+
11
+ BUGS
12
+ * Handle append strategy (using add rather than set?) to avoid race condition
13
+
14
+ MISSING TESTS:
15
+ * missing tests for Klass.transaction do ... end
16
+ * non "id" pks work but lack test coverage
17
+ * expire_cache
@@ -0,0 +1,14 @@
1
+ * does not work with :dependent => nullify because
2
+ def nullify_has_many_dependencies(record, reflection_name, association_class, primary_key_name, dependent_conditions)
3
+ association_class.update_all("#{primary_key_name} = NULL", dependent_conditions)
4
+ end
5
+ This does not trigger callbacks
6
+ * update_all, delete, update_counter, increment_counter, decrement_counter, counter_caches in general - counter caches are replaced by this gem, bear that in mind.
7
+ * attr_readonly - no technical obstacle, just not yet supported
8
+ * attributes before typecast behave unpredictably - hard to support
9
+ * ActiveRecord::Rollback is unsupported - the exception gets swallowed so there isn't an opportunity to rollback the cache transaction - not hard to support
10
+ * Named bind variables :conditions => ["name = :name", { :name => "37signals!" }] - not hard to support
11
+ * printf style binds: :conditions => ["name = '%s'", "37signals!"] - not too hard to support
12
+ * objects as attributes that are serialized. story.title = {:foo => :bar}; customer.balance = Money.new(...) - these could be coerced using Column#type_cast?
13
+
14
+ With a lot of these features the issue is not technical but performance. Every special case costs some overhead.
@@ -0,0 +1,6 @@
1
+ require 'activerecord'
2
+
3
+ ActiveRecord::Base.establish_connection(
4
+ :adapter => 'sqlite3',
5
+ :dbfile => ':memory:'
6
+ )
@@ -0,0 +1,6 @@
1
+ test:
2
+ ttl: 604800
3
+ namespace: cache
4
+ sessions: false
5
+ debug: false
6
+ servers: localhost:11211
@@ -0,0 +1,12 @@
1
+ ActiveRecord::Schema.define(:version => 2) do
2
+ create_table "stories", :force => true do |t|
3
+ t.string "title", "subtitle"
4
+ t.string "type"
5
+ t.boolean "published"
6
+ end
7
+
8
+ create_table "characters", :force => true do |t|
9
+ t.integer "story_id"
10
+ t.string "name"
11
+ end
12
+ end
data/init.rb ADDED
@@ -0,0 +1 @@
1
+ require File.join(File.basedir(__FILE__),'rails','init')
@@ -0,0 +1,55 @@
1
+ $LOAD_PATH.unshift(File.dirname(__FILE__))
2
+
3
+ require 'rubygems'
4
+ require 'activesupport'
5
+ require 'activerecord'
6
+
7
+ require 'cash/lock'
8
+ require 'cash/transactional'
9
+ require 'cash/write_through'
10
+ require 'cash/finders'
11
+ require 'cash/buffered'
12
+ require 'cash/index'
13
+ require 'cash/config'
14
+ require 'cash/accessor'
15
+
16
+ require 'cash/request'
17
+ require 'cash/fake'
18
+ require 'cash/local'
19
+
20
+ require 'cash/query/abstract'
21
+ require 'cash/query/select'
22
+ require 'cash/query/primary_key'
23
+ require 'cash/query/calculation'
24
+
25
+ require 'cash/util/array'
26
+ require 'cash/util/marshal'
27
+
28
+ class ActiveRecord::Base
29
+ def self.is_cached(options = {})
30
+ options.assert_valid_keys(:ttl, :repository, :version)
31
+ include Cash unless ancestors.include?(Cash)
32
+ Cash::Config.create(self, options)
33
+ end
34
+ end
35
+
36
+ module Cash
37
+ def self.included(active_record_class)
38
+ active_record_class.class_eval do
39
+ include Config, Accessor, WriteThrough, Finders
40
+ extend ClassMethods
41
+ end
42
+ end
43
+
44
+ module ClassMethods
45
+ def self.extended(active_record_class)
46
+ class << active_record_class
47
+ alias_method_chain :transaction, :cache_transaction
48
+ end
49
+ end
50
+
51
+ def transaction_with_cache_transaction(&block)
52
+ repository.transaction { transaction_without_cache_transaction(&block) }
53
+ end
54
+ end
55
+ end
@@ -0,0 +1,83 @@
1
+ module Cash
2
+ module Accessor
3
+ def self.included(a_module)
4
+ a_module.module_eval do
5
+ extend ClassMethods
6
+ include InstanceMethods
7
+ end
8
+ end
9
+
10
+ module ClassMethods
11
+ def fetch(keys, options = {}, &block)
12
+ case keys
13
+ when Array
14
+ return {} if keys.empty?
15
+
16
+ keys = keys.collect { |key| cache_key(key) }
17
+ hits = repository.get_multi(*keys)
18
+ if (missed_keys = keys - hits.keys).any?
19
+ missed_values = block.call(missed_keys)
20
+ hits.merge!(missed_keys.zip(Array(missed_values)).to_hash_without_nils)
21
+ end
22
+ hits
23
+ else
24
+ repository.get(cache_key(keys), options[:raw]) || (block ? block.call : nil)
25
+ end
26
+ end
27
+
28
+ def get(keys, options = {}, &block)
29
+ case keys
30
+ when Array
31
+ fetch(keys, options, &block)
32
+ else
33
+ fetch(keys, options) do
34
+ if block_given?
35
+ add(keys, result = yield(keys), options)
36
+ result
37
+ end
38
+ end
39
+ end
40
+ end
41
+
42
+ def add(key, value, options = {})
43
+ if repository.add(cache_key(key), value, options[:ttl] || cache_config.ttl, options[:raw]) == "NOT_STORED\r\n"
44
+ yield if block_given?
45
+ end
46
+ end
47
+
48
+ def set(key, value, options = {})
49
+ repository.set(cache_key(key), value, options[:ttl] || cache_config.ttl, options[:raw])
50
+ end
51
+
52
+ def incr(key, delta = 1, ttl = nil)
53
+ ttl ||= cache_config.ttl
54
+ repository.incr(cache_key = cache_key(key), delta) || begin
55
+ repository.add(cache_key, (result = yield).to_s, ttl, true) { repository.incr(cache_key) }
56
+ result
57
+ end
58
+ end
59
+
60
+ def decr(key, delta = 1, ttl = nil)
61
+ ttl ||= cache_config.ttl
62
+ repository.decr(cache_key = cache_key(key), delta) || begin
63
+ repository.add(cache_key, (result = yield).to_s, ttl, true) { repository.decr(cache_key) }
64
+ result
65
+ end
66
+ end
67
+
68
+ def expire(key)
69
+ repository.delete(cache_key(key))
70
+ end
71
+
72
+ def cache_key(key)
73
+ "#{name}:#{cache_config.version}/#{key.to_s.gsub(' ', '+')}"
74
+ end
75
+ end
76
+
77
+ module InstanceMethods
78
+ def expire
79
+ self.class.expire(id)
80
+ end
81
+ end
82
+ end
83
+ end
@@ -0,0 +1,126 @@
1
+ module Cash
2
+ class Buffered
3
+ def self.push(cache, lock)
4
+ if cache.is_a?(Buffered)
5
+ cache.push
6
+ else
7
+ Buffered.new(cache, lock)
8
+ end
9
+ end
10
+
11
+ def initialize(memcache, lock)
12
+ @buffer = {}
13
+ @commands = []
14
+ @cache = memcache
15
+ @lock = lock
16
+ end
17
+
18
+ def pop
19
+ @cache
20
+ end
21
+
22
+ def push
23
+ NestedBuffered.new(self, @lock)
24
+ end
25
+
26
+ def get(key, *options)
27
+ if @buffer.has_key?(key)
28
+ @buffer[key]
29
+ else
30
+ @buffer[key] = @cache.get(key, *options)
31
+ end
32
+ end
33
+
34
+ def set(key, value, *options)
35
+ @buffer[key] = value
36
+ buffer_command Command.new(:set, key, value, *options)
37
+ end
38
+
39
+ def incr(key, amount = 1)
40
+ return unless value = get(key, true)
41
+
42
+ @buffer[key] = value.to_i + amount
43
+ buffer_command Command.new(:incr, key, amount)
44
+ @buffer[key]
45
+ end
46
+
47
+ def decr(key, amount = 1)
48
+ return unless value = get(key, true)
49
+
50
+ @buffer[key] = [value.to_i - amount, 0].max
51
+ buffer_command Command.new(:decr, key, amount)
52
+ @buffer[key]
53
+ end
54
+
55
+ def add(key, value, *options)
56
+ @buffer[key] = value
57
+ buffer_command Command.new(:add, key, value, *options)
58
+ end
59
+
60
+ def delete(key, *options)
61
+ @buffer[key] = nil
62
+ buffer_command Command.new(:delete, key, *options)
63
+ end
64
+
65
+ def get_multi(*keys)
66
+ values = keys.collect { |key| get(key) }
67
+ keys.zip(values).to_hash_without_nils
68
+ end
69
+
70
+ def flush
71
+ sorted_keys = @commands.select(&:requires_lock?).collect(&:key).uniq.sort
72
+ sorted_keys.each do |key|
73
+ @lock.acquire_lock(key)
74
+ end
75
+ perform_commands
76
+ ensure
77
+ @buffer = {}
78
+ sorted_keys.each do |key|
79
+ @lock.release_lock(key)
80
+ end
81
+ end
82
+
83
+ def method_missing(method, *args, &block)
84
+ @cache.send(method, *args, &block)
85
+ end
86
+
87
+ def respond_to?(method)
88
+ @cache.respond_to?(method)
89
+ end
90
+
91
+ protected
92
+ def perform_commands
93
+ @commands.each do |command|
94
+ command.call(@cache)
95
+ end
96
+ end
97
+
98
+ def buffer_command(command)
99
+ @commands << command
100
+ end
101
+ end
102
+
103
+ class NestedBuffered < Buffered
104
+ def flush
105
+ perform_commands
106
+ end
107
+ end
108
+
109
+ class Command
110
+ attr_accessor :key
111
+
112
+ def initialize(name, key, *args)
113
+ @name = name
114
+ @key = key
115
+ @args = args
116
+ end
117
+
118
+ def requires_lock?
119
+ @name == :set
120
+ end
121
+
122
+ def call(cache)
123
+ cache.send @name, @key, *@args
124
+ end
125
+ end
126
+ end