Class: Farce::LRUMap

Inherits:
Abstract::LRUMap show all
Includes:
Shareable::Delegated
Defined in:
lib/farce/lru_map.rb

Overview

A Ractor-shareable bounded map that evicts the least recently used entry. Transfer modes apply to values. Equality-mode mutable string keys become immutable. Individual reads and writes update recency. Iteration and key observation do not.

Examples:

Keeping copied values in a small cache

cache = Farce::LRUMap.new(max_size: 2, mode: :copy)

cache[:first]  = [1]
cache[:second] = [2]
cache[:first] # makes sure :first was accessed more recently than :second
cache[:third]  = [3]

cache.key?(:second) # => false

Instance Method Summary collapse

Methods included from Shareable

#ractor_shareable?

Methods inherited from Abstract::BoundedMap

#[], #[]=, #clear, #compare_keys_by_identity?, #compare_values_by_identity?, #delete, #each, #each_key, #each_value, #fetch, #getkey, #key?, #keys, #max_size, #max_size=, #prune, #shift, #size, #store_if_absent, #values

Methods included from Abstract::DuplicableMap

#compact, #compact_blank, #deep_dup, #duplicable?, #except, #flatten, #invert, #merge, #reject, #reverse_merge, #select, #slice, #stringify_keys, #symbolize_keys, #to_proc, #transform_keys, #transform_values, #with_indifferent_access

Methods inherited from Abstract::Map

#[], #[]=, #as_extended_json, #as_json, #assert_valid_keys, #assoc, #bson_type, #clear, #compare_by_identity?, #compare_keys_by_identity?, #compare_values_by_identity?, #deconstruct_keys, #delete, #dig, #each, #each_key, #each_pair, #each_value, #empty?, #fetch, #fetch_values, #getkey, #has_key?, #key, #key?, #keys, #length, #rassoc, #size, #store, #store_if_absent, #to_a, #to_bson, #to_bson_normalized_value, #to_cbor, #to_h, #to_hash, #to_json, #to_msgpack, #to_query, #to_s, #value?, #values_at, #weak_keys?, #weak_values?

Constructor Details

#initialize(entries = nil, mode: :copy) ⇒ LRUMap

Valid modes are:

  • :copy - The value will be copied between Ractors. This is the default mode.
  • :make_shareable - The value will be made Ractor-shareable using Ractor.make_shareable.
  • :move - The value will be moved between Ractors. This saves memory compared to copying, and supports values that can't be copied but moved (like IO objects). However, the value will no longer be accessible on the Ractor that pushed it.
  • :mutable - A Mutable instance will be created for the value. This isn't done recursively and thus will fail for nested unshareable values.
  • :local - The value will be kept local to the Ractor that pushed it. Another ractor trying to receive it will get an error. Useful for usage contained within a single Ractor.
  • :proxy - The value will be wrapped in a Farce::Proxy that executes calls in the original Ractor.
  • :raise - An error will be raised if the value is not Ractor-shareable. Useful for enforcing shareability.
  • :dedup - The value will be deduplicated using Farce.dedup, then made Ractor-shareable. This may update and freeze the original. Already-shareable values pass through unchanged.
  • :shareable_copy - The value will be copied and the copy will be made Ractor-shareable.

Parameters:

  • entries (Hash, Array<Array(BasicObject, BasicObject)>, Abstract::Map, #each, nil) (defaults to: nil) —

    Optional initial entries. Entries are stored sequentially and may be evicted.

  • mode (Symbol) (defaults to: :copy) —

    The default value transfer mode.



26
27
28
29
 
# File 'lib/farce/lru_map.rb', line 26

def initialize(entries = nil, mode: :copy, **)
  @manager = marshal_mode_manager(mode)
  super(entries, **)
end

Instance Method Details

#mode ⇒ Symbol

The default transfer mode for values.

Returns:

  • (Symbol) 


33
 
# File 'lib/farce/lru_map.rb', line 33

def mode = @manager.mode

#shareable_keys? ⇒ true

Keys must be shareable, except equality-mode strings that can be snapshotted.

Returns:

  • (true) 


37
 
# File 'lib/farce/lru_map.rb', line 37

def shareable_keys? = true

#shareable_values? ⇒ true

Values are stored in Ractor-shareable representations.

Returns:

  • (true) 


41
 
# File 'lib/farce/lru_map.rb', line 41

def shareable_values? = true