RubyGems - farce - Versions diffs - 0.0.1.alpha2-java - Mend

farce 0.0.1.alpha2-java

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (376) hide show

checksums.yaml +7 -0
data/CODE_OF_CONDUCT.md +26 -0
data/CONTRIBUTING.md +71 -0
data/MIT-LICENSE +20 -0
data/README.md +1524 -0
data/SECURITY.md +10 -0
data/docs/benchmarks.md +185 -0
data/docs/gems/dry-types.md +290 -0
data/docs/gems/msgpack.md +70 -0
data/docs/gems/ractor-shim.md +63 -0
data/docs/modes.md +628 -0
data/docs/scopes.md +649 -0
data/docs/variants.md +346 -0
data/lib/farce/_yard/internal.rb +13 -0
data/lib/farce/_yard/macros.rb +61 -0
data/lib/farce/_yard/ractor.rb +46 -0
data/lib/farce/abstract/atom.rb +186 -0
data/lib/farce/abstract/bounded_map.rb +232 -0
data/lib/farce/abstract/collection.rb +151 -0
data/lib/farce/abstract/concurrent_map.rb +381 -0
data/lib/farce/abstract/counter.rb +193 -0
data/lib/farce/abstract/duplicable_map.rb +229 -0
data/lib/farce/abstract/exchanger.rb +26 -0
data/lib/farce/abstract/flag.rb +71 -0
data/lib/farce/abstract/lazy.rb +115 -0
data/lib/farce/abstract/lease.rb +104 -0
data/lib/farce/abstract/lease_map.rb +261 -0
data/lib/farce/abstract/lease_pool.rb +91 -0
data/lib/farce/abstract/lfu_map.rb +20 -0
data/lib/farce/abstract/lru_map.rb +25 -0
data/lib/farce/abstract/map.rb +345 -0
data/lib/farce/abstract/molecule.rb +245 -0
data/lib/farce/abstract/port.rb +74 -0
data/lib/farce/abstract/priority_queue.rb +117 -0
data/lib/farce/abstract/queue.rb +269 -0
data/lib/farce/abstract/scheduler.rb +111 -0
data/lib/farce/abstract/set.rb +910 -0
data/lib/farce/abstract/sorted_set.rb +172 -0
data/lib/farce/abstract/timer_queue.rb +136 -0
data/lib/farce/abstract/tree_map.rb +269 -0
data/lib/farce/abstract/value.rb +68 -0
data/lib/farce/abstract/vector.rb +1126 -0
data/lib/farce/abstract/weak_atom.rb +32 -0
data/lib/farce/abstract/weak_key_map.rb +12 -0
data/lib/farce/abstract/weak_map.rb +13 -0
data/lib/farce/abstract/weak_set.rb +12 -0
data/lib/farce/abstract/weak_value_map.rb +12 -0
data/lib/farce/abstract.rb +17 -0
data/lib/farce/atom.rb +293 -0
data/lib/farce/class_mirror.rb +87 -0
data/lib/farce/clock.rb +121 -0
data/lib/farce/config.rb +229 -0
data/lib/farce/counter.rb +71 -0
data/lib/farce/deduper.rb +122 -0
data/lib/farce/engine/jruby/bounded_map.rb +314 -0
data/lib/farce/engine/jruby/fiber_scheduler.jar +0 -0
data/lib/farce/engine/jruby/fiber_scheduler.rb +119 -0
data/lib/farce/engine/jruby/lease_waiting.rb +19 -0
data/lib/farce/engine/jruby/map.rb +505 -0
data/lib/farce/engine/jruby/mutable_numeric_copy.rb +42 -0
data/lib/farce/engine/jruby/signal.rb +147 -0
data/lib/farce/engine/jruby.rb +63 -0
data/lib/farce/engine/jvm/concurrent_weak_registry.rb +55 -0
data/lib/farce/engine/jvm/counter.rb +102 -0
data/lib/farce/engine/jvm/extension.rb +32 -0
data/lib/farce/engine/jvm/farce.jar +0 -0
data/lib/farce/engine/jvm/flag.rb +79 -0
data/lib/farce/engine/jvm/priority_queue.rb +217 -0
data/lib/farce/engine/jvm/tree_map.rb +350 -0
data/lib/farce/engine/jvm/types.rb +180 -0
data/lib/farce/engine/jvm.rb +19 -0
data/lib/farce/engine/ruby/3.4/fiber_scheduler.rb +20 -0
data/lib/farce/engine/ruby/3.4/port.rb +186 -0
data/lib/farce/engine/ruby/3.4/ractor_methods.rb +26 -0
data/lib/farce/engine/ruby/3.4/ractor_selector.rb +92 -0
data/lib/farce/engine/ruby/3.4/vault.rb +56 -0
data/lib/farce/engine/ruby/4.0/port.rb +19 -0
data/lib/farce/engine/ruby/4.0/ractor_methods.rb +20 -0
data/lib/farce/engine/ruby/4.0/ractor_selector.rb +108 -0
data/lib/farce/engine/ruby/4.0/vault.rb +74 -0
data/lib/farce/engine/ruby/4.1/port.rb +21 -0
data/lib/farce/engine/ruby/4.1/ractor_methods.rb +22 -0
data/lib/farce/engine/ruby/4.1/ractor_selector.rb +25 -0
data/lib/farce/engine/ruby/4.1/vault.rb +5 -0
data/lib/farce/engine/ruby/fiber_scheduler.rb +32 -0
data/lib/farce/engine/ruby/key_lock_map.rb +28 -0
data/lib/farce/engine/ruby/shared/lease.rb +26 -0
data/lib/farce/engine/ruby/shared/lease_pool.rb +24 -0
data/lib/farce/engine/ruby/shared/main_scheduler.rb +9 -0
data/lib/farce/engine/ruby/shared/parallel_scheduler.rb +9 -0
data/lib/farce/engine/ruby/shared/proxy_owner.rb +31 -0
data/lib/farce/engine/ruby/shared/ractor_methods.rb +34 -0
data/lib/farce/engine/ruby/shared/ractor_selector.rb +328 -0
data/lib/farce/engine/ruby/shared/strict_map.rb +13 -0
data/lib/farce/engine/ruby/shared/unshared_vector.rb +14 -0
data/lib/farce/engine/ruby/shared/vault.rb +144 -0
data/lib/farce/engine/ruby/shared/vault_weak_map.rb +336 -0
data/lib/farce/engine/ruby/shared/weak_atom.rb +54 -0
data/lib/farce/engine/ruby/shared/weak_map.rb +413 -0
data/lib/farce/engine/ruby.rb +130 -0
data/lib/farce/engine/shared/atom.rb +10 -0
data/lib/farce/engine/shared/exchanger.rb +130 -0
data/lib/farce/engine/shared/identity_key.rb +22 -0
data/lib/farce/engine/shared/lease.rb +10 -0
data/lib/farce/engine/shared/lease_pool.rb +10 -0
data/lib/farce/engine/shared/main_scheduler.rb +20 -0
data/lib/farce/engine/shared/map_key_coordination.rb +226 -0
data/lib/farce/engine/shared/parallel_scheduler.rb +9 -0
data/lib/farce/engine/shared/port.rb +44 -0
data/lib/farce/engine/shared/portable_bounded_map.rb +619 -0
data/lib/farce/engine/shared/proxy_owner.rb +43 -0
data/lib/farce/engine/shared/queue.rb +233 -0
data/lib/farce/engine/shared/ractor_methods.rb +73 -0
data/lib/farce/engine/shared/rebindable.rb +15 -0
data/lib/farce/engine/shared/strict_atom.rb +73 -0
data/lib/farce/engine/shared/strict_map.rb +117 -0
data/lib/farce/engine/shared/strict_queue_values.rb +27 -0
data/lib/farce/engine/shared/strict_tree_map.rb +56 -0
data/lib/farce/engine/shared/transaction_map_backend.rb +20 -0
data/lib/farce/engine/shared/trie.rb +317 -0
data/lib/farce/engine/shared/trie_builder.rb +199 -0
data/lib/farce/engine/shared/unshareable.rb +14 -0
data/lib/farce/engine/shared/unshared_atom.rb +256 -0
data/lib/farce/engine/shared/unshared_priority_queue.rb +9 -0
data/lib/farce/engine/shared/unshared_queue.rb +18 -0
data/lib/farce/engine/shared/unshared_signal.rb +21 -0
data/lib/farce/engine/shared/unshared_vector.rb +377 -0
data/lib/farce/engine/shared/unshared_weak_atom.rb +30 -0
data/lib/farce/engine/shared/unshared_weak_map.rb +445 -0
data/lib/farce/engine/shared/vault.rb +31 -0
data/lib/farce/engine/shared/vector.rb +83 -0
data/lib/farce/engine/shared/weak_atom/base.rb +189 -0
data/lib/farce/engine/shared/weak_atom.rb +20 -0
data/lib/farce/engine/shared/weak_map/cell.rb +99 -0
data/lib/farce/engine/shared/weak_map/index.rb +249 -0
data/lib/farce/engine/shared/weak_map/lock.rb +80 -0
data/lib/farce/engine/shared/weak_map/reference.rb +33 -0
data/lib/farce/engine/shared.rb +63 -0
data/lib/farce/engine/truffleruby/fiber_scheduler.rb +13 -0
data/lib/farce/engine/truffleruby/lock.rb +121 -0
data/lib/farce/engine/truffleruby/map.rb +656 -0
data/lib/farce/engine/truffleruby/native/counter.rb +105 -0
data/lib/farce/engine/truffleruby/native/flag.rb +77 -0
data/lib/farce/engine/truffleruby/native/ordered_array_support.rb +67 -0
data/lib/farce/engine/truffleruby/native/priority_queue.rb +388 -0
data/lib/farce/engine/truffleruby/native/tree_map.rb +51 -0
data/lib/farce/engine/truffleruby/native/unsafe_tree_map.rb +350 -0
data/lib/farce/engine/truffleruby/signal.rb +77 -0
data/lib/farce/engine/truffleruby.rb +148 -0
data/lib/farce/envelope.rb +335 -0
data/lib/farce/error.rb +35 -0
data/lib/farce/exchanger.rb +41 -0
data/lib/farce/flag.rb +27 -0
data/lib/farce/integrations/active_support/blank.rb +68 -0
data/lib/farce/integrations/active_support/clock.rb +17 -0
data/lib/farce/integrations/active_support/duplicable.rb +78 -0
data/lib/farce/integrations/active_support/map.rb +175 -0
data/lib/farce/integrations/active_support/set.rb +60 -0
data/lib/farce/integrations/active_support/value_serialization.rb +17 -0
data/lib/farce/integrations/active_support/vector.rb +231 -0
data/lib/farce/integrations/active_support.rb +9 -0
data/lib/farce/integrations/activesupport.rb +5 -0
data/lib/farce/integrations/bson.rb +108 -0
data/lib/farce/integrations/cbor.rb +51 -0
data/lib/farce/integrations/concurrent.rb +112 -0
data/lib/farce/integrations/dry-types.rb +5 -0
data/lib/farce/integrations/dry_types.rb +694 -0
data/lib/farce/integrations/json.rb +7 -0
data/lib/farce/integrations/msgpack.rb +112 -0
data/lib/farce/integrations/oj.rb +69 -0
data/lib/farce/integrations/psych.rb +191 -0
data/lib/farce/integrations/ractor-sharing.rb +5 -0
data/lib/farce/integrations/ractor-tmvar.rb +5 -0
data/lib/farce/integrations/ractor_sharing.rb +172 -0
data/lib/farce/integrations/ractor_tmvar.rb +64 -0
data/lib/farce/integrations/shared/to_json.rb +42 -0
data/lib/farce/integrations/sorted_set.rb +11 -0
data/lib/farce/integrations/weakref.rb +38 -0
data/lib/farce/integrations/yajl.rb +10 -0
data/lib/farce/integrations.rb +156 -0
data/lib/farce/internal/_frozen_config.rb +11 -0
data/lib/farce/internal/autoloads.rb +47 -0
data/lib/farce/internal/blocking_priority_queue.rb +122 -0
data/lib/farce/internal/converter.rb +106 -0
data/lib/farce/internal/copyable.rb +31 -0
data/lib/farce/internal/delegation.rb +20 -0
data/lib/farce/internal/external_transaction.rb +59 -0
data/lib/farce/internal/fake_ractor.rb +179 -0
data/lib/farce/internal/freeze.rb +118 -0
data/lib/farce/internal/inspect.rb +157 -0
data/lib/farce/internal/key_lock_map.rb +29 -0
data/lib/farce/internal/key_normalizer.rb +289 -0
data/lib/farce/internal/lease_initialization.rb +115 -0
data/lib/farce/internal/lease_map.rb +441 -0
data/lib/farce/internal/lease_pool_state.rb +228 -0
data/lib/farce/internal/lease_state.rb +342 -0
data/lib/farce/internal/lease_waiting.rb +13 -0
data/lib/farce/internal/managed_queue.rb +26 -0
data/lib/farce/internal/map_value_modes.rb +227 -0
data/lib/farce/internal/marshal_support.rb +227 -0
data/lib/farce/internal/mixin.rb +20 -0
data/lib/farce/internal/mutable_ordered_key_lock_map.rb +63 -0
data/lib/farce/internal/noncopyable.rb +17 -0
data/lib/farce/internal/ordered_key_lock_map.rb +69 -0
data/lib/farce/internal/pool_supervisor.rb +41 -0
data/lib/farce/internal/pool_worker.rb +61 -0
data/lib/farce/internal/portable_transaction/reservation_entry.rb +29 -0
data/lib/farce/internal/portable_transaction/strong_map_entry.rb +137 -0
data/lib/farce/internal/portable_transaction/strong_map_size_entry.rb +44 -0
data/lib/farce/internal/portable_transaction/tree_entry.rb +64 -0
data/lib/farce/internal/portable_transaction.rb +164 -0
data/lib/farce/internal/proxy_owner_notifications.rb +29 -0
data/lib/farce/internal/reservation_waiting.rb +24 -0
data/lib/farce/internal/scheduled_task.rb +48 -0
data/lib/farce/internal/scheduler_io.rb +171 -0
data/lib/farce/internal/scheduler_lifecycle.rb +314 -0
data/lib/farce/internal/select_scheduler.rb +235 -0
data/lib/farce/internal/storage.rb +162 -0
data/lib/farce/internal/strict_lease.rb +30 -0
data/lib/farce/internal/strict_lease_map.rb +20 -0
data/lib/farce/internal/strict_lease_pool.rb +29 -0
data/lib/farce/internal/thread_pool.rb +166 -0
data/lib/farce/internal/transaction_conflict.rb +9 -0
data/lib/farce/internal/transaction_freeze_guard.rb +30 -0
data/lib/farce/internal/transaction_map_snapshot.rb +123 -0
data/lib/farce/internal/undefined.rb +22 -0
data/lib/farce/internal/unshared_lease.rb +29 -0
data/lib/farce/internal/unshared_lease_pool.rb +34 -0
data/lib/farce/internal/unshared_queue_waiting.rb +28 -0
data/lib/farce/internal/value_serialization.rb +13 -0
data/lib/farce/internal/weak_map_value_modes.rb +58 -0
data/lib/farce/internal/weak_mode_manager.rb +26 -0
data/lib/farce/internal.rb +129 -0
data/lib/farce/lazy.rb +100 -0
data/lib/farce/lazy_ref.rb +40 -0
data/lib/farce/lease.rb +28 -0
data/lib/farce/lease_map.rb +34 -0
data/lib/farce/lease_pool.rb +29 -0
data/lib/farce/lfu_map.rb +53 -0
data/lib/farce/local/atom.rb +23 -0
data/lib/farce/local/counter.rb +88 -0
data/lib/farce/local/flag.rb +65 -0
data/lib/farce/local/lazy.rb +38 -0
data/lib/farce/local/lazy_ref.rb +36 -0
data/lib/farce/local/lease.rb +77 -0
data/lib/farce/local/lease_map.rb +80 -0
data/lib/farce/local/lease_pool.rb +38 -0
data/lib/farce/local/lfu_map.rb +55 -0
data/lib/farce/local/lru_map.rb +62 -0
data/lib/farce/local/map.rb +47 -0
data/lib/farce/local/molecule.rb +45 -0
data/lib/farce/local/priority_queue.rb +53 -0
data/lib/farce/local/queue.rb +32 -0
data/lib/farce/local/scoped.rb +166 -0
data/lib/farce/local/set.rb +18 -0
data/lib/farce/local/sorted_set.rb +50 -0
data/lib/farce/local/timer_queue.rb +41 -0
data/lib/farce/local/tree_map.rb +47 -0
data/lib/farce/local/vector.rb +30 -0
data/lib/farce/local/weak_atom.rb +23 -0
data/lib/farce/local/weak_key_map.rb +39 -0
data/lib/farce/local/weak_map.rb +39 -0
data/lib/farce/local/weak_set.rb +18 -0
data/lib/farce/local/weak_value_map.rb +39 -0
data/lib/farce/local.rb +35 -0
data/lib/farce/lock.rb +54 -0
data/lib/farce/lru_map.rb +63 -0
data/lib/farce/map.rb +58 -0
data/lib/farce/mode_manager.rb +142 -0
data/lib/farce/molecule.rb +60 -0
data/lib/farce/mutable.rb +171 -0
data/lib/farce/pool.rb +332 -0
data/lib/farce/port.rb +134 -0
data/lib/farce/priority_queue.rb +70 -0
data/lib/farce/proxy/register.rb +101 -0
data/lib/farce/proxy/supervisor.rb +137 -0
data/lib/farce/proxy/wrapper.rb +49 -0
data/lib/farce/proxy.rb +291 -0
data/lib/farce/queue.rb +60 -0
data/lib/farce/ractor.rb +269 -0
data/lib/farce/read_write_lock.rb +256 -0
data/lib/farce/reference.rb +158 -0
data/lib/farce/resolv/dns.rb +42 -0
data/lib/farce/resolv.rb +85 -0
data/lib/farce/scheduler.rb +536 -0
data/lib/farce/set.rb +39 -0
data/lib/farce/shareable.rb +150 -0
data/lib/farce/signal.rb +97 -0
data/lib/farce/sorted_set.rb +36 -0
data/lib/farce/strict/atom.rb +34 -0
data/lib/farce/strict/counter.rb +10 -0
data/lib/farce/strict/exchanger.rb +25 -0
data/lib/farce/strict/flag.rb +10 -0
data/lib/farce/strict/lazy.rb +26 -0
data/lib/farce/strict/lazy_ref.rb +26 -0
data/lib/farce/strict/lease.rb +27 -0
data/lib/farce/strict/lease_map.rb +33 -0
data/lib/farce/strict/lease_pool.rb +28 -0
data/lib/farce/strict/lfu_map.rb +27 -0
data/lib/farce/strict/lru_map.rb +28 -0
data/lib/farce/strict/map.rb +54 -0
data/lib/farce/strict/molecule.rb +16 -0
data/lib/farce/strict/port.rb +40 -0
data/lib/farce/strict/priority_queue.rb +20 -0
data/lib/farce/strict/queue.rb +17 -0
data/lib/farce/strict/set.rb +14 -0
data/lib/farce/strict/sorted_set.rb +19 -0
data/lib/farce/strict/timer_queue.rb +13 -0
data/lib/farce/strict/tree_map.rb +27 -0
data/lib/farce/strict/vector.rb +24 -0
data/lib/farce/strict/weak_atom.rb +31 -0
data/lib/farce/strict/weak_key_map.rb +49 -0
data/lib/farce/strict/weak_map.rb +49 -0
data/lib/farce/strict/weak_set.rb +14 -0
data/lib/farce/strict/weak_value_map.rb +48 -0
data/lib/farce/strict.rb +28 -0
data/lib/farce/system.rb +40 -0
data/lib/farce/thread_scheduler.rb +70 -0
data/lib/farce/timer_queue.rb +66 -0
data/lib/farce/transaction/atom.rb +73 -0
data/lib/farce/transaction/map.rb +25 -0
data/lib/farce/transaction/map_operations.rb +143 -0
data/lib/farce/transaction/molecule.rb +90 -0
data/lib/farce/transaction/mutable.rb +61 -0
data/lib/farce/transaction/set.rb +17 -0
data/lib/farce/transaction/set_operations.rb +48 -0
data/lib/farce/transaction/sorted_set.rb +18 -0
data/lib/farce/transaction/tree_map.rb +78 -0
data/lib/farce/transaction/vector.rb +139 -0
data/lib/farce/transaction/wrapper.rb +202 -0
data/lib/farce/transaction.rb +343 -0
data/lib/farce/tree_map.rb +56 -0
data/lib/farce/unsafe/lfu_map.rb +36 -0
data/lib/farce/unsafe/lru_map.rb +36 -0
data/lib/farce/unsafe/tree_map.rb +21 -0
data/lib/farce/unsafe.rb +29 -0
data/lib/farce/unshareable.rb +67 -0
data/lib/farce/unshared/atom.rb +24 -0
data/lib/farce/unshared/counter.rb +10 -0
data/lib/farce/unshared/flag.rb +10 -0
data/lib/farce/unshared/lazy.rb +38 -0
data/lib/farce/unshared/lazy_ref.rb +26 -0
data/lib/farce/unshared/lease.rb +27 -0
data/lib/farce/unshared/lease_map.rb +26 -0
data/lib/farce/unshared/lease_pool.rb +25 -0
data/lib/farce/unshared/lfu_map.rb +20 -0
data/lib/farce/unshared/lru_map.rb +20 -0
data/lib/farce/unshared/map.rb +49 -0
data/lib/farce/unshared/molecule.rb +16 -0
data/lib/farce/unshared/priority_queue.rb +16 -0
data/lib/farce/unshared/queue.rb +27 -0
data/lib/farce/unshared/set.rb +14 -0
data/lib/farce/unshared/sorted_set.rb +28 -0
data/lib/farce/unshared/timer_queue.rb +16 -0
data/lib/farce/unshared/tree_map.rb +21 -0
data/lib/farce/unshared/vector.rb +19 -0
data/lib/farce/unshared/weak_atom.rb +31 -0
data/lib/farce/unshared/weak_key_map.rb +44 -0
data/lib/farce/unshared/weak_map.rb +44 -0
data/lib/farce/unshared/weak_set.rb +14 -0
data/lib/farce/unshared/weak_value_map.rb +43 -0
data/lib/farce/unshared.rb +28 -0
data/lib/farce/vector.rb +228 -0
data/lib/farce/version.rb +8 -0
data/lib/farce/walker/definitions.rb +186 -0
data/lib/farce/walker/modification.rb +355 -0
data/lib/farce/walker.rb +319 -0
data/lib/farce/weak_atom.rb +121 -0
data/lib/farce/weak_key_map.rb +31 -0
data/lib/farce/weak_map.rb +33 -0
data/lib/farce/weak_ref.rb +67 -0
data/lib/farce/weak_set.rb +82 -0
data/lib/farce/weak_value.rb +195 -0
data/lib/farce/weak_value_map.rb +32 -0
data/lib/farce.rb +519 -0
metadata +420 -0

