Class: Elephas::Cache

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

Overview

This is the main class of the framework. Use only this class to access the cache.

Class Attribute Summary (collapse)

Class Method Summary (collapse)

Class Attribute Details

+ (Object) provider

The provider used for the caching.



12
13
14
 
# File 'lib/elephas/cache.rb', line 12

def provider
  @provider
end

Class Method Details

+ (String) default_prefix

Returns the default prefix for cache entries.

Returns:

  • (String) —

    The default prefix for cache entries.



96
97
98
 
# File 'lib/elephas/cache.rb', line 96

def default_prefix
  "elephas-#{::Elephas::Version::STRING}-cache"
end

+ (Boolean) delete(key)

Deletes a value from the cache.

Parameters:

  • key (String) —

    The key to delete.

Returns:

  • (Boolean) —

    true if the key was in the cache, false otherwise.



81
82
83
 
# File 'lib/elephas/cache.rb', line 81

def delete(key)
  self.provider.delete(key)
end

+ (Boolean) exists?(key)

Checks if a key exists in the cache.

Parameters:

  • key (String) —

    The key to lookup.

Returns:

  • (Boolean) —

    true if the key is in the cache, false otherwise.



89
90
91
 
# File 'lib/elephas/cache.rb', line 89

def exists?(key)
  self.provider.exists?(key)
end

+ (Object|NilClass) read(key)

Reads a value from the cache.

Parameters:

  • key (String) —

    The key to lookup.

Returns:

  • (Object|NilClass) —

    The read value or nil.



62
63
64
 
# File 'lib/elephas/cache.rb', line 62

def read(key)
  self.provider.read(key)
end

+ (Hash) setup_options(options, key)

Setups options for use into the framework. Valid options are:

  • :ttl: The TTL (time to live, in milliseconds) of the entry. It means how long will the value stay in cache. Setting it to 0 or less means never cache the entry.
  • :force: Setting it to true will always skip the cache.
  • :key: The key associated to this value. You should never set this option directly.
  • :prefix: The prefix used in cache. This is used to avoid conflicts with other caching frameworks.
  • :complete_key: The complete key used for computing the hash. By default is concatenation of :key and :prefix options.
  • :hash: The hash used to store the key in the cache. Should be unique
  • :as_entry: In Elephas::Cache.use, setting this to true will return the entire Entry object rather than the value only.

Parameters:

  • options (Object) —

    An initial setup.

  • key (String) —

    The key to associate to this options.

Returns:

  • (Hash) —

    An options hash.



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/elephas/cache.rb', line 114

def setup_options(options, key)
  options = {} if !options.is_a?(::Hash)
  options = {:ttl => 1.hour * 1000, :force => false, :as_entry => false}.merge(options)
  options[:key] ||= key.ensure_string
  options[:ttl] == options[:ttl].blank? ? 1.hour * 1000 : [options[:ttl].to_integer, 0].max
  options[:force] = options[:force].to_boolean
  options[:prefix] = options[:prefix].present? ? options[:prefix] : "elephas-#{::Elephas::Version::STRING}-cache"

  # Wrap the final key to ensure we don't have colliding namespaces.
  options[:complete_key] ||= "#{options[:prefix]}[#{options[:key]}]"

  # Compute the hash key used for referencing this value
  options[:hash] ||= ::Elephas::Entry.hashify_key(options[:complete_key])

  options
end

+ (Object|Entry) use(key, options = {})

This is the main method of the framework.

It tries reading a key from the cache.

If it doesn't find it, it uses the provided block (which receives options as argument) to compute its value and then store it into the cache for later usages.

value = Elephas::Cache.use("KEY") do |options|
  "VALUE"
end

value
# => "VALUE"

value = Elephas::Cache.use("KEY") do |options|
  "ANOTHER VALUE"
end

value
# => "VALUE"

Parameters:

  • key (String) —

    The key to lookup.

Returns:

  • (Object|Entry) —

    The found or newly-set value associated to the key.

See Also:



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/elephas/cache.rb', line 39

def use(key, options = {})
  rv = nil

  # Get options
  options = self.setup_options(options, key)

  # Check if the storage has the value (if we don't have to skip the cache)
  rv = self.provider.read(options[:hash]) if options[:force] == false && options[:ttl] > 0

  if rv.nil? && block_given? then # Try to compute the value from the block
    rv = yield(options)
    rv = ::Elephas::Entry.ensure(rv, options[:complete_key], options) # Make sure is an entry
    Elephas::Cache.write(rv.hash, rv, options) if !rv.value.nil? && options[:ttl] > 0 # We have a value and we have to store it
  end

  # Return value
  options[:as_entry] ? rv : rv.value.dup
end

+ (Object) write(key, value, options = {})

Writes a value to the cache.

Parameters:

  • key (String) —

    The key to associate the value with.

  • value (Object) —

    The value to write. Setting a value to nil doesn't mean deleting the value.

  • options (Hash) (defaults to: {}) —

    A list of options for writing.

Returns:

  • (Object) —

    The value itself.

See Also:



73
74
75
 
# File 'lib/elephas/cache.rb', line 73

def write(key, value, options = {})
  self.provider.write(key, value, self.setup_options(options, key))
end