Class: RustyLRU::Cache

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable
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.

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 26

Instance Method Details

#[](key) ⇒ Object?

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

Examples:

Retrieve a value

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

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

#[]=(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"

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

#clearnil

Removes all key-value pairs from the cache.


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

#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

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

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

Overloads:

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

    Yields each key in the cache to the caller.

    Yield Parameters:

    • key (Object)

      each key

  • #each_keyEnumerator

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


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

#each_pair {|key, value| ... } ⇒ self #each_pairEnumerator 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

  • #each_pairEnumerator

    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

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

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

Overloads:

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

    Yields each value in the cache to the caller.

    Yield Parameters:

    • value (Object)

      each value

  • #each_valueEnumerator

    Returns an Enumerator for enumerating the values in the cache.


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

#empty?Boolean

Returns true iff the cache is empty.


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

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

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


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

#keysArray<Object>

Returns all keys in the cache as an array


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

def_delegator :each_key, :to_a, :keys

#lengthInteger Also known as: size

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


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

#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]

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

#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"

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

#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]

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

#resize(cap) ⇒ nil

Alters the store's cap.


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

#valuesArray<Object>

Returns all values in the cache as an array


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

def_delegator :each_value, :to_a, :values