data/docs/variants.md ADDED Viewed

@@ -0,0 +1,346 @@
+<!--
+# @title Variants
+-->
+# Variants
+Most Farce classes implement a set of variants as separate subclasses within module namespaces.
+These namespaces and variants are:
+* **Farce**: Data containers that support both shareable and unshareable content. Unshareable content is usually handled by implementing [mode support](modes.md). Keep in mind that this is also the top level namespace for Farce in general, so it contains other classes and modules not implementing variants (including the variant namespaces themselves).
+* **Farce::Strict**: Variants that enforce strict sharing rules. Unshareable content will be rejected.
+* **Farce::Local**: Variants that hold concrete, independent data for each [scope](scopes.md) (i.e., one copy per ractor, thread, etc). As no scope stretches across multiple ractors, these may contain unshareable content without issue.
+* **Farce::Unshared**: Variants that explicitly allow unshareable content. These cannot be shared across multiple ractors.
+* **Farce::Unsafe**: Variants that aren't shareable but moreover aren't guaranteed to be thread-safe either. They only exist if they give a significant performance or usability benefit despite these limitations.
+* **Farce::Transaction**: Variants generated by transactions.
+You can choose the variant based on your needs:
+```ruby
+global_map = Farce::Map.new
+local_map  = Farce::Local::Map.new(scope: :thread)
+```
+None of the namespaces define any instance methods, so they are safe to include:
+```ruby
+class MyClass
+  include Farce::Strict
+  @register = Map.new
+  @cache    = LRUMap.new
+end
+```
+## Classes implementing Variants
+<table>
+  <thead>
+    <tr>
+      <th></th>
+      <th width="120" align="center" style="text-align: center">Farce</th>
+      <th width="120" align="center" style="text-align: center">Strict</th>
+      <th width="120" align="center" style="text-align: center">Local</th>
+      <th width="120" align="center" style="text-align: center">Unshared</th>
+      <th width="120" align="center" style="text-align: center">Unsafe</th>
+      <th width="120" align="center" style="text-align: center">Transaction</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><tt>Atom</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">✅</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>Counter</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>Exchanger</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">➖</td> <!-- Local -->
+      <td align="center" style="text-align: center">➖</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">➖</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>Flag</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>Lazy</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>LazyRef</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>Lease</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>LeaseMap</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>LeasePool</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>LFUMap</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>LRUMap</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>Molecule</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">✅</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>Map</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">✅</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>Mutable</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">➖</td> <!-- Strict -->
+      <td align="center" style="text-align: center">➖</td> <!-- Local -->
+      <td align="center" style="text-align: center">➖</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">➖</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">✅</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>Port</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">➖</td> <!-- Local -->
+      <td align="center" style="text-align: center">➖</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">➖</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>PriorityQueue</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>Queue</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>Set</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">✅</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>SortedSet</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">✅</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>TimerQueue</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>TreeMap</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">✅</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>Vector</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">✅</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>WeakAtom</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>WeakKeyMap</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>WeakMap</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>WeakSet</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+    <tr>
+      <td><tt>WeakValueMap</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
+  </tbody>
+</table>
+Legend:
+* ✅ Defined
+* ➖ Not defined
+* 🔗 Alias for another variant
+## Classes without Variants
+When using the variant namespaces interchangeably, keep in mind that some classes do not come with variants.
+This is obvious for classes that aren't data containers, like `Signal` or `Lock`, but also include classes like `Envelope` and `Scheduler`, which support modes, and `WeakValue` and `WeakRef`, which will choose (and switch) between the correct `WeakAtom` variants automatically.
+## Abstract Classes and Modules
+Classes with variants will typically have at least one abstract class or module that they implement.
+This is helpful for type checking and as a possible extension point, while doing a better job at substitution.
+For example, `Farce::Map` subclasses should all implement mode support, but the same cannot be said for all `Farce::Abstract::Map` subclasses.
+This makes type checking easy:
+```ruby
+def self.increment_counter(counter)
+  case counter
+  when Farce::Abstract::Counter then counter.increment
+  when Ratomic::Counter         then counter.increment(1) # required argument
+  else raise "Unsupported counter type"
+  end
+end
+counter = Farce::Counter.new
+increment_counter(counter)
+counter = Farce::Local::Counter.new(scope: :fiber)
+increment_counter(counter)
+```
+Abstract classes may in turn have abstract subclasses to group functionality. For instance, all `PriorityQueue` variants inherit from `Farce::Abstract::PriorityQueue`, which in turn is a subclass of `Farce::Abstract::Queue`.
+A noticeably more complex abstract hierarchy exists for maps:
+* `Farce::Abstract::Map`: Superclass for all map variants. Contains the almost complete set of Hash-compatible methods, as well as some additional methods like `store_if_absent`.
+  * `Farce::Abstract::ConcurrentMap`: Superclass for maps with an extended concurrency API, including `Farce::Map` and its variants.
+    * `Farce::Abstract::WeakMap`: Superclass for all `WeakMap` variants.
+    * `Farce::Abstract::WeakKeyMap`: Superclass for all `WeakKeyMap` variants.
+    * `Farce::Abstract::WeakValueMap`: Superclass for all `WeakValueMap` variants.
+  * `Farce::Abstract::BoundedMap`: Superclass for all map variants with an enforced size limit. All current variants enforce this limit via eviction, but a subclass rejecting writes could be a valid implementation.
+    * `Farce::Abstract::LFUMap`: Superclass for all Least Frequently Used (LFU) map variants.
+    * `Farce::Abstract::LRUMap`: Superclass for all Least Recently Used (LRU) map variants.
+  * `Farce::Abstract::LeaseMap`: Superclass for all `LeaseMap` variants.
+  * `Farce::Abstract::TreeMap`: Superclass for all `TreeMap` variants.

