farce 0.4.1-x86-linux-gnu → 0.6.0-x86-linux-gnu

data/ext/farce/trie_search.h

@@ -0,0 +1,114 @@
+/* Included twice to specialize static matching without a mode branch in the
+ * traversal loop. Keep both modes on the same capture and backtracking logic. */
+
+static VALUE
+TRIE_SEARCH_BODY(VALUE opaque)
+{
+    trie_search_t *search = (trie_search_t *)(uintptr_t)opaque;
+#if TRIE_IGNORE_CASE
+    trie_case_mapping_t mapping = { .encoding = rb_enc_from_index(search->input_encoding) };
+    mapping.ascii_compatible = rb_enc_asciicompat(mapping.encoding);
+    trie_search_push_frame_ignore_case(search, search->trie->root, 0, 0, 0, &mapping);
+#else
+    trie_search_push_frame(search, search->trie->root, 0, 0);
+#endif
+    while (search->frame_count) {
+        trie_frame_t *frame = &search->frames[search->frame_count - 1];
+        trie_search_work_checkpoint(search);
+        if (frame->phase == 0) {
+            bool descended = false;
+            if (frame->node->static_index) {
+                while (frame->static_index) {
+                    trie_static_edge_t *edge = &frame->node->static_edges[frame->static_index - 1];
+#if TRIE_IGNORE_CASE
+                    long end_cursor;
+                    unsigned end_offset;
+#else
+                    long label_length = RSTRING_LEN(edge->label);
+#endif
+                    frame->static_index = edge->next_same_byte;
+#if TRIE_IGNORE_CASE
+                    if (!trie_static_match_ignore_case(search, frame, edge, &mapping,
+                                                       &end_cursor, &end_offset)) continue;
+                    trie_search_push_frame_ignore_case(search, edge->child, end_cursor,
+                                                        search->event_count, end_offset, &mapping);
+#else
+                    if (!trie_static_match(search->input, frame->cursor, edge,
+                                           label_length, search->input_encoding)) continue;
+                    trie_search_push_frame(search, edge->child, frame->cursor + label_length,
+                                           search->event_count);
+#endif
+                    descended = true;
+                    break;
+                }
+            }
+            else {
+                while (frame->static_index < frame->node->static_count) {
+                    trie_static_edge_t *edge = &frame->node->static_edges[frame->static_index++];
+#if TRIE_IGNORE_CASE
+                    long end_cursor;
+                    unsigned end_offset;
+#else
+                    long label_length = RSTRING_LEN(edge->label);
+#endif
+#if TRIE_IGNORE_CASE
+                    if (!trie_static_match_ignore_case(search, frame, edge, &mapping,
+                                                       &end_cursor, &end_offset)) continue;
+                    trie_search_push_frame_ignore_case(search, edge->child, end_cursor,
+                                                        search->event_count, end_offset, &mapping);
+#else
+                    if (!trie_static_match(search->input, frame->cursor, edge,
+                                           label_length, search->input_encoding)) continue;
+                    trie_search_push_frame(search, edge->child, frame->cursor + label_length,
+                                           search->event_count);
+#endif
+                    descended = true;
+                    break;
+                }
+            }
+            if (descended) continue;
+            frame->phase = 1;
+        }
+        if (frame->phase == 1) {
+            bool descended = false;
+            while (frame->regexp_index < frame->node->regexp_count) {
+#if TRIE_IGNORE_CASE
+                if (frame->lowercase_offset) break;
+#endif
+                trie_regexp_edge_t *edge = &frame->node->regexp_edges[frame->regexp_index++];
+                size_t restore = search->event_count;
+                long end_cursor;
+                if (!trie_regexp_match(edge, search, frame->cursor, &end_cursor)) {
+                    search->event_count = restore;
+                    continue;
+                }
+#if TRIE_IGNORE_CASE
+                trie_search_push_frame_ignore_case(search, edge->child, end_cursor, restore, 0, &mapping);
+#else
+                trie_search_push_frame(search, edge->child, end_cursor, restore);
+#endif
+                descended = true;
+                break;
+            }
+            if (descended) continue;
+            frame->phase = 2;
+        }
+        if (frame->phase == 2) {
+            frame->phase = 3;
+            if (
+#if TRIE_IGNORE_CASE
+                !frame->lowercase_offset &&
+#endif
+                (search->peek || frame->cursor == search->input_length) &&
+                trie_emit_terminal(search, frame)) break;
+        }
+        if (frame->phase == 3) {
+            size_t restore = frame->restore_events;
+            search->frame_count--;
+            search->event_count = restore;
+        }
+    }
+    if (search->stream) return search->self;
+    return search->first_only ? search->first : search->results;
+}
+

