Class: Farce::TreeMap

Inherits:
Abstract::TreeMap show all
Includes:
Shareable::Delegated
Defined in:
lib/farce/tree_map.rb

Overview

A Ractor-shareable map that keeps entries sorted by key. Transfer modes apply only to values. Keys are stored directly, except that mutable strings become immutable. Values stored through this map's mode manager are automatically unwrapped.

Examples:

Keeping copied values in key order

map = Farce::TreeMap.new(mode: :copy)
map[2] = ["draft"]
map[1] = ["published"]

map.values # => [["published"], ["draft"]]

Instance Method Summary collapse

Methods included from Shareable

#ractor_shareable?

Methods inherited from Abstract::TreeMap

#[], #[]=, #clear, #compare_keys_by_identity?, #compare_values_by_identity?, #delete, #each, #each_key, #each_value, #empty?, #fetch, #first_key, #getkey, #key?, #keys, #last_key, #length, #pop, #shareable_keys?, #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, #shareable_keys?, #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, normalize_keys: nil, **keyword_entries) ⇒ TreeMap

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 for the map.

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

    The default value transfer mode.



23
24
25
26
27
28
29
30
 
# File 'lib/farce/tree_map.rb', line 23

def initialize(entries = nil, mode: :copy, normalize_keys: nil, **keyword_entries)
  unless keyword_entries.empty?
    raise ArgumentError, "entries given as both positional and keyword arguments" unless entries.nil?
    entries = keyword_entries
  end
  @manager = marshal_mode_manager(mode)
  super(entries, normalize_keys:)
end

Instance Method Details

#mode ⇒ Symbol

The default transfer mode for values.

Returns:

  • (Symbol) 


34
 
# File 'lib/farce/tree_map.rb', line 34

def mode = @manager.mode

#shareable_values? ⇒ true

Values are stored in Ractor-shareable representations.

Returns:

  • (true) 


38
 
# File 'lib/farce/tree_map.rb', line 38

def shareable_values? = true