data/lib/farce/_yard/internal.rb ADDED Viewed

@@ -0,0 +1,13 @@
+return if true
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # @!visibility private
+    module Autoloads end
+    # @!visibility private
+    module RactorMethods end
+    # @!visibility private
+    class Atom end
+  end
+end

data/lib/farce/_yard/macros.rb ADDED Viewed

@@ -0,0 +1,61 @@
+# @!macro unsafe
+#   @note
+#     Instances of this class are **not thread-safe** and should not be shared concurrently.
+#     This does not just apply to Ractors, but also Threads and possibly Fibers.
+#
+#     Only use them if you are absolutely certain of this and they do not leave a tightly controlled scope.
+#     They can provide a memory or performance advantage over their thread-safe counterparts, so they
+#     might be useful for hot path optimizations.
+#
+#     Concurrent access, especially modifications, may corrupt the internal state of the object.
+# @!macro modes
+#   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 {Farce::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.
+# @!macro scopes
+#   Valid scopes are:
+#   * `:ractor` - The value is shared by all threads within the same Ractor.
+#   * `:thread_group` - The value is shared by all threads within the same thread group.
+#   * `:thread` - The value is shared by all fibers within the same thread.
+#   * `:fiber_storage` - The value is shared by all fibers using the same storage.
+#     Unless explicitly specified, storage is inherited from the parent fiber for blocking fibers,
+#     but not for non-blocking fibers (such as those created by {Scheduler#schedule}).
+#   * `:fiber` - Each fiber has its own independent value.
+# @!macro key_normalization
+#   @param normalize_keys [Symbol, Proc, Hash, Farce::Abstract::Map, nil]
+#     Converts incoming keys to their canonical stored form:
+#     * If a `Symbol` is provided, it will be used as a method name to call on each key.
+#     * If a `Proc` is provided, it will be called with each key and should return the normalized key.
+#     * If a `Hash` or {Farce::Abstract::Map Map} is provided, it will be used to look up the normalized key for each incoming key.
+# @!macro map_initialization
+#   Create a map with optional initial entries.
+#   @param initial_mapping [Hash, Farce::Abstract::Map, #each, nil]
+#     The entries to store initially. Each iteration must yield a key-value pair.
+#     Nil creates an empty map.
+#   @!macro key_normalization
+#   @param compare_by_identity [Boolean]
+#     The default identity-comparison setting for keys and values. Defaults to false.
+#   @param compare_keys_by_identity [Boolean]
+#     Whether keys use object identity instead of `hash` and `eql?`.
+#     Defaults to `compare_by_identity`.
+#   @param compare_values_by_identity [Boolean]
+#     Whether values use object identity instead of `==`.
+#     Defaults to `compare_by_identity`.
+# @!macro active_support
+#   @note This methods is only available if ActiveSupport has been loaded.

