Class: FastCache::Cache

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

Overview

In-process cache with least-recently used (LRU) and time-to-live (TTL) expiration semantics.

This implementation is not thread-safe. It does not use a thread to clean up expired values. Instead, an expiration check is performed:

  1. Every time you retrieve a value, against that value. If the value has expired, it will be removed and ‘nil` will be returned.

  2. Every ‘expire_interval` operations as the cache is used to remove all expired values up to that point.

For manual expiration call #expire!.

Examples:


# Create cache with one million elements no older than 1 hour
cache = FastCache::Cache.new(1_000_000, 60 * 60)
cached_value = cache.fetch('cached_value_key') do
  # Expensive computation that returns the value goes here
end

Author:

Defined Under Namespace

Classes: Entry

Instance Method Summary collapse

Constructor Details

#initialize(max_size, ttl, expire_interval = 100) ⇒ Cache

Initializes the cache.

Parameters:

  • max_size (Integer) —

    Maximum number of elements in the cache.

  • ttl (Numeric) —

    Maximum time, in seconds, for a value to stay in the cache.

  • expire_interval (Integer) (defaults to: 100) —

    Number of cache operations between calls to #expire!.



35
36
37
38
39
40
41
42
 
# File 'lib/fast_cache/cache.rb', line 35

def initialize(max_size, ttl, expire_interval = 100)
  @max_size = max_size
  @ttl = ttl.to_f
  @expire_interval = expire_interval
  @op_count = 0
  @data = {}
  @expires_at = {}
end

Instance Method Details

#[](key) ⇒ Object?

Retrieves a value from the cache.

Parameters:

  • key (Object) —

    the key to look up

Returns:

  • (Object, nil) —

    the value at the key, when present, or ‘nil`



64
65
66
67
 
# File 'lib/fast_cache/cache.rb', line 64

def [](key)
  _, value = get(key)
  value
end

#[]=(key, val) ⇒ Object

Stores a value in the cache.

Parameters:

  • key (Object) —

    the key to store at

  • val (Object) —

    the value to store

Returns:

  • (Object) —

    the value



74
75
76
77
 
# File 'lib/fast_cache/cache.rb', line 74

def []=(key, val)
  expire!
  store(key, val)
end

#clear ⇒ self

Clears the cache.

Returns:

  • (self) 


105
106
107
108
109
 
# File 'lib/fast_cache/cache.rb', line 105

def clear
  @data.clear
  @expires_at.clear
  self
end

#count ⇒ Integer Also known as: size, length

Note:

calls to #empty? do not count against ‘expire_interval`. Therefore, the number of elements is that prior to any expiration.

Returns the number of elements in the cache.

Returns:

  • (Integer) —

    number of elements in the cache.



117
118
119
 
# File 'lib/fast_cache/cache.rb', line 117

def count
  @data.count
end

#delete(key) ⇒ Object?

Removes a value from the cache.

Parameters:

  • key (Object) —

    the key to remove at

Returns:

  • (Object, nil) —

    the value at the key, when present, or ‘nil`



83
84
85
86
87
88
89
90
91
 
# File 'lib/fast_cache/cache.rb', line 83

def delete(key)
  entry = @data.delete(key)
  if entry
    @expires_at.delete(entry)
    entry.value
  else
    nil
  end
end

#each {|Array<key, value>| ... } ⇒ Enumerator, Array<key, value>

Note:

The returned values could have expired by the time the client code gets to accessing them.

Note:

Because of its stability, this operation is very expensive. Use with caution.

Allows iteration over the items in the cache.

Enumeration is stable: it is not affected by changes to the cache, including value expiration. Expired values are removed first.

Yields:

  • (Array<key, value>) —

    key/value pairs, when a block is provided.

Returns:

  • (Enumerator, Array<key, value>) —

    an Enumerator, when a block is not provided, or an array of key/value pairs.



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

def each(&block)
  expire!
  @data.map { |key, entry| [key, entry.value] }.each(&block)
end

#empty? ⇒ Boolean

Note:

calls to #empty? do not count against ‘expire_interval`.

Checks whether the cache is empty.

Returns:

  • (Boolean) 


98
99
100
 
# File 'lib/fast_cache/cache.rb', line 98

def empty?
  count == 0
end

#expire! ⇒ self

Removes expired values from the cache.

Returns:

  • (self) 


145
146
147
148
 
# File 'lib/fast_cache/cache.rb', line 145

def expire!
  check_expired(Time.now.to_f)
  self
end

#fetch(key) { ... } ⇒ Object

Retrieves a value from the cache, if available and not expired, or yields to a block that calculates the value to be stored in the cache.

Parameters:

  • key (Object) —

    the key to look up or store at

Yields:

  • yields when the value is not present

Yield Returns:

  • (Object) —

    the value to store in the cache.

Returns:

  • (Object) —

    the value at the key



51
52
53
54
55
56
57
58
 
# File 'lib/fast_cache/cache.rb', line 51

def fetch(key)
  found, value = get(key)
  if found
    value
  else
    store(key, yield)
  end
end

#inspect ⇒ String

Returns information about the number of objects in the cache, its maximum size and TTL.

Returns:

  • (String) 


154
155
156
 
# File 'lib/fast_cache/cache.rb', line 154

def inspect
  "<#{self.class.name} count=#{count} max_size=#{@max_size} ttl=#{@ttl}>"
end