Class: RustyLRU::Cache

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable, EnumHelpers
Defined in:
lib/rusty_lru/cache.rb

Overview

This class implements an LRU Cache.

Cache objects behave a lot like Ruby’s Hash class, but with the important difference that internally a list is maintained of all keys in order from most recently used to least recently used (LRU).

Additionally, if the cache is capped (see #initialize), then when the cache is full to capacity an operation that adds a new key will cause the key-value pair at the bottom of the LRU list (i.e. the least-recently-used pair) to be dropped from the cache. This way the cache never grows beyond a pre-determined size.

To precent items from being dropped, some operations (notably #[] and #[]= move the key to the front of the list.

Like Hash, this class includes the Enumerable module, so it responds to a number of methods not listed here, such as #map, #reduce, #to_a, #to_h, etc.

Like a Hash, values can be any object whatsoever, and keys can be any object that responds to #hash and #eql? correctly.

Defined Under Namespace

Modules: EnumHelpers

Instance Method Summary collapse

Constructor Details

#initialize(cap = nil) ⇒ Object

Initializes a new cache object.

If no cap is specified, the cache will be uncapped. A cap can be added later using #resize.

Examples:

Create a LRU cache with no cap

cache = RustyLRU::Cache.new

Create a LRU cache with a maximum of 100 items

cache = RustyLRU::Cache.new(100)



# File 'lib/rusty_lru/cache.rb', line 29

Instance Method Details

#[](key) ⇒ Object?

Retrieves a value from the cache by key, updating the LRU list.

Examples:

Retrieve a value

cache["x"] #=> "y"

Parameters:

  • key (Object) —

    The key to look up in the cache.

Returns:

  • (Object, nil) —

    The value corresponding to the key, or nil.




# File 'lib/rusty_lru/cache.rb', line 41

#[]=(key, value) ⇒ Object? Also known as: store

Stores a key-value pair in the cache, updating the LRU list.

The stored pair becomes the most recently used upon insertion/update.

Examples:

Store a pair

cache[:x] = "z"
cache[:x] = "y" #=> "z"

Parameters:

  • key (Object) —

    The key to store

  • value (Object) —

    The value to store

Returns:

  • (Object, nil) —

    The previous value, or ‘nil`.




# File 'lib/rusty_lru/cache.rb', line 50

#clear ⇒ nil

Removes all key-value pairs from the cache.

Returns:

  • (nil) 



# File 'lib/rusty_lru/cache.rb', line 130

#delete(key) ⇒ Object?

Deletes the key-value pair corresponding to the given key from the cache.

Examples:

Store and delete a pair

cache["key"] = :value
cache.delete("key") #=> :value

Parameters:

  • key (Object) —

    The key to delete

Returns:

  • (Object, nil) —

    The corresponding value, or nil




# File 'lib/rusty_lru/cache.rb', line 63

#each_key {|key| ... } ⇒ self #each_key ⇒ Enumerator

Overloads:

  • #each_key {|key| ... } ⇒ self

    Yields each key in the cache to the caller.

    Yield Parameters:

    • key (Object) —

      each key

    Returns:

    • (self)
  • #each_key ⇒ Enumerator

    Returns an Enumerator that will enumerate the keys in the cache.

    Returns:

    • (Enumerator) 



# File 'lib/rusty_lru/cache.rb', line 157

#each_pair {|key, value| ... } ⇒ self #each_pair ⇒ Enumerator Also known as: each

Overloads:

  • #each_pair {|key, value| ... } ⇒ self

    Yields each key-value pair in the cache to the caller.

    Examples:

    #each_pair with a block

    cache.each_pair do |key, value|
  puts "#{key} = #{value}"
end

    Yield Parameters:

    • key (Object) —

      each key

    • value (Object) —

      each value

    Returns:

    • (self)
  • #each_pair ⇒ Enumerator

    Returns an Enumerator that will enumerate all key-value pairs.

    Examples:

    Get a hash of values to keys

    cache.each_pair.map { |key, value| [value, key }.to_h

    Returns:

    • (Enumerator) 



# File 'lib/rusty_lru/cache.rb', line 135

#each_value {|value| ... } ⇒ self #each_value ⇒ Enumerator

Overloads:

  • #each_value {|value| ... } ⇒ self

    Yields each value in the cache to the caller.

    Yield Parameters:

    • value (Object) —

      each value

    Returns:

    • (self)
  • #each_value ⇒ Enumerator

    Returns an Enumerator for enumerating the values in the cache.

    Returns:

    • (Enumerator) 



# File 'lib/rusty_lru/cache.rb', line 170

#empty? ⇒ Boolean

Returns true iff the cache is empty.

Returns:

  • (Boolean) 



# File 'lib/rusty_lru/cache.rb', line 108

#has_key?(key) ⇒ Boolean Also known as: key?, member?

Returns true iff the given key is present. Does not affect the LRU list.

Parameters:

  • key (Object) —

    The key to test for.

Returns:

  • (Boolean) 



# File 'lib/rusty_lru/cache.rb', line 113

#keys ⇒ Array<Object>

Returns all keys in the cache as an array

Returns:

  • (Array<Object>) —

    All keys



206
 
# File 'lib/rusty_lru/cache.rb', line 206

def_delegator :each_key, :to_a, :keys

#length ⇒ Integer Also known as: size

Returns the number of key-value pairs stored in the cache.

Returns:

  • (Integer) 



# File 'lib/rusty_lru/cache.rb', line 119

#lru_pair ⇒ <(Object, Object)>?

Returns the least-recently used pair without affecting the LRU list.

This method is similar to #pop, but does not mutate the cache.

Examples:

Conditionally remove the LRU pair

cache.pop if cache.peek_lru == [:x, :y]

Returns:

  • (<(Object, Object)>, nil) —

    The least-recently-used pair, or nil.




# File 'lib/rusty_lru/cache.rb', line 98

#peek(key) ⇒ Object?

Retrieves a value from the cache by key without updating the LRU list.

This method is equivalent to #[], except that the LRU list is not affected.

Examples:

Peek into the cache

cache[:x] = "y"
cache.peek(:x) #=> "y"

Parameters:

  • key (Object) —

    The key too look up

Returns:

  • (Object, nil) —

    The corresponding value, or nil




# File 'lib/rusty_lru/cache.rb', line 85

#pop ⇒ <(Object, Object)>?

Deletes and returns the least-recently used key-value pair.

Examples:

Create a cache with two elements, pop the first one.

cache = RustyLRU::cache.new
cache[:a] = 1
cache[:b] = 2
cache.pop #=> [:a, 1]

Returns:

  • (<(Object, Object)>, nil) —

    The least-recently-used pair, or nil.




# File 'lib/rusty_lru/cache.rb', line 74

#resize(cap) ⇒ nil

Alters the store’s cap.

Parameters:

  • cap (Integer) —

    The new cap.

Returns:

  • (nil) 



# File 'lib/rusty_lru/cache.rb', line 124

#values ⇒ Array<Object>

Returns all values in the cache as an array

Returns:

  • (Array<Object>) —

    All values



212
 
# File 'lib/rusty_lru/cache.rb', line 212

def_delegator :each_value, :to_a, :values