farce 0.4.1 → 0.5.0

data/ext/farce/priority_queue.c

@@ -1964,11 +1964,55 @@ priority_queue_oldest_age(VALUE self)
     return priority_queue_call(self, queue, priority_queue_oldest_age_body, (VALUE)&operation);
 }
 
+static VALUE
+priority_queue_capacity_body(VALUE opaque)
+{
+    priority_queue_self_operation_t *operation = (priority_queue_self_operation_t *)opaque;
+    return operation->queue->bounded ? SIZET2NUM(operation->queue->capacity) : Qnil;
+}
+
 static VALUE
 priority_queue_capacity(VALUE self)
 {
     priority_queue_t *queue = priority_queue_get(self);
-    return queue->bounded ? SIZET2NUM(queue->capacity) : Qnil;
+    priority_queue_self_operation_t operation = {.queue = queue, .self = self};
+    if (priority_queue_can_run_direct(queue)) return priority_queue_capacity_body((VALUE)&operation);
+    return priority_queue_call(self, queue, priority_queue_capacity_body, (VALUE)&operation);
+}
+
+typedef struct {
+    priority_queue_t *queue;
+    VALUE value;
+    size_t capacity;
+    bool bounded;
+} priority_queue_resize_t;
+
+static VALUE
+priority_queue_set_capacity_body(VALUE opaque)
+{
+    priority_queue_resize_t *resize = (priority_queue_resize_t *)opaque;
+    priority_queue_notify_before_commit(resize->queue);
+    resize->queue->capacity = resize->capacity;
+    resize->queue->bounded = resize->bounded;
+    return resize->value;
+}
+
+static VALUE
+priority_queue_set_capacity(VALUE self, VALUE value)
+{
+    priority_queue_t *queue = priority_queue_get(self);
+    priority_queue_resize_t resize = {.queue = queue, .value = value, .capacity = 0, .bounded = !NIL_P(value)};
+    if (resize.bounded) {
+        resize.value = rb_to_int(value);
+        long long capacity = NUM2LL(resize.value);
+        if (capacity <= 0) rb_raise(rb_eArgError, "capacity must be positive or nil");
+        if ((unsigned long long)capacity > (unsigned long long)SIZE_MAX) {
+            rb_raise(rb_eArgError, "capacity is too large");
+        }
+        resize.capacity = (size_t)capacity;
+    }
+    if (priority_queue_can_run_direct(queue)) return priority_queue_set_capacity_body((VALUE)&resize);
+    return priority_queue_call(self, queue, priority_queue_set_capacity_body, (VALUE)&resize);
 }
 
 static void
@@ -1999,6 +2043,7 @@ priority_queue_define_methods(VALUE klass)
     rb_define_method(klass, "oldest_enqueued_at", priority_queue_oldest_enqueued_at, 0);
     rb_define_method(klass, "oldest_age", priority_queue_oldest_age, 0);
     rb_define_method(klass, "capacity", priority_queue_capacity, 0);
+    rb_define_method(klass, "capacity=", priority_queue_set_capacity, 1);
     rb_define_method(klass, "freeze", priority_queue_freeze, 0);
     rb_define_method(klass, "frozen?", priority_queue_frozen_p, 0);
 }

data/ext/farce/queue.c

@@ -33,6 +33,8 @@ typedef struct {
 #endif
 } readiness_signal_t;
 