data/lib/farce/_yard/ractor.rb ADDED Viewed

@@ -0,0 +1,46 @@
+return if true
+# @!visibility private
+class Ractor
+end
+module Farce
+  module Ractor
+    # Either `Ractor::Port` or a shim for it. It is recommended to use {Farce::Port Farce::Port} instead,
+    # which will always be a subclass of this class, but has added safety and functionality.
+    class Port
+      # Closes the port. Sending to a closed port is prohibited. Receiving is also prohibited if there are no
+      # messages in its message queue. Only the Ractor which created the port is allowed to close it.
+      # @return [void]
+      def close = super
+      # Checks it the port is closed.
+      # @return [Boolean] `true` if the port is closed, `false` otherwise.
+      # @see #close
+      def closed? = super
+      # @overload receive
+      #   Receives a message from the port.
+      #   @return [BasicObject] The received message.
+      # @overload receive(timeout: nil)
+      #   Receives a message from the port. Blocks until a message is available or the timeout is reached.
+      #   @note
+      #     Use {Farce::Port Farce::Port} instead to guarantee a timeout argument on all Ruby implementations.
+      #   @ruby CRuby 4.1+, JRuby, TruffleRuby
+      #   @param timeout [Numeric, nil] The timeout in seconds, or `nil` for no timeout.
+      #   @return [BasicObject, nil] The received message, or `nil` if the timeout has been reached.
+      #
+      # @return [BasicObject]
+      # @raise [Farce::Ractor::ClosedError] if the port is closed and there are no messages in the queue.
+      def receive = super
+      # Sends a message over the port.
+      # @param message [BasicObject] The message to send.
+      # @param move [Boolean] Whether to move the message to the Ractor if it isn't sharable.
+      # @return [self]
+      # @raise [Farce::Ractor::ClosedError] if the port is closed.
+      def send(message, move: false) = super
+      alias << send
+    end
+  end
+end

