Class: Zache

Inherits:
Object
  • Object
show all
Defined in:
lib/zache.rb

Overview

It is a very simple thread-safe in-memory cache with an ability to expire keys automatically, when their lifetime is over. Use it like this:

require 'zache'
zache = Zache.new
# Expires in 5 minutes
v = zache.get(:count, lifetime: 5 * 60) { expensive() }

For more information read README file.

Author

Yegor Bugayenko ([email protected])

Copyright

Copyright © 2018-2024 Yegor Bugayenko

License

MIT

Defined Under Namespace

Classes: Fake

Instance Method Summary collapse

Constructor Details

#initialize(sync: true, dirty: false) ⇒ Zache

Makes a new object of the cache.

“sync” is whether the hash is thread-safe (‘true`) or not (`false`); it is recommended to leave this parameter untouched, unless you really know what you are doing.

If the dirty argument is set to true, a previously calculated result will be returned if it exists and is already expired.



77
78
79
80
81
82
 
# File 'lib/zache.rb', line 77

def initialize(sync: true, dirty: false)
  @hash = {}
  @sync = sync
  @dirty = dirty
  @mutex = Mutex.new
end

Instance Method Details

#clean ⇒ Object

Remove keys that are expired.



179
180
181
 
# File 'lib/zache.rb', line 179

def clean
  synchronized { @hash.delete_if { |key, _value| expired?(key) } }
end

#empty? ⇒ Boolean

Returns:

  • (Boolean) 


183
184
185
 
# File 'lib/zache.rb', line 183

def empty?
  @hash.empty?
end

#exists?(key, dirty: false) ⇒ Boolean

Checks whether the value exists in the cache by the provided key. Returns TRUE if the value is here. If the key is already expired in the hash, it will be removed by this method and the result will be FALSE.

Returns:

  • (Boolean) 


119
120
121
122
123
124
125
126
 
# File 'lib/zache.rb', line 119

def exists?(key, dirty: false)
  rec = @hash[key]
  if expired?(key) && !dirty && !@dirty
    @hash.delete(key)
    rec = nil
  end
  !rec.nil?
end

#expired?(key) ⇒ Boolean

Checks whether the key exists in the cache and is expired. If the key is absent FALSE is returned.

Returns:

  • (Boolean) 


130
131
132
133
 
# File 'lib/zache.rb', line 130

def expired?(key)
  rec = @hash[key]
  !rec.nil? && rec[:start] < Time.now - rec[:lifetime]
end

#get(key, lifetime: 2**32, dirty: false, &block) ⇒ Object

Gets the value from the cache by the provided key.

If the value is not found in the cache, it will be calculated via the provided block. If the block is not given, an exception will be raised (unless dirty is set to true). The lifetime must be in seconds. The default lifetime is huge, which means that the key will never be expired.

If the dirty argument is set to true, a previously calculated result will be returned if it exists and is already expired.



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/zache.rb', line 100

def get(key, lifetime: 2**32, dirty: false, &block)
  if block_given?
    return @hash[key][:value] if (dirty || @dirty) && locked? && expired?(key) && @hash.key?(key)
    synchronized { calc(key, lifetime, &block) }
  else
    rec = @hash[key]
    if expired?(key)
      return rec[:value] if dirty || @dirty
      @hash.delete(key)
      rec = nil
    end
    raise 'The key is absent in the cache' if rec.nil?
    rec[:value]
  end
end

#locked? ⇒ Boolean

Is cache currently locked doing something?

Returns:

  • (Boolean) 


143
144
145
 
# File 'lib/zache.rb', line 143

def locked?
  @mutex.locked?
end

#mtime(key) ⇒ Object

Returns the modification time of the key, if it exists. If not, current time is returned.



137
138
139
140
 
# File 'lib/zache.rb', line 137

def mtime(key)
  rec = @hash[key]
  rec.nil? ? Time.now : rec[:start]
end

#put(key, value, lifetime: 2**32) ⇒ Object

Put a value into the cache.



148
149
150
151
152
153
154
155
156
 
# File 'lib/zache.rb', line 148

def put(key, value, lifetime: 2**32)
  synchronized do
    @hash[key] = {
      value: value,
      start: Time.now,
      lifetime: lifetime
    }
  end
end

#remove(key) ⇒ Object

Removes the value from the cache, by the provided key. If the key is absent and the block is provided, the block will be called.



160
161
162
 
# File 'lib/zache.rb', line 160

def remove(key)
  synchronized { @hash.delete(key) { yield if block_given? } }
end

#remove_all ⇒ Object

Remove all keys from the cache.



165
166
167
 
# File 'lib/zache.rb', line 165

def remove_all
  synchronized { @hash = {} }
end

#remove_by ⇒ Object

Remove all keys that match the block.



170
171
172
173
174
175
176
 
# File 'lib/zache.rb', line 170

def remove_by
  synchronized do
    @hash.each_key do |k|
      @hash.delete(k) if yield(k)
    end
  end
end

#size ⇒ Object

Total number of keys currently in cache.



85
86
87
 
# File 'lib/zache.rb', line 85

def size
  @hash.size
end