+typedef struct queue_wait_context queue_wait_context_t;
+
 typedef struct {
     pthread_mutex_t lock;
     VALUE *values;
@@ -44,8 +46,14 @@ typedef struct {
     size_t tail;
     size_t pop_waiters;
     size_t push_waiters;
+    VALUE interrupt_token;
+    uint64_t interrupt_generation;
+    size_t interrupt_pending;
+    queue_wait_context_t *interrupt_waiters;
     readiness_signal_t can_pop;
     readiness_signal_t can_push;
+    readiness_signal_t interrupts_drained;
+    size_t interrupt_drain_waiters;
     farce_unshared_wait_list_t unshared_pop_waiters;
     farce_unshared_wait_list_t unshared_push_waiters;
     bool bounded;
@@ -160,20 +168,25 @@ queue_update_readiness(queue_t *queue)
     }
     readiness_set(
         &queue->can_pop,
-        queue->pop_waiters > 0 && (queue->closed || queue->size > 0)
+        queue->pop_waiters > 0 && (queue->closed || queue->size > 0 || queue->interrupt_pending > 0)
     );
     readiness_set(
         &queue->can_push,
         queue->push_waiters > 0 &&
             (queue->sealed || !queue->bounded || queue->size < queue->limit)
     );
+    readiness_set(
+        &queue->interrupts_drained,
+        queue->interrupt_drain_waiters > 0 && (queue->closed || queue->interrupt_pending == 0)
+    );
     if (!queue->shared) {
         /* Keep the slow path until both waiter mechanisms and every pending
          * readiness byte have drained. Interrupted direct waits may leave the
          * flag set, which is harmless and corrected by the next mutation. */
         queue->unshared_notifications_needed = queue->pop_waiters || queue->push_waiters ||
             queue->unshared_pop_waiters.count || queue->unshared_push_waiters.count ||
-            queue->can_pop.set || queue->can_push.set;
+            queue->can_pop.set || queue->can_push.set ||
+            queue->interrupt_drain_waiters || queue->interrupts_drained.set;
     }
 }
 