data/lib/farce/abstract/atom.rb ADDED Viewed

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+module Farce
+  module Abstract
+    # @abstract Common interface and behavior for atomic references.
+    #
+    # Concrete implementations decide how values are retained and transferred.
+    # A value may become `nil` without an explicit update when an implementation
+    # retains it weakly.
+    class Atom
+      include Internal::MarshalSupport::Atom
+      include Internal::Copyable
+      include Internal::Inspect
+      include Value
+      include Internal::ValueSerialization
+      # @api private
+      def transaction_wrapper(transaction) = Transaction::Atom.new(transaction, self, internal_atom)
+      # Whether comparisons use object identity instead of equality.
+      # @return [Boolean]
+      def compare_by_identity? = internal_atom.compare_by_identity?
+      # Return the current value without waiting for an update in progress.
+      # @return [BasicObject, nil] the current value
+      def value = internal_atom.value
+      # Store a new value.
+      # @param new_value [BasicObject, nil] the new value
+      # @return [BasicObject, nil] the new value
+      def value=(new_value)
+        store(new_value)
+      end
+      # Return the current value, waiting for any update in progress.
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield called when the timeout expires
+      # @return [BasicObject, nil] the current value or the fallback result
+      def get(timeout: nil, &) = internal_atom.get(timeout:, &)
+      # Store a new value, waiting for any update in progress.
+      # @param new_value [BasicObject, nil] the new value
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield called when the timeout expires
+      # @return [BasicObject, nil] the stored value or the fallback result
+      def store(new_value, timeout: nil, &) = internal_atom.store(new_value, timeout:, &)
+      # Replace the current value and return the previous value.
+      # @param new_value [BasicObject, nil] the new value
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield called when the timeout expires
+      # @return [BasicObject, nil] the previous value or the fallback result
+      def swap(new_value, timeout: nil, &) = internal_atom.swap(new_value, timeout:, &)
+      # Compute and store a value if the current value is nil.
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield computes the value to store when the current value is nil
+      # @yieldreturn [BasicObject, nil] the value to store
+      # @return [BasicObject, nil] the current or newly stored value, or nil when the timeout expires
+      def store_if_absent(timeout: nil, &) = internal_atom.store_if_absent(timeout:, &)
+      # Atomically replace the current value if it matches the expected value.
+      # @param expected [BasicObject, nil] the value to compare with the current value
+      # @param new_value [BasicObject, nil] the replacement value
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @return [Boolean] whether the value was replaced
+      def compare_and_set(expected, new_value, timeout: nil)
+        internal_atom.compare_and_set(expected, new_value, timeout:)
+      end
+      # Atomically replace the current value with the result of a block.
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield receives the current value and computes its replacement
+      # @yieldparam current [BasicObject, nil] the current value
+      # @yieldreturn [BasicObject, nil] the replacement value
+      # @return [BasicObject, nil] the replacement value, or nil when the timeout expires
+      def update(timeout: nil, &) = internal_atom.update(timeout:, &)
+      # Store an initial value if the current value is nil, otherwise replace it with the result of a block.
+      # @param initial_value [BasicObject, nil] the value to store when the current value is nil
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield receives a non-nil current value and computes its replacement
+      # @yieldparam current [BasicObject] the current value
+      # @yieldreturn [BasicObject, nil] the replacement value
+      # @return [BasicObject, nil] the replacement or initial value, or nil when the timeout expires
+      def upsert(initial_value, timeout: nil, &) = internal_atom.upsert(initial_value, timeout:, &)
+      # Wait until a block condition matches the current value.
+      # One timeout budget covers all checks and waits. The block is not interrupted.
+      # @yieldparam value [BasicObject, nil] the current value
+      # @yieldreturn [Boolean] whether the value matches
+      # @param timeout [Numeric, nil] the total seconds available
+      # @return [BasicObject, nil] the matching value, or nil on timeout
+      # @raise [LocalJumpError] if no block is given
+      def wait_until(timeout: nil, &) = Internal.wait_until(self, timeout:, &)
+      # Wait while the block returns a truthy value.
+      # @yieldparam value [BasicObject, nil] the current value
+      # @yieldreturn [BasicObject] a truthy value to keep waiting, or nil or false to stop
+      # @param timeout [Numeric, nil] the total seconds available
+      # @return [BasicObject, nil] the value when the condition becomes false, or nil on timeout
+      # @raise [LocalJumpError] if no block is given
+      def wait_while(timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        wait_until(timeout:) { |value| !yield(value) }
+      end
+      # Wait while `object === value` is true.
+      # @param object [#===] the pattern to stop matching
+      # @param timeout [Numeric, nil] the total seconds available
+      # @return [BasicObject, nil] the first nonmatching value, or nil on timeout
+      def wait_while_match(object, timeout: nil)
+        wait_while(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
+      end
+      # (see #wait_until_changed)
+      def wait_while_value(...) = wait_until_changed(...)
+      # Wait until the current value equals an object using the configured comparison mode.
+      # @param object [BasicObject, nil] the value to compare with the current value
+      # @param timeout [Numeric, nil] the total seconds available
+      # @return [BasicObject, nil] the matching value, or nil on timeout
+      def wait_until_value(object, timeout: nil)
+        wait_until(timeout:) { |value| compare_by_identity? ? object.equal?(value) : object == value }
+      end
+      # Wait until `object === value` is true.
+      # @param object [#===] the pattern to match
+      # @param timeout [Numeric, nil] the total seconds available
+      # @return [BasicObject, nil] the matching value, or nil on timeout
+      def wait_until_match(object, timeout: nil)
+        wait_until(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
+      end
+      # Wait until the current value no longer matches an expected value.
+      # @param expected [BasicObject, nil] the value to compare with the current value
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield called when the timeout expires
+      # @return [BasicObject, nil] the changed value or the fallback result
+      def wait_until_changed(expected, timeout: nil, &)
+        internal_atom.wait_until_changed(expected, timeout:, &)
+      end
+      # Wait until the current value is not nil.
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield called when the timeout expires
+      # @return [BasicObject, nil] the non-nil value or the fallback result
+      def wait_until_non_nil(timeout: nil, &) = internal_atom.wait_until_non_nil(timeout:, &)
+      # @api private
+      def inspect_with(inspector)
+        super do
+          yield if block_given?
+          inspect_value(inspector)
+        end
+      end
+      protected
+      def internal_atom = @atom
+      private
+      def inspect_value(inspector, prefix = "value=")
+        if prefix
+          inspector.breakable
+          inspector.text(prefix)
+        end
+        inspector.object(value)
+      end
+      def initialize_copy(other)
+        super
+        source = other.internal_atom
+        copy   = source.class.new(source.value, compare_by_identity: source.compare_by_identity?)
+        if is_a?(Local::Scoped)
+          Internal::Storage.scope(scope)[self] = copy
+        else
+          @atom = copy
+        end
+      end
+    end
+  end
+end