data/ext/farce/vector.c

@@ -4,6 +4,7 @@
 #include "ruby/fiber/scheduler.h"
 
 #include <errno.h>
+#include <limits.h>
 #include <math.h>
 #include <stdint.h>
 #include <stdlib.h>
@@ -380,22 +381,26 @@ vector_assignment_index(vector_t *vector, long long raw)
     return (size_t)raw;
 }
 
+static size_t
+vector_initial_size(VALUE source)
+{
+    long size = NUM2LONG(source);
+    if (size < 0) rb_raise(rb_eArgError, "negative array size");
+    if (size > LONG_MAX / (long)sizeof(VALUE)) rb_raise(rb_eArgError, "array size too big");
+    return (size_t)size;
+}
+
 static VALUE
-vector_initialize(int argc, VALUE *argv, VALUE self)
+vector_normalize_source(VALUE klass, VALUE source)
 {
-    VALUE source = Qnil;
-    VALUE keywords = Qnil;
-    VALUE identity = Qundef;
-    ID keyword_ids[] = {rb_intern("compare_by_identity")};
-    VALUE keyword_values[1];
-    vector_t *vector;
+    if (RB_INTEGER_TYPE_P(source)) vector_initial_size(source);
+    return source;
+}
 
-    rb_check_frozen(self);
-    rb_scan_args(argc, argv, "01:", &source, &keywords);
-    if (!NIL_P(keywords)) {
-        rb_get_kwargs(keywords, keyword_ids, 0, 1, keyword_values);
-        identity = keyword_values[0];
-    }
+static VALUE
+vector_initialize_with_identity(VALUE self, VALUE source, VALUE identity)
+{
+    vector_t *vector;
     TypedData_Get_Struct(self, vector_t, &vector_type, vector);
     if (vector->initialized) rb_raise(rb_eRuntimeError, "Vector is already initialized");
 
@@ -403,8 +408,12 @@ vector_initialize(int argc, VALUE *argv, VALUE self)
         ? false
         : containers_strict_bool(identity, "compare_by_identity");
 
+    bool sized = RB_INTEGER_TYPE_P(source);
     size_t size = 0;
-    if (!NIL_P(source)) {
+    if (sized) {
+        size = vector_initial_size(source);
+    }
+    else if (!NIL_P(source)) {
         Check_Type(source, T_ARRAY);
         size = (size_t)RARRAY_LEN(source);
     }
@@ -413,16 +422,37 @@ vector_initialize(int argc, VALUE *argv, VALUE self)
     if (!vector->values) rb_memerror();
     vector->capacity = capacity;
 
-    for (size_t index = 0; index < size; index++) {
-        VALUE value = rb_ary_entry(source, (long)index);
-        containers_check_shareable(value);
-        RB_OBJ_WRITE(self, &vector->values[index], value);
+    if (!sized) {
+        for (size_t index = 0; index < size; index++) {
+            VALUE value = rb_ary_entry(source, (long)index);
+            containers_check_shareable(value);
+            RB_OBJ_WRITE(self, &vector->values[index], value);
+        }
     }
     vector->size = size;
     vector->initialized = true;
+    if (sized) return containers_publish_native_reference_free(self);
     return containers_publish_native_with_references(self, vector_validate_references);
 }
 
+static VALUE
+vector_initialize(int argc, VALUE *argv, VALUE self)
+{
+    ID keyword_ids[] = {rb_intern("compare_by_identity")};
+    VALUE keyword_values[1];
+
+    rb_check_frozen(self);
+    VALUE source = containers_parse_constructor(argc, argv, keyword_ids, 1, keyword_values);
+    return vector_initialize_with_identity(self, source, keyword_values[0]);
+}
+
+static VALUE
+vector_new_for_modes(VALUE klass, VALUE source)
+{
+    VALUE self = rb_obj_alloc(klass);
+    return vector_initialize_with_identity(self, source, Qtrue);
+}
+
 static VALUE
 vector_snapshot_locked(VALUE self)
 {
@@ -1002,7 +1032,7 @@ vector_wait_until_changed(int argc, VALUE *argv, VALUE self)
         uint64_t generation;
         size_t index;
         pthread_mutex_lock(&vector->lock);
-        if (!vector_wait_for_reservation_locked(vector, &timeout)) return Qnil;
+        if (!vector_wait_for_reservation_locked(vector, &timeout)) return rb_block_given_p() ? rb_yield(Qnil) : Qnil;
         VALUE current = vector_lookup_index(vector, raw, &index) ? vector->values[index] : Qnil;
         generation = vector->generation;
         pthread_mutex_unlock(&vector->lock);
@@ -1010,12 +1040,12 @@ vector_wait_until_changed(int argc, VALUE *argv, VALUE self)
         if (!vector_values_equal(vector, current, expected)) return current;
 
         pthread_mutex_lock(&vector->lock);
-        if (!vector_wait_for_reservation_locked(vector, &timeout)) return Qnil;
+        if (!vector_wait_for_reservation_locked(vector, &timeout)) return rb_block_given_p() ? rb_yield(Qnil) : Qnil;
         if (vector->generation != generation) {
             pthread_mutex_unlock(&vector->lock);
             continue;
         }
-        if (!vector_wait_once(vector, &timeout)) return Qnil;
+        if (!vector_wait_once(vector, &timeout)) return rb_block_given_p() ? rb_yield(Qnil) : Qnil;
     }
 }
 
@@ -1185,6 +1215,8 @@ containers_init_vector(VALUE namespace)
 
     cVector = rb_define_class_under(namespace, "Vector", rb_cObject);
     rb_define_alloc_func(cVector, vector_allocate);
+    rb_define_singleton_method(cVector, "normalize_source", vector_normalize_source, 1);
+    rb_define_singleton_method(cVector, "new_for_modes", vector_new_for_modes, 1);
     rb_define_method(cVector, "freeze", vector_freeze, 0);
     rb_define_method(cVector, "initialize", vector_initialize, -1);
     rb_define_method(cVector, "size", vector_size, 0);

data/ext/farce/weak_map.c

@@ -1,4 +1,5 @@
 #include "containers.h"
+#include "weak_references.h"
 
 #ifdef RC_HAVE_NATIVE_WEAK_REFERENCES
 
@@ -15,11 +16,6 @@
 
 #define WEAK_MAP_INITIAL_CAPACITY 16
 
-/* These functions are exported by Rubies with the probed typed-data weak
- * reference callback, but their declarations intentionally remain internal. */
-void rb_gc_declare_weak_references(VALUE object);
-bool rb_gc_handle_weak_references_alive_p(VALUE object);
-
 static VALUE cWeakKeyMap;
 static VALUE weak_map_keep;
 static VALUE weak_map_delete_token;
@@ -209,7 +205,7 @@ weak_map_compact(void *pointer)
  * mutex here could deadlock if GC stopped a mutator at a safepoint while it
  * owned the mutex, so cleanup deliberately runs lock-free. */
 static void
-weak_map_handle_weak_references(void *pointer)
+FARCE_WEAK_REFERENCES_CALLBACK(weak_map_handle_weak_references)
 {
     weak_map_t *map = pointer;
     if (!map->slots) return;
@@ -219,8 +215,8 @@ weak_map_handle_weak_references(void *pointer)
         weak_map_slot_t *slot = &map->slots[index];
         if (slot->state != WEAK_MAP_OCCUPIED) continue;
 
-        bool key_alive = !map->weak_keys || rb_gc_handle_weak_references_alive_p(slot->key);
-        bool value_alive = !map->weak_values || rb_gc_handle_weak_references_alive_p(slot->value);
+        bool key_alive = !map->weak_keys || FARCE_WEAK_REFERENCE_ALIVE_P(slot->key);
+        bool value_alive = !map->weak_values || FARCE_WEAK_REFERENCE_ALIVE_P(slot->value);
         if (key_alive && value_alive) continue;
 
         slot->key = Qnil;
@@ -1173,9 +1169,15 @@ weak_map_modify_body(VALUE opaque)
 }
 
 static VALUE
-weak_map_modify(VALUE self, VALUE key)
+weak_map_modify(int argc, VALUE *argv, VALUE self)
 {
     rb_check_frozen(self);
+    VALUE key;
+    VALUE keywords = Qnil;
+    VALUE keyword_values[1] = {Qundef};
+    ID keyword_ids[] = {rb_intern("timeout")};
+    rb_scan_args(argc, argv, "1:", &key, &keywords);
+    if (!NIL_P(keywords)) rb_get_kwargs(keywords, keyword_ids, 0, 1, keyword_values);
     rb_need_block();
     weak_map_t *map = get_weak_map(self);
     key = weak_map_prepare_key(map, key);
@@ -1187,8 +1189,11 @@ weak_map_modify(VALUE self, VALUE key)
     };
     operation.hash = weak_map_key_hash(map, key);
     rb_check_frozen(self);
+    weak_map_timeout_t timeout = weak_map_parse_timeout(
+        keyword_values[0] == Qundef ? Qnil : keyword_values[0]
+    );
     weak_map_execution_context_t execution = {.self = self};
-    weak_map_lock_for_key(map, key, operation.hash, &execution);
+    if (!weak_map_lock_for_key_with_timeout(map, key, operation.hash, &timeout, &execution)) return Qfalse;
     bool found;
     size_t index = weak_map_find_slot(map, key, operation.hash, &found, &execution);
     if (RB_OBJ_FROZEN(self)) {
@@ -1675,7 +1680,7 @@ define_weak_map_methods(VALUE klass)
     rb_define_method(klass, "store", weak_map_store_with_timeout, -1);
     rb_define_method(klass, "swap", weak_map_swap, -1);
     rb_define_method(klass, "update", weak_map_update, -1);
-    rb_define_method(klass, "modify", weak_map_modify, 1);
+    rb_define_method(klass, "modify", weak_map_modify, -1);
     rb_define_method(klass, "wait_until_changed", weak_map_wait_until_changed, -1);
     rb_define_method(klass, "wait_until_non_nil", weak_map_wait_until_non_nil, -1);
     rb_define_method(klass, "store_if_absent", weak_map_store_if_absent, -1);

data/ext/farce/weak_references.h

@@ -0,0 +1,23 @@
+#ifndef FARCE_WEAK_REFERENCES_H
+#define FARCE_WEAK_REFERENCES_H
+
+#include "ruby.h"
+#include <stdbool.h>
+
+#ifdef RC_HAVE_NATIVE_WEAK_REFERENCES
+/* These symbols are exported, but their declarations remain internal. The
+ * callback and liveness function gained the same opaque GC context together. */
+void rb_gc_declare_weak_references(VALUE object);
+
+#ifdef FARCE_WEAK_REFERENCES_HAVE_OBJSPACE
+bool rb_gc_handle_weak_references_alive_p(void *objspace, VALUE object);
+# define FARCE_WEAK_REFERENCES_CALLBACK(name) name(void *pointer, void *objspace)
+# define FARCE_WEAK_REFERENCE_ALIVE_P(object) rb_gc_handle_weak_references_alive_p(objspace, object)
+#else
+bool rb_gc_handle_weak_references_alive_p(VALUE object);
+# define FARCE_WEAK_REFERENCES_CALLBACK(name) name(void *pointer)
+# define FARCE_WEAK_REFERENCE_ALIVE_P(object) rb_gc_handle_weak_references_alive_p(object)
+#endif
+#endif
+
+#endif

data/ext/java/org/farce/FiberScheduler.java

@@ -17,6 +17,7 @@ import org.jruby.RubyModule;
 import org.jruby.RubyObject;
 import org.jruby.RubyThread;
 import org.jruby.anno.JRubyMethod;
+import org.jruby.api.Access;
 import org.jruby.runtime.ThreadContext;
 import org.jruby.runtime.builtin.IRubyObject;
 import org.jruby.util.io.SelectExecutor;
@@ -30,9 +31,10 @@ public final class FiberScheduler extends RubyObject {
     public FiberScheduler(Ruby runtime, RubyClass klass) { super(runtime, klass); }
 
     public static void load(Ruby runtime) {
-        RubyModule internal = (RubyModule) runtime.getModule("Farce").getConstantAt("Internal");
-        RubyClass klass = internal.defineClassUnder("FiberScheduler", runtime.getObject(), FiberScheduler::new);
-        klass.defineAnnotatedMethods(FiberScheduler.class);
+        ThreadContext context = runtime.getCurrentContext();
+        RubyModule internal = (RubyModule) Access.getModule(context, "Farce").getConstantAt(context, "Internal");
+        RubyClass klass = internal.defineClassUnder(context, "FiberScheduler", runtime.getObject(), FiberScheduler::new);
+        klass.defineMethods(context, FiberScheduler.class);
     }
 
     @JRubyMethod(name = "nio_initialize")
@@ -59,14 +61,14 @@ public final class FiberScheduler extends RubyObject {
         checkOwner(context);
         if (selector == null) throw context.runtime.newIOError("scheduler is closed");
         RubyArray groups = (RubyArray) groupValue;
-        Long milliseconds = timeout.isNil() ? null : Math.max(0, (long)Math.ceil(timeout.convertToFloat().getDoubleValue() * 1000));
+        Long milliseconds = timeout.isNil() ? null : Math.max(0, (long)Math.ceil(timeout.convertToFloat().asDouble(context) * 1000));
         IRubyObject immediate = snapshot(context, groups, 0L);
         if (!immediate.isNil() || (milliseconds != null && milliseconds == 0)) return immediate;
         HashMap<SelectableChannel, Integer> interests = new HashMap<>();
         boolean compatible = ((RubyArray)groups.entry(2)).isEmpty();
         for (int i = 0; i < 2; i++) {
             RubyArray list = (RubyArray)groups.entry(i);
-            for (Object object : list.toJavaArray()) {
+            for (Object object : list.toJavaArray(context)) {
                 RubyIO io = RubyIO.convertToIO(context, (IRubyObject)object);
                 SelectableChannel channel = io.getOpenFileChecked().fd().chSelect;
                 if (channel == null || channel.provider() != selector.provider()) { compatible = false; continue; }
@@ -123,7 +125,7 @@ public final class FiberScheduler extends RubyObject {
     public IRubyObject hookBuffer(ThreadContext context, IRubyObject value) {
         RubyIOBuffer buffer = (RubyIOBuffer)value;
         if (!buffer.locked_p(context).isTrue()) return value;
-        if (buffer.size(context).convertToInteger().getLongValue() != 0) return value;
+        if (buffer.size(context).convertToInteger().asLong(context) != 0) return value;
         try {
             Field field = RubyIOBuffer.class.getDeclaredField("base");
             if (!field.trySetAccessible()) throw context.runtime.newRuntimeError("Farce cannot access the JRuby hook buffer layout");

data/ext/java/org/farce/PriorityQueue.java

@@ -54,7 +54,8 @@ public final class PriorityQueue {
     private final Consumer<Runnable> committer;
     private final QueueSignal signal;
     private final BooleanSupplier scheduled;
-    private final long capacity;
+    private long capacity;
+    private Object rubyCapacity;
     private final boolean trackAge;
     private long size;
     private long generation;
@@ -70,7 +71,7 @@ public final class PriorityQueue {
                          BiPredicate<Object, Object> identical,
                          BiPredicate<Object, Object> match,
                          Consumer<Runnable> committer,
-                         BooleanSupplier scheduled, long capacity, QueueSignal signal,
+                         BooleanSupplier scheduled, long capacity, Object rubyCapacity, QueueSignal signal,
                          boolean trackAge) {
         this.tree = new TreeMap<>(comparator);
         this.snapshot = snapshot;
@@ -82,6 +83,7 @@ public final class PriorityQueue {
         this.signal = signal;
         this.scheduled = scheduled;
         this.capacity = capacity;
+        this.rubyCapacity = rubyCapacity;
         this.trackAge = trackAge;
     }
 
@@ -302,6 +304,20 @@ public final class PriorityQueue {
         }
     }
 
+    public Object getCapacity() {
+        enter();
+        try { return rubyCapacity; } finally { lock.unlock(); }
+    }
+
+    public void setCapacity(long capacity, Object rubyCapacity) {
+        enter();
+        try { commit(() -> {
+            this.capacity = capacity;
+            this.rubyCapacity = rubyCapacity;
+        }); }
+        finally { lock.unlock(); }
+    }
+
     public long size() {
         enter();
         try { return size; } finally { lock.unlock(); }

data/lib/farce/abstract/atom.rb

@@ -59,7 +59,11 @@ module Farce
       # @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:, &)
+      def store_if_absent(timeout: nil, &)
+        return internal_atom.store_if_absent(&) if timeout.nil?
+
+        internal_atom.store_if_absent(timeout:, &)
+      end
 
       # Atomically replace the current value if it matches the expected value.
       # @param expected [BasicObject, nil] the value to compare with the current value

data/lib/farce/abstract/concurrent_map.rb

@@ -5,6 +5,9 @@
 module Farce
   module Abstract
     # @abstract Super class for {Map maps} with added concurrency features.
+    #
+    # Maps implement most of the interface provided by Hash,
+    # as well as `Concurrent::Map` from the `concurrent-ruby` gem.
     class ConcurrentMap < Map
       include DuplicableMap
 
@@ -34,6 +37,24 @@ module Farce
         end
       end
 
+      # Return an existing value or store a default for an absent key.
+      # A block takes precedence over the default and receives the original key.
+      # The lookup and store are separate operations. Concurrent writes can be overwritten.
+      # @param key [BasicObject] The key to look up or store.
+      # @param defaults [Array<BasicObject>] At most one default value to store when the key is absent.
+      # @see #store For supported transfer and timeout options.
+      # @yieldparam key [BasicObject] The original key.
+      # @yieldreturn [BasicObject] The value to store.
+      # @return [BasicObject, nil] The existing or newly stored value.
+      # @raise [KeyError] If the key is absent and neither a default nor a block is provided.
+      def fetch_or_store(key, *defaults, **)
+        if defaults.size > 1
+          raise ArgumentError, "wrong number of arguments (given #{defaults.size + 1}, expected 1..2)"
+        end
+        return fetch(key) if defaults.empty? && !block_given?
+        fetch(key) { store(key, block_given? ? yield(key) : defaults.first, **) }
+      end
+
       # Read the value associated with a key, waiting for atomic-update access if necessary.
       # @param key [BasicObject] The key to look up.
       # @param timeout [Numeric, nil] The maximum number of seconds to wait for access.
@@ -43,6 +64,12 @@ module Farce
       #   The associated value, nil if the key is absent, or the fallback result if the operation times out.
       def get(key, timeout: nil, &) = internal_map.get(key, timeout:, &)
 
+      # Sets a value and returns the previous value.
+      # @param key [BasicObject] The key to update.
+      # @param value [BasicObject] The value to store.
+      # @return [BasicObject, nil] The previous value, or nil if the key was absent.
+      def get_and_set(...) = swap(...)
+
       # Associate a value with a key, waiting for atomic-update access if necessary.
       # @param key [BasicObject] The key to store.
       # @param value [BasicObject] The value to store.
@@ -52,6 +79,9 @@ module Farce
       # @return [BasicObject, nil] `value` on success, or the fallback result or nil on timeout.
       def store(key, value, timeout: nil, &) = internal_map.store(key, value, timeout:, &)
 
+      # (see #store)
+      def put(...) = store(...)
+
       # Replace the value associated with a key and return its previous value.
       # @param key [BasicObject] The key to update.
       # @param replacement [BasicObject] The value to store.
@@ -71,6 +101,69 @@ module Farce
       # @raise [LocalJumpError] If no block is given.
       def store_if_absent(key, timeout: nil, &) = internal_map.store_if_absent(key, timeout:, &)
 
+      # (see #store_if_absent)
+      def compute_if_absent(...) = store_if_absent(...)
+
+      # Atomically store a value only when the key is absent.
+      # Existing nil and false values are preserved.
+      # @param key [BasicObject] The key to look up or store.
+      # @param value [BasicObject] The value to store when the key is absent.
+      # @see #store_if_absent For supported transfer and timeout options.
+      # @return [BasicObject, nil] The existing value, or nil when a value was inserted or access timed out.
+      def put_if_absent(key, value, **)
+        inserted = false
+        previous = store_if_absent(key, **) do
+          inserted = true
+          value
+        end
+        inserted ? nil : previous
+      end
+
+      # Atomically replace an existing value and return its previous value.
+      # An absent key is left unchanged. Existing nil and false values can be replaced.
+      # @param key [BasicObject] The key to update.
+      # @param replacement [BasicObject] The value to store.
+      # @param timeout [Numeric, nil] The maximum number of seconds to wait for access.
+      # @see #store For supported transfer options.
+      # @return [BasicObject, nil] The previous value, or nil when the key is absent or access timed out.
+      def replace_if_exists(key, replacement, timeout: nil, **)
+        map = internal_map
+        previous = nil
+        changed = map.modify(key, timeout:) do |present, value|
+          next Internal::MAP_KEEP unless present
+          previous = value
+          map.check_mutation
+          wrap_value(replacement, **)
+        end
+        unwrap_value(previous) if changed
+      end
+
+      # Atomically replace the value associated with a key if it is present.
+      # The block receives the current value and should return the new value to store.
+      # The block is not called for an absent key. A stored nil is passed to the block.
+      # @param key [BasicObject] The key to update.
+      # @param timeout [Numeric, nil] The maximum number of seconds to wait for access.
+      # @yield [value] Called with the current value if the key is present.
+      # @yieldparam value [BasicObject] The current value.
+      # @yieldreturn [BasicObject] The new value to store.
+      # @return [BasicObject, nil] The newly stored value, or nil if the key was absent or the operation timed out.
+      # @raise [LocalJumpError] If no block is given.
+      def store_if_present(key, timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        map = internal_map
+        result = nil
+        changed = map.modify(key, timeout:) do |present, value|
+          next Internal::MAP_KEEP unless present
+          replacement = yield(unwrap_value(value))
+          map.check_mutation
+          result = wrap_value(replacement)
+        end
+        unwrap_value(result) if changed
+      end
+
+      # (see #store_if_present)
+      def compute_if_present(...) = store_if_present(...)
+
       # Atomically replace a value if the key is present and its current value matches `expected`.
       # The configured value-comparison mode determines whether matching uses equality or identity.
       # @param key [BasicObject] The key to update.
@@ -82,6 +175,23 @@ module Farce
         internal_map.compare_and_set(key, expected, replacement, timeout:)
       end
 
+      # (see #compare_and_set)
+      def replace_pair(...) = compare_and_set(...)
+
+      # Atomically remove a key if its current value matches `expected`.
+      # The configured value-comparison mode determines whether matching uses equality or identity.
+      # Missing keys and mismatched values are left unchanged.
+      # @param key [BasicObject] The key to remove.
+      # @param expected [BasicObject] The expected current value.
+      # @param timeout [Numeric, nil] The maximum number of seconds to wait for access.
+      # @return [Boolean] Whether the entry was removed. Returns false on timeout.
+      def delete_pair(key, expected, timeout: nil)
+        expected = wrap_comparison(expected)
+        internal_map.modify(key, timeout:) do |present, value|
+          present && values_equal?(value, expected) ? Internal::MAP_DELETE : Internal::MAP_KEEP
+        end
+      end
+
       # Atomically replace the value associated with a key with the block result.
       # The block receives nil when the key is absent or its current value is nil.
       # @param key [BasicObject] The key to update.
@@ -93,6 +203,9 @@ module Farce
       # @raise [LocalJumpError] If no block is given.
       def update(key, timeout: nil, &) = internal_map.update(key, timeout:, &)
 
+      # (see #update)
+      def compute(...) = update(...)
+
       # Atomically insert `initial` for an absent key or replace an existing value with the block result.
       # The block is not called when the key is absent.
       # @param key [BasicObject] The key to insert or update.
@@ -105,6 +218,9 @@ module Farce
       # @raise [LocalJumpError] If no block is given.
       def upsert(key, initial, timeout: nil, &) = internal_map.upsert(key, initial, timeout:, &)
 
+      # (see #upsert)
+      def merge_pair(...) = upsert(...)
+
       # 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
@@ -344,6 +460,12 @@ module Farce
 
       private
 
+      def wrap_comparison(value) = value
+
+      def values_equal?(left, right)
+        compare_values_by_identity? ? left.equal?(right) : left == right
+      end
+
       def modify_entry(key, canonical: false)
         map = internal_map
         map = map.instance_variable_get(:@map) if canonical && map.is_a?(Internal::KeyNormalizer::ConcurrentMap)