@@ -181,6 +194,7 @@ static void
 queue_mark(void *pointer)
 {
     queue_t *queue = pointer;
+    rb_gc_mark_movable(queue->interrupt_token);
     farce_unshared_wait_mark(&queue->unshared_pop_waiters);
     farce_unshared_wait_mark(&queue->unshared_push_waiters);
     if (!queue->values) return;
@@ -195,6 +209,7 @@ static void
 queue_compact(void *pointer)
 {
     queue_t *queue = pointer;
+    containers_gc_update(&queue->interrupt_token);
     if (!queue->values) return;
     size_t index = queue->head;
     for (size_t remaining = queue->size; remaining > 0; remaining--) {
@@ -212,6 +227,7 @@ queue_free(void *pointer)
     free(queue->enqueued_at);
     readiness_close(&queue->can_pop);
     readiness_close(&queue->can_push);
+    readiness_close(&queue->interrupts_drained);
     ruby_xfree(queue);
 }
 
@@ -277,8 +293,14 @@ queue_allocate_type(VALUE klass, bool shared)
     queue->tail = 0;
     queue->pop_waiters = 0;
     queue->push_waiters = 0;
+    queue->interrupt_token = Qnil;
+    queue->interrupt_generation = 0;
+    queue->interrupt_pending = 0;
+    queue->interrupt_waiters = NULL;
     queue->can_pop = (readiness_signal_t){.read_fd = -1, .write_fd = -1, .set = false};
     queue->can_push = (readiness_signal_t){.read_fd = -1, .write_fd = -1, .set = false};
+    queue->interrupts_drained = (readiness_signal_t){.read_fd = -1, .write_fd = -1, .set = false};
+    queue->interrupt_drain_waiters = 0;
     queue->unshared_pop_waiters = (farce_unshared_wait_list_t){0};
     queue->unshared_push_waiters = (farce_unshared_wait_list_t){0};
     queue->bounded = true;
@@ -384,6 +406,8 @@ typedef struct {
     bool finite;
     bool collected;
     double deadline;
+    bool interruptible;
+    VALUE token;
 } queue_timeout_t;
 
 static double
@@ -449,13 +473,44 @@ queue_wait_for_descriptor(int fd, queue_timeout_t *timeout)
     return containers_wait_for_readable(fd, wait_timeout);
 }
 
-typedef struct {
+struct queue_wait_context {
     queue_t *queue;
     readiness_signal_t *signal;
     size_t *waiter_count;
     queue_timeout_t *timeout;
     int wait_fd;
-} queue_wait_context_t;
+    bool linked;
+    uint64_t generation;
+    queue_wait_context_t *previous;
+    queue_wait_context_t *next;
+};
+
+/* Keep a wakeup readable until every interrupted descriptor waiter has left.
+ * Registration and removal happen under the same queue lock as publication. */
+static void
+queue_register_interrupt_waiter(queue_wait_context_t *context)
+{
+    if (!context->timeout->interruptible || context->signal != &context->queue->can_pop) return;
+    queue_t *queue = context->queue;
+    context->generation = queue->interrupt_generation;
+    context->previous = NULL;
+    context->next = queue->interrupt_waiters;
+    if (context->next) context->next->previous = context;
+    queue->interrupt_waiters = context;
+    context->linked = true;
+}
+
+static void
+queue_remove_interrupt_waiter(queue_wait_context_t *context)
+{
+    if (!context->linked) return;
+    queue_t *queue = context->queue;
+    if (context->previous) context->previous->next = context->next;
+    else queue->interrupt_waiters = context->next;
+    if (context->next) context->next->previous = context->previous;
+    if (context->generation != queue->interrupt_generation) queue->interrupt_pending--;
+    context->linked = false;
+}
 
 static VALUE
 queue_wait_body(VALUE opaque)
@@ -527,6 +582,7 @@ queue_wait_cleanup(VALUE opaque)
     queue_wait_context_t *context = (queue_wait_context_t *)opaque;
     if (context->wait_fd >= 0) close(context->wait_fd);
     queue_lock(context->queue);
+    queue_remove_interrupt_waiter(context);
     (*context->waiter_count)--;
     queue_update_readiness(context->queue);
     if (context->queue->closed && *context->waiter_count == 0) {
@@ -588,8 +644,16 @@ queue_wait(VALUE self, queue_t *queue, readiness_signal_t *signal, size_t *waite
         queue_unlock(queue);
         return false;
     }
+    /* A fresh wait must not repeatedly consume readiness reserved for older
+     * interrupted fibers on the same scheduler. Wait for their acknowledgments
+     * on a separate signal, without joining the interrupted generation. */
+    if (signal == &queue->can_pop && queue->interrupt_pending > 0) {
+        signal = &queue->interrupts_drained;
+        waiter_count = &queue->interrupt_drain_waiters;
+    }
     if (!queue->shared) queue->unshared_notifications_needed = true;
-    if (!queue->shared && (!queue->unshared_fiber_io || NIL_P(rb_fiber_scheduler_current()))) {
+    if (signal != &queue->interrupts_drained && !queue->shared &&
+        (!queue->unshared_fiber_io || NIL_P(rb_fiber_scheduler_current()))) {
         farce_unshared_wait_list_t *list = signal == &queue->can_pop ?
             &queue->unshared_pop_waiters : &queue->unshared_push_waiters;
         return farce_unshared_wait(list, self, timeout->finite, timeout->deadline);
@@ -611,6 +675,7 @@ queue_wait(VALUE self, queue_t *queue, readiness_signal_t *signal, size_t *waite
             .timeout = timeout,
             .wait_fd = -1,
         };
+        queue_register_interrupt_waiter(&context);
         (*waiter_count)++;
         queue_update_readiness(queue);
         queue_unlock(queue);
@@ -632,6 +697,7 @@ queue_wait(VALUE self, queue_t *queue, readiness_signal_t *signal, size_t *waite
         .timeout = timeout,
         .wait_fd = wait_fd,
     };
+    queue_register_interrupt_waiter(&context);
     (*waiter_count)++;
     queue_update_readiness(queue);
     queue_unlock(queue);
@@ -664,7 +730,54 @@ static VALUE
 queue_capacity(VALUE self)
 {
     queue_t *queue = get_queue(self);
-    return queue->bounded ? SIZET2NUM(queue->limit) : Qnil;
+    queue_lock(queue);
+    bool bounded = queue->bounded;
+    size_t limit = queue->limit;
+    queue_unlock(queue);
+    return bounded ? SIZET2NUM(limit) : Qnil;
+}
+
+static VALUE
+queue_set_capacity(VALUE self, VALUE value)
+{
+    size_t limit = 0;
+    if (!NIL_P(value)) {
+        long long converted = NUM2LL(rb_to_int(value));
+        if (converted <= 0) rb_raise(rb_eArgError, "capacity must be positive or nil");
+        if ((unsigned long long)converted > SIZE_MAX / sizeof(VALUE)) rb_raise(rb_eArgError, "capacity is too large");
+        limit = (size_t)converted;
+    }
+    queue_t *queue = get_queue(self);
+    queue_lock(queue);
+    queue->bounded = !NIL_P(value);
+    queue->limit = limit;
+    queue_update_readiness(queue);
+    queue_unlock(queue);
+    return value;
+}
+
+static VALUE
+queue_interrupt(VALUE self, VALUE token, VALUE generation_value)
+{
+    queue_t *queue = get_queue(self);
+    if (queue->shared) containers_check_shareable(token);
+    uint64_t generation = NUM2ULL(generation_value);
+    queue_lock(queue);
+    /* Concurrent writers can finish their notifications out of order. */
+    if (!NIL_P(queue->interrupt_token) && generation <= queue->interrupt_generation) {
+        queue_unlock(queue);
+        return self;
+    }
+    RB_OBJ_WRITE(self, &queue->interrupt_token, token);
+    queue->interrupt_generation = generation;
+    queue->interrupt_pending = 0;
+    for (queue_wait_context_t *waiter = queue->interrupt_waiters; waiter; waiter = waiter->next) {
+        if (waiter->generation != generation) queue->interrupt_pending++;
+    }
+    if (!queue->shared) farce_unshared_wait_notify_all(&queue->unshared_pop_waiters);
+    queue_update_readiness(queue);
+    queue_unlock(queue);
+    return self;
 }
 
 /* Called with queue->lock held. The queue is unchanged if allocation fails.
@@ -719,7 +832,7 @@ queue_num_waiting(VALUE self)
     queue_t *queue = get_queue(self);
     size_t num_waiting;
     queue_lock(queue);
-    num_waiting = queue->pop_waiters + queue->push_waiters +
+    num_waiting = queue->pop_waiters + queue->push_waiters + queue->interrupt_drain_waiters +
         queue->unshared_pop_waiters.count + queue->unshared_push_waiters.count;
     queue_unlock(queue);
     return SIZET2NUM(num_waiting);
@@ -848,6 +961,7 @@ queue_close(VALUE self)
         queue_update_readiness(queue);
         if (queue->pop_waiters == 0) readiness_close(&queue->can_pop);
         if (queue->push_waiters == 0) readiness_close(&queue->can_push);
+        if (queue->interrupt_drain_waiters == 0) readiness_close(&queue->interrupts_drained);
     }
     queue_unlock(queue);
     return self;
@@ -862,6 +976,7 @@ queue_release_wait_descriptors(VALUE self)
     queue_lock(queue);
     if (queue->pop_waiters == 0) readiness_close(&queue->can_pop);
     if (queue->push_waiters == 0) readiness_close(&queue->can_push);
+    if (queue->interrupt_drain_waiters == 0) readiness_close(&queue->interrupts_drained);
     queue_unlock(queue);
     return self;
 }
@@ -871,6 +986,10 @@ queue_pop_with_timeout(VALUE self, queue_t *queue, queue_timeout_t timeout)
 {
     for (;;) {
         queue_lock(queue);
+        if (timeout.interruptible && timeout.token != queue->interrupt_token) {
+            queue_unlock(queue);
+            return Qfalse;
+        }
         if (queue->closed) {
             queue_unlock(queue);
             raise_queue_closed();
@@ -902,6 +1021,18 @@ queue_pop(int argc, VALUE *argv, VALUE self)
     return queue_pop_with_timeout(self, queue, timeout);
 }
 
+/* Pool dispatch uses positional arguments to avoid another keyword hash. */
+static VALUE
+queue_pop_interruptible(VALUE self, VALUE token, VALUE timeout_value)
+{
+    queue_timeout_t timeout = parse_timeout(timeout_value);
+    timeout.interruptible = true;
+    timeout.token = token;
+    VALUE result = queue_pop_with_timeout(self, get_queue(self), timeout);
+    RB_GC_GUARD(token);
+    return result;
+}
+
 static VALUE
 queue_try_pop(VALUE self)
 {
@@ -1042,6 +1173,9 @@ containers_init_queue(VALUE namespace)
     rb_define_method(unshared, "fiber_wait", unshared_queue_fiber_wait, 0);
     rb_define_method(cQueue, "initialize", queue_initialize, -1);
     rb_define_method(cQueue, "capacity", queue_capacity, 0);
+    rb_define_method(cQueue, "capacity=", queue_set_capacity, 1);
+    rb_define_method(cQueue, "interrupt", queue_interrupt, 2);
+    rb_define_method(cQueue, "pop_interruptible", queue_pop_interruptible, 2);
     rb_define_method(cQueue, "size", queue_size, 0);
     rb_define_method(cQueue, "num_waiting", queue_num_waiting, 0);
     rb_define_method(cQueue, "clear", queue_clear, 0);

data/ext/farce/vector.c

@@ -1002,7 +1002,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 +1010,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;
     }
 }
 

data/ext/farce/weak_map.c

@@ -1173,9 +1173,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 +1193,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 +1684,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/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/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)