farce 0 → 0.1.0

data/ext/farce/vector.c

@@ -0,0 +1,1195 @@
+#include "containers.h"
+#include "transaction.h"
+#include "ruby/io.h"
+#include "ruby/fiber/scheduler.h"
+
+#include <errno.h>
+#include <fcntl.h>
+#include <math.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <time.h>
+#include <unistd.h>
+
+#define VECTOR_INITIAL_CAPACITY 16
+static VALUE cVector;
+static ID vector_values_id, vector_updating_id, vector_mutex_id;
+static VALUE vector_transaction_marker;
+
+typedef struct vector_waiter vector_waiter_t;
+
+struct vector_waiter {
+    int read_fd;
+    int write_fd;
+    bool notified;
+    vector_waiter_t *next;
+};
+
+typedef struct {
+    pthread_mutex_t lock;
+    VALUE *values;
+    size_t capacity;
+    size_t size;
+    vector_waiter_t *waiters;
+    uint64_t generation;
+    bool compare_by_identity;
+    uint8_t updating;
+    bool initialized;
+    VALUE updating_fiber;
+    VALUE updating_thread;
+} vector_t;
+
+typedef struct {
+    bool finite;
+    double deadline;
+} vector_timeout_t;
+
+static void
+vector_mark(void *pointer)
+{
+    vector_t *vector = pointer;
+    rb_gc_mark_movable(vector->updating_fiber);
+    rb_gc_mark_movable(vector->updating_thread);
+    if (!vector->values) return;
+    for (size_t index = 0; index < vector->size; index++) {
+        rb_gc_mark_movable(vector->values[index]);
+    }
+}
+
+static void
+vector_compact(void *pointer)
+{
+    vector_t *vector = pointer;
+    vector->updating_fiber = rb_gc_location(vector->updating_fiber);
+    vector->updating_thread = rb_gc_location(vector->updating_thread);
+    if (!vector->values) return;
+    for (size_t index = 0; index < vector->size; index++) {
+        vector->values[index] = rb_gc_location(vector->values[index]);
+    }
+}
+
+static void
+vector_free(void *pointer)
+{
+    vector_t *vector = pointer;
+    pthread_mutex_destroy(&vector->lock);
+    free(vector->values);
+    ruby_xfree(vector);
+}
+
+static size_t
+vector_memsize(const void *pointer)
+{
+    const vector_t *vector = pointer;
+    return vector ? sizeof(vector_t) + vector->capacity * sizeof(VALUE) : 0;
+}
+
+static const rb_data_type_t vector_type = {
+    .wrap_struct_name = "Ractor::Containers::Vector",
+    .function = {
+        .dmark = vector_mark,
+        .dfree = vector_free,
+        .dsize = vector_memsize,
+        .dcompact = vector_compact,
+    },
+    .flags = RUBY_TYPED_FROZEN_SHAREABLE,
+};
+
+static void
+vector_validate_references(VALUE self)
+{
+    vector_t *vector;
+    TypedData_Get_Struct(self, vector_t, &vector_type, vector);
+    for (size_t index = 0; index < vector->size; index++) {
+        containers_check_shareable(vector->values[index]);
+    }
+}
+
+static VALUE
+vector_allocate(VALUE klass)
+{
+    vector_t *vector;
+    VALUE object = TypedData_Make_Struct(klass, vector_t, &vector_type, vector);
+    pthread_mutex_init(&vector->lock, NULL);
+    vector->values = NULL;
+    vector->capacity = 0;
+    vector->size = 0;
+    vector->waiters = NULL;
+    vector->generation = 0;
+    vector->compare_by_identity = false;
+    vector->updating = false;
+    vector->initialized = false;
+    vector->updating_fiber = Qnil;
+    vector->updating_thread = Qnil;
+    return object;
+}
+
+static vector_t *
+get_vector(VALUE self)
+{
+    vector_t *vector;
+    TypedData_Get_Struct(self, vector_t, &vector_type, vector);
+    if (!vector->initialized) rb_raise(rb_eRuntimeError, "uninitialized Vector");
+    return vector;
+}
+
+static VALUE *
+vector_allocate_values(size_t capacity)
+{
+    if (capacity > SIZE_MAX / sizeof(VALUE)) return NULL;
+    VALUE *values = malloc(capacity * sizeof(VALUE));
+    if (!values) return NULL;
+    for (size_t index = 0; index < capacity; index++) values[index] = Qnil;
+    return values;
+}
+
+static bool
+vector_ensure_capacity(vector_t *vector, size_t required)
+{
+    if (required <= vector->capacity) return true;
+
+    size_t capacity = vector->capacity ? vector->capacity : VECTOR_INITIAL_CAPACITY;
+    while (capacity < required) {
+        if (capacity > SIZE_MAX / 2) {
+            capacity = required;
+            break;
+        }
+        capacity *= 2;
+    }
+
+    VALUE *values = vector_allocate_values(capacity);
+    if (!values) return false;
+    for (size_t index = 0; index < vector->size; index++) values[index] = vector->values[index];
+    free(vector->values);
+    vector->values = values;
+    vector->capacity = capacity;
+    return true;
+}
+
+static double
+vector_monotonic_now(void)
+{
+    struct timespec now;
+#ifdef CLOCK_MONOTONIC
+    if (clock_gettime(CLOCK_MONOTONIC, &now) == 0) {
+        return (double)now.tv_sec + (double)now.tv_nsec / 1000000000.0;
+    }
+#endif
+    struct timeval fallback;
+    gettimeofday(&fallback, NULL);
+    return (double)fallback.tv_sec + (double)fallback.tv_usec / 1000000.0;
+}
+
+static vector_timeout_t
+vector_parse_timeout(VALUE value)
+{
+    vector_timeout_t timeout = {.finite = false, .deadline = 0};
+    if (NIL_P(value)) return timeout;
+
+    double seconds = NUM2DBL(value);
+    if (!isfinite(seconds) || seconds < 0) {
+        rb_raise(rb_eArgError, "timeout must be a finite, non-negative number or nil");
+    }
+    timeout.finite = true;
+    timeout.deadline = vector_monotonic_now() + seconds;
+    return timeout;
+}
+
+static VALUE
+vector_timeout_keyword(VALUE keywords)
+{
+    VALUE timeout = Qnil;
+    if (!NIL_P(keywords)) {
+        ID keyword_ids[] = {rb_intern("timeout")};
+        VALUE keyword_values[1];
+        rb_get_kwargs(keywords, keyword_ids, 0, 1, keyword_values);
+        if (keyword_values[0] != Qundef) timeout = keyword_values[0];
+    }
+    return timeout;
+}
+
+static void
+vector_set_fd_flags(int fd)
+{
+#ifdef _WIN32
+    (void)fd;
+#else
+    int flags = fcntl(fd, F_GETFL, 0);
+    if (flags >= 0) (void)fcntl(fd, F_SETFL, flags | O_NONBLOCK);
+    flags = fcntl(fd, F_GETFD, 0);
+    if (flags >= 0) (void)fcntl(fd, F_SETFD, flags | FD_CLOEXEC);
+#endif
+}
+
+/* Called with vector->lock held. Each waiter has an independent pipe, so a
+ * transition wakes every waiting thread or scheduled fiber. */
+static void
+vector_notify_waiters_locked(vector_t *vector)
+{
+    unsigned char byte = 1;
+    vector->generation++;
+    for (vector_waiter_t *waiter = vector->waiters; waiter; waiter = waiter->next) {
+        if (waiter->notified) continue;
+        ssize_t result;
+        do {
+            result = write(waiter->write_fd, &byte, 1);
+        } while (result < 0 && errno == EINTR);
+        if (result == 1 || (result < 0 && (errno == EAGAIN || errno == EWOULDBLOCK))) {
+            waiter->notified = true;
+        }
+    }
+}
+
+static void
+vector_finish_update_locked(vector_t *vector)
+{
+    vector->updating = false;
+    vector_notify_waiters_locked(vector);
+}
+
+typedef struct {
+    vector_t *vector;
+    vector_waiter_t waiter;
+    vector_timeout_t *timeout;
+} vector_wait_context_t;
+
+static bool
+vector_wait_for_descriptor(int fd, vector_timeout_t *timeout)
+{
+    VALUE wait_timeout = Qnil;
+    if (timeout->finite) {
+        double remaining = timeout->deadline - vector_monotonic_now();
+        if (remaining <= 0) return false;
+        wait_timeout = DBL2NUM(remaining);
+    }
+    return containers_wait_for_readable(fd, wait_timeout);
+}
+
+static VALUE
+vector_wait_body(VALUE opaque)
+{
+    vector_wait_context_t *context = (vector_wait_context_t *)opaque;
+    return vector_wait_for_descriptor(context->waiter.read_fd, context->timeout) ? Qtrue : Qfalse;
+}
+
+static VALUE
+vector_wait_cleanup(VALUE opaque)
+{
+    vector_wait_context_t *context = (vector_wait_context_t *)opaque;
+    vector_waiter_t **link;
+
+    pthread_mutex_lock(&context->vector->lock);
+    for (link = &context->vector->waiters; *link; link = &(*link)->next) {
+        if (*link == &context->waiter) {
+            *link = context->waiter.next;
+            break;
+        }
+    }
+    pthread_mutex_unlock(&context->vector->lock);
+    close(context->waiter.read_fd);
+    close(context->waiter.write_fd);
+    return Qnil;
+}
+
+/* Called with vector->lock held and always returns with it released. The
+ * waiter is registered before unlocking, which closes the check-to-wait race
+ * without requiring a permanent descriptor on every Vector. */
+static bool
+vector_wait_once(vector_t *vector, vector_timeout_t *timeout)
+{
+    int descriptors[2];
+    if (pipe(descriptors) != 0) {
+        pthread_mutex_unlock(&vector->lock);
+        rb_sys_fail("pipe");
+    }
+    vector_set_fd_flags(descriptors[0]);
+    vector_set_fd_flags(descriptors[1]);
+
+    vector_wait_context_t context = {
+        .vector = vector,
+        .waiter = {
+            .read_fd = descriptors[0],
+            .write_fd = descriptors[1],
+            .notified = false,
+            .next = vector->waiters,
+        },
+        .timeout = timeout,
+    };
+    vector->waiters = &context.waiter;
+    pthread_mutex_unlock(&vector->lock);
+    return RTEST(rb_ensure(vector_wait_body, (VALUE)&context, vector_wait_cleanup, (VALUE)&context));
+}
+
+static void
+vector_check_reservation_wait_locked(vector_t *vector)
+{
+    if (vector->updating != FARCE_TRANSACTION_RESERVED) return;
+    pthread_mutex_unlock(&vector->lock);
+    VALUE fiber = rb_fiber_current();
+    VALUE thread = rb_thread_current();
+    VALUE scheduler = rb_fiber_scheduler_current();
+    pthread_mutex_lock(&vector->lock);
+    if (vector->updating != FARCE_TRANSACTION_RESERVED) return;
+    if (vector->updating_fiber == fiber ||
+        (vector->updating_thread == thread && NIL_P(scheduler))) {
+        pthread_mutex_unlock(&vector->lock);
+        rb_raise(rb_eThreadError, "deadlock; recursive or unscheduled vector transaction access");
+    }
+}
+
+/* Called with the short mutex held. Return with it held on success. */
+static bool
+vector_wait_for_reservation_locked(vector_t *vector, vector_timeout_t *timeout)
+{
+    while (vector->updating == FARCE_TRANSACTION_RESERVED) {
+        vector_check_reservation_wait_locked(vector);
+        if (vector->updating != FARCE_TRANSACTION_RESERVED) break;
+        if (!vector_wait_once(vector, timeout) && timeout->finite) return false;
+        pthread_mutex_lock(&vector->lock);
+    }
+    return true;
+}
+
+static void
+vector_read_lock(vector_t *vector)
+{
+    vector_timeout_t timeout = {.finite = false, .deadline = 0};
+    pthread_mutex_lock(&vector->lock);
+    (void)vector_wait_for_reservation_locked(vector, &timeout);
+}
+
+static VALUE
+vector_freeze(VALUE self)
+{
+    vector_t *vector;
+    TypedData_Get_Struct(self, vector_t, &vector_type, vector);
+    vector_read_lock(vector);
+    rb_obj_freeze(self);
+    pthread_mutex_unlock(&vector->lock);
+    return self;
+}
+
+/* Returns with vector->lock held on success and released on timeout. */
+static bool
+vector_lock_for_update(vector_t *vector, vector_timeout_t *timeout)
+{
+    for (;;) {
+        pthread_mutex_lock(&vector->lock);
+        if (!vector->updating) return true;
+        vector_check_reservation_wait_locked(vector);
+        if (!vector->updating) return true;
+        if (!vector_wait_once(vector, timeout)) return false;
+    }
+}
+
+static long long
+vector_convert_index(VALUE value)
+{
+    return NUM2LL(value);
+}
+
+static bool
+vector_lookup_index(vector_t *vector, long long raw, size_t *index)
+{
+    if (raw < 0) {
+        unsigned long long distance = (unsigned long long)(-(raw + 1)) + 1;
+        if (distance > vector->size) return false;
+        *index = vector->size - (size_t)distance;
+        return true;
+    }
+    if ((unsigned long long)raw >= vector->size) return false;
+    *index = (size_t)raw;
+    return true;
+}
+
+/* Called with the lock held. Raises only after releasing it. */
+static size_t
+vector_assignment_index(vector_t *vector, long long raw)
+{
+    if (raw < 0) {
+        unsigned long long distance = (unsigned long long)(-(raw + 1)) + 1;
+        if (distance > vector->size) {
+            pthread_mutex_unlock(&vector->lock);
+            rb_raise(rb_eIndexError, "index %lld too small for vector; minimum: -%zu", raw, vector->size);
+        }
+        return vector->size - (size_t)distance;
+    }
+    if ((unsigned long long)raw >= SIZE_MAX) {
+        pthread_mutex_unlock(&vector->lock);
+        rb_raise(rb_eIndexError, "index %lld too large", raw);
+    }
+    return (size_t)raw;
+}
+
+static VALUE
+vector_initialize(int argc, VALUE *argv, VALUE self)
+{
+    VALUE source = Qnil;
+    VALUE keywords = Qnil;
+    VALUE identity = Qundef;
+    ID keyword_ids[] = {rb_intern("compare_by_identity")};
+    VALUE keyword_values[1];
+    vector_t *vector;
+
+    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];
+    }
+    TypedData_Get_Struct(self, vector_t, &vector_type, vector);
+    if (vector->initialized) rb_raise(rb_eRuntimeError, "Vector is already initialized");
+
+    vector->compare_by_identity = identity == Qundef
+        ? false
+        : containers_strict_bool(identity, "compare_by_identity");
+
+    size_t size = 0;
+    if (!NIL_P(source)) {
+        Check_Type(source, T_ARRAY);
+        size = (size_t)RARRAY_LEN(source);
+    }
+    size_t capacity = size > VECTOR_INITIAL_CAPACITY ? size : VECTOR_INITIAL_CAPACITY;
+    vector->values = vector_allocate_values(capacity);
+    if (!vector->values) rb_memerror();
+    vector->capacity = capacity;
+
+    for (size_t index = 0; index < size; index++) {
+        VALUE value = RARRAY_AREF(source, (long)index);
+        containers_check_shareable(value);
+        vector->values[index] = value;
+    }
+    vector->size = size;
+    vector->initialized = true;
+    return containers_publish_native_with_references(self, vector_validate_references);
+}
+
+static VALUE
+vector_snapshot_locked(VALUE self)
+{
+    vector_t *vector = get_vector(self);
+    return rb_ary_new_from_values((long)vector->size, vector->values);
+}
+
+static VALUE
+vector_snapshot_unlock(VALUE self)
+{
+    pthread_mutex_unlock(&get_vector(self)->lock);
+    return Qnil;
+}
+
+static VALUE
+vector_snapshot(VALUE self)
+{
+    vector_read_lock(get_vector(self));
+    return rb_ensure(vector_snapshot_locked, self, vector_snapshot_unlock, self);
+}
+
+static VALUE
+vector_size(VALUE self)
+{
+    vector_t *vector = get_vector(self);
+    size_t size;
+    vector_read_lock(vector);
+    size = vector->size;
+    pthread_mutex_unlock(&vector->lock);
+    return SIZET2NUM(size);
+}
+
+/* Never retain a backing-buffer pointer or hold the lock across a Ruby yield. */
+static VALUE
+vector_each(VALUE self)
+{
+    RETURN_ENUMERATOR(self, 0, NULL);
+    vector_t *vector = get_vector(self);
+    vector_read_lock(vector);
+    size_t limit = vector->size;
+    pthread_mutex_unlock(&vector->lock);
+
+    for (size_t index = 0; index < limit; index++) {
+        vector_read_lock(vector);
+        if (index >= vector->size) {
+            pthread_mutex_unlock(&vector->lock);
+            break;
+        }
+        VALUE value = vector->values[index];
+        pthread_mutex_unlock(&vector->lock);
+        rb_yield(value);
+    }
+    return self;
+}
+
+static VALUE
+vector_reverse_each(VALUE self)
+{
+    RETURN_ENUMERATOR(self, 0, NULL);
+    vector_t *vector = get_vector(self);
+    vector_read_lock(vector);
+    size_t index = vector->size;
+    pthread_mutex_unlock(&vector->lock);
+
+    while (index > 0) {
+        vector_read_lock(vector);
+        if (index > vector->size) index = vector->size;
+        if (index == 0) {
+            pthread_mutex_unlock(&vector->lock);
+            break;
+        }
+        VALUE value = vector->values[--index];
+        pthread_mutex_unlock(&vector->lock);
+        rb_yield(value);
+    }
+    return self;
+}
+
+static VALUE
+vector_fetch(VALUE self, VALUE index_value)
+{
+    vector_t *vector = get_vector(self);
+    long long raw = vector_convert_index(index_value);
+    size_t index;
+    vector_read_lock(vector);
+    bool found = vector_lookup_index(vector, raw, &index);
+    VALUE result = found ? vector->values[index] : Qnil;
+    pthread_mutex_unlock(&vector->lock);
+    if (found) return result;
+    if (rb_block_given_p()) return rb_yield(index_value);
+    rb_raise(rb_eIndexError, "index %lld outside of vector bounds", raw);
+}
+
+static VALUE
+vector_compare_by_identity_p(VALUE self)
+{
+    return get_vector(self)->compare_by_identity ? Qtrue : Qfalse;
+}
+
+static VALUE
+vector_get_fast(VALUE self, VALUE index_value)
+{
+    vector_t *vector = get_vector(self);
+    long long raw = vector_convert_index(index_value);
+    size_t index;
+    VALUE result = Qnil;
+    vector_read_lock(vector);
+    if (vector_lookup_index(vector, raw, &index)) result = vector->values[index];
+    pthread_mutex_unlock(&vector->lock);
+    return result;
+}
+
+static VALUE
+vector_get(int argc, VALUE *argv, VALUE self)
+{
+    VALUE index_value;
+    VALUE keywords = Qnil;
+    rb_scan_args(argc, argv, "1:", &index_value, &keywords);
+    long long raw = vector_convert_index(index_value);
+    vector_timeout_t timeout = vector_parse_timeout(vector_timeout_keyword(keywords));
+    vector_t *vector = get_vector(self);
+
+    if (!vector_lock_for_update(vector, &timeout)) return Qnil;
+    size_t index;
+    VALUE result = vector_lookup_index(vector, raw, &index) ? vector->values[index] : Qnil;
+    pthread_mutex_unlock(&vector->lock);
+    return result;
+}
+
+static VALUE
+vector_store_internal(VALUE self, vector_t *vector, long long raw, VALUE value, vector_timeout_t *timeout)
+{
+    rb_check_frozen(self);
+    if (!vector_lock_for_update(vector, timeout)) return Qfalse;
+    size_t index = vector_assignment_index(vector, raw);
+    if (!vector_ensure_capacity(vector, index + 1)) {
+        pthread_mutex_unlock(&vector->lock);
+        rb_memerror();
+    }
+    if (index >= vector->size) vector->size = index + 1;
+    vector->values[index] = value;
+    vector_notify_waiters_locked(vector);
+    pthread_mutex_unlock(&vector->lock);
+    return value;
+}
+
+static VALUE
+vector_set_fast(VALUE self, VALUE index_value, VALUE value)
+{
+    vector_t *vector = get_vector(self);
+    rb_check_frozen(self);
+    long long raw = vector_convert_index(index_value);
+    rb_check_frozen(self);
+    vector_timeout_t timeout = {.finite = false, .deadline = 0};
+    containers_check_shareable(value);
+    return vector_store_internal(self, vector, raw, value, &timeout);
+}
+
+static VALUE
+vector_store(int argc, VALUE *argv, VALUE self)
+{
+    VALUE index_value;
+    VALUE value;
+    VALUE keywords = Qnil;
+    rb_scan_args(argc, argv, "2:", &index_value, &value, &keywords);
+    rb_check_frozen(self);
+    long long raw = vector_convert_index(index_value);
+    vector_timeout_t timeout = vector_parse_timeout(vector_timeout_keyword(keywords));
+    rb_check_frozen(self);
+    vector_t *vector = get_vector(self);
+    containers_check_shareable(value);
+    return vector_store_internal(self, vector, raw, value, &timeout);
+}
+
+static VALUE
+vector_clear(VALUE self)
+{
+    vector_t *vector = get_vector(self);
+    rb_check_frozen(self);
+    vector_timeout_t timeout = {.finite = false, .deadline = 0};
+    (void)vector_lock_for_update(vector, &timeout);
+    for (size_t index = 0; index < vector->size; index++) vector->values[index] = Qnil;
+    vector->size = 0;
+    vector_notify_waiters_locked(vector);
+    pthread_mutex_unlock(&vector->lock);
+    return self;
+}
+
+static VALUE
+vector_push(int argc, VALUE *argv, VALUE self)
+{
+    VALUE value;
+    VALUE keywords = Qnil;
+    rb_scan_args(argc, argv, "1:", &value, &keywords);
+    rb_check_frozen(self);
+    vector_timeout_t timeout = vector_parse_timeout(vector_timeout_keyword(keywords));
+    rb_check_frozen(self);
+    vector_t *vector = get_vector(self);
+    containers_check_shareable(value);
+
+    if (!vector_lock_for_update(vector, &timeout)) return Qfalse;
+    if (vector->size == SIZE_MAX || !vector_ensure_capacity(vector, vector->size + 1)) {
+        pthread_mutex_unlock(&vector->lock);
+        rb_memerror();
+    }
+    vector->values[vector->size++] = value;
+    vector_notify_waiters_locked(vector);
+    pthread_mutex_unlock(&vector->lock);
+    return self;
+}
+
+static VALUE
+vector_pop(int argc, VALUE *argv, VALUE self)
+{
+    VALUE keywords = Qnil;
+    rb_scan_args(argc, argv, "0:", &keywords);
+    rb_check_frozen(self);
+    vector_timeout_t timeout = vector_parse_timeout(vector_timeout_keyword(keywords));
+    rb_check_frozen(self);
+    vector_t *vector = get_vector(self);
+
+    if (!vector_lock_for_update(vector, &timeout)) return Qnil;
+    VALUE result = Qnil;
+    if (vector->size > 0) {
+        size_t index = --vector->size;
+        result = vector->values[index];
+        vector->values[index] = Qnil;
+        vector_notify_waiters_locked(vector);
+    }
+    pthread_mutex_unlock(&vector->lock);
+    return result;
+}
+
+static VALUE
+vector_swap(int argc, VALUE *argv, VALUE self)
+{
+    VALUE index_value;
+    VALUE replacement;
+    VALUE keywords = Qnil;
+    rb_scan_args(argc, argv, "2:", &index_value, &replacement, &keywords);
+    rb_check_frozen(self);
+    long long raw = vector_convert_index(index_value);
+    vector_timeout_t timeout = vector_parse_timeout(vector_timeout_keyword(keywords));
+    rb_check_frozen(self);
+    vector_t *vector = get_vector(self);
+    containers_check_shareable(replacement);
+
+    if (!vector_lock_for_update(vector, &timeout)) return Qnil;
+    size_t index = vector_assignment_index(vector, raw);
+    if (!vector_ensure_capacity(vector, index + 1)) {
+        pthread_mutex_unlock(&vector->lock);
+        rb_memerror();
+    }
+    VALUE previous = index < vector->size ? vector->values[index] : Qnil;
+    if (index >= vector->size) vector->size = index + 1;
+    vector->values[index] = replacement;
+    vector_notify_waiters_locked(vector);
+    pthread_mutex_unlock(&vector->lock);
+    return previous;
+}
+
+typedef struct {
+    VALUE self;
+    vector_t *vector;
+    size_t index;
+    VALUE current;
+    VALUE argument;
+    VALUE replacement;
+    bool identity;
+    bool complete;
+} vector_operation_t;
+
+static VALUE
+vector_operation_cleanup(VALUE opaque)
+{
+    vector_operation_t *operation = (vector_operation_t *)opaque;
+    if (!operation->complete) {
+        pthread_mutex_lock(&operation->vector->lock);
+        vector_finish_update_locked(operation->vector);
+        pthread_mutex_unlock(&operation->vector->lock);
+    }
+    return Qnil;
+}
+
+static VALUE
+vector_store_if_absent_body(VALUE opaque)
+{
+    vector_operation_t *operation = (vector_operation_t *)opaque;
+    VALUE result = rb_yield_values(0);
+    rb_check_frozen(operation->self);
+    containers_check_shareable(result);
+    pthread_mutex_lock(&operation->vector->lock);
+    if (operation->index >= operation->vector->size) {
+        operation->vector->size = operation->index + 1;
+    }
+    operation->vector->values[operation->index] = result;
+    vector_finish_update_locked(operation->vector);
+    pthread_mutex_unlock(&operation->vector->lock);
+    operation->complete = true;
+    return result;
+}
+
+static VALUE
+vector_store_if_absent(int argc, VALUE *argv, VALUE self)
+{
+    VALUE index_value;
+    VALUE keywords = Qnil;
+    rb_scan_args(argc, argv, "1:", &index_value, &keywords);
+    rb_check_frozen(self);
+    long long raw = vector_convert_index(index_value);
+    vector_timeout_t timeout = vector_parse_timeout(vector_timeout_keyword(keywords));
+    rb_check_frozen(self);
+    vector_t *vector = get_vector(self);
+    rb_need_block();
+
+    if (!vector_lock_for_update(vector, &timeout)) return Qnil;
+    size_t index = vector_assignment_index(vector, raw);
+    if (!vector_ensure_capacity(vector, index + 1)) {
+        pthread_mutex_unlock(&vector->lock);
+        rb_memerror();
+    }
+    if (index < vector->size && !NIL_P(vector->values[index])) {
+        VALUE value = vector->values[index];
+        pthread_mutex_unlock(&vector->lock);
+        return value;
+    }
+
+    vector_operation_t operation = {
+        .self = self,
+        .vector = vector,
+        .index = index,
+        .complete = false,
+    };
+    vector->updating = true;
+    pthread_mutex_unlock(&vector->lock);
+    return rb_ensure(
+        vector_store_if_absent_body,
+        (VALUE)&operation,
+        vector_operation_cleanup,
+        (VALUE)&operation
+    );
+}
+
+static VALUE
+vector_cas_body(VALUE opaque)
+{
+    vector_operation_t *operation = (vector_operation_t *)opaque;
+    bool matches = operation->identity
+        ? operation->current == operation->argument
+        : RTEST(rb_equal(operation->current, operation->argument));
+    rb_check_frozen(operation->self);
+
+    pthread_mutex_lock(&operation->vector->lock);
+    if (matches) operation->vector->values[operation->index] = operation->replacement;
+    vector_finish_update_locked(operation->vector);
+    pthread_mutex_unlock(&operation->vector->lock);
+    operation->complete = true;
+    return matches ? Qtrue : Qfalse;
+}
+
+static VALUE
+vector_compare_and_set(int argc, VALUE *argv, VALUE self)
+{
+    VALUE index_value;
+    VALUE expected;
+    VALUE replacement;
+    VALUE keywords = Qnil;
+    rb_scan_args(argc, argv, "3:", &index_value, &expected, &replacement, &keywords);
+    rb_check_frozen(self);
+    long long raw = vector_convert_index(index_value);
+    vector_timeout_t timeout = vector_parse_timeout(vector_timeout_keyword(keywords));
+    rb_check_frozen(self);
+    vector_t *vector = get_vector(self);
+    containers_check_shareable(expected);
+    containers_check_shareable(replacement);
+
+    if (!vector_lock_for_update(vector, &timeout)) return Qfalse;
+    size_t index;
+    if (!vector_lookup_index(vector, raw, &index)) {
+        pthread_mutex_unlock(&vector->lock);
+        return Qfalse;
+    }
+    vector_operation_t operation = {
+        .self = self,
+        .vector = vector,
+        .index = index,
+        .current = vector->values[index],
+        .argument = expected,
+        .replacement = replacement,
+        .identity = vector->compare_by_identity,
+        .complete = false,
+    };
+    vector->updating = true;
+    pthread_mutex_unlock(&vector->lock);
+    return rb_ensure(vector_cas_body, (VALUE)&operation, vector_operation_cleanup, (VALUE)&operation);
+}
+
+static VALUE
+vector_upsert_body(VALUE opaque)
+{
+    vector_operation_t *operation = (vector_operation_t *)opaque;
+    VALUE result = rb_yield(operation->current);
+    rb_check_frozen(operation->self);
+    containers_check_shareable(result);
+    pthread_mutex_lock(&operation->vector->lock);
+    operation->vector->values[operation->index] = result;
+    vector_finish_update_locked(operation->vector);
+    pthread_mutex_unlock(&operation->vector->lock);
+    operation->complete = true;
+    return result;
+}
+
+static VALUE
+vector_upsert(int argc, VALUE *argv, VALUE self)
+{
+    VALUE index_value;
+    VALUE initial;
+    VALUE keywords = Qnil;
+    rb_scan_args(argc, argv, "2:", &index_value, &initial, &keywords);
+    rb_check_frozen(self);
+    long long raw = vector_convert_index(index_value);
+    vector_timeout_t timeout = vector_parse_timeout(vector_timeout_keyword(keywords));
+    rb_check_frozen(self);
+    vector_t *vector = get_vector(self);
+    containers_check_shareable(initial);
+    rb_need_block();
+
+    if (!vector_lock_for_update(vector, &timeout)) return Qnil;
+    size_t index = vector_assignment_index(vector, raw);
+    if (!vector_ensure_capacity(vector, index + 1)) {
+        pthread_mutex_unlock(&vector->lock);
+        rb_memerror();
+    }
+    if (index >= vector->size) vector->size = index + 1;
+    if (NIL_P(vector->values[index])) {
+        vector->values[index] = initial;
+        vector_notify_waiters_locked(vector);
+        pthread_mutex_unlock(&vector->lock);
+        return initial;
+    }
+
+    vector_operation_t operation = {
+        .self = self,
+        .vector = vector,
+        .index = index,
+        .current = vector->values[index],
+        .complete = false,
+    };
+    vector->updating = true;
+    pthread_mutex_unlock(&vector->lock);
+    return rb_ensure(vector_upsert_body, (VALUE)&operation, vector_operation_cleanup, (VALUE)&operation);
+}
+
+static VALUE
+vector_update_body(VALUE opaque)
+{
+    vector_operation_t *operation = (vector_operation_t *)opaque;
+    VALUE result = rb_yield(operation->current);
+    rb_check_frozen(operation->self);
+    containers_check_shareable(result);
+    pthread_mutex_lock(&operation->vector->lock);
+    if (operation->index >= operation->vector->size) {
+        operation->vector->size = operation->index + 1;
+    }
+    operation->vector->values[operation->index] = result;
+    vector_finish_update_locked(operation->vector);
+    pthread_mutex_unlock(&operation->vector->lock);
+    operation->complete = true;
+    return result;
+}
+
+static VALUE
+vector_update(int argc, VALUE *argv, VALUE self)
+{
+    VALUE index_value;
+    VALUE keywords = Qnil;
+    rb_scan_args(argc, argv, "1:", &index_value, &keywords);
+    rb_check_frozen(self);
+    long long raw = vector_convert_index(index_value);
+    vector_timeout_t timeout = vector_parse_timeout(vector_timeout_keyword(keywords));
+    rb_check_frozen(self);
+    vector_t *vector = get_vector(self);
+    rb_need_block();
+
+    if (!vector_lock_for_update(vector, &timeout)) return Qnil;
+    size_t index = vector_assignment_index(vector, raw);
+    if (!vector_ensure_capacity(vector, index + 1)) {
+        pthread_mutex_unlock(&vector->lock);
+        rb_memerror();
+    }
+
+    vector_operation_t operation = {
+        .self = self,
+        .vector = vector,
+        .index = index,
+        .current = index < vector->size ? vector->values[index] : Qnil,
+        .complete = false,
+    };
+    vector->updating = true;
+    pthread_mutex_unlock(&vector->lock);
+    return rb_ensure(vector_update_body, (VALUE)&operation, vector_operation_cleanup, (VALUE)&operation);
+}
+
+static bool
+vector_values_equal(vector_t *vector, VALUE left, VALUE right)
+{
+    return vector->compare_by_identity ? left == right : RTEST(rb_equal(left, right));
+}
+
+static VALUE
+vector_wait_until_changed(int argc, VALUE *argv, VALUE self)
+{
+    VALUE index_value;
+    VALUE expected;
+    VALUE keywords = Qnil;
+    rb_scan_args(argc, argv, "2:", &index_value, &expected, &keywords);
+    long long raw = vector_convert_index(index_value);
+    vector_timeout_t timeout = vector_parse_timeout(vector_timeout_keyword(keywords));
+    vector_t *vector = get_vector(self);
+    containers_check_shareable(expected);
+
+    for (;;) {
+        uint64_t generation;
+        size_t index;
+        pthread_mutex_lock(&vector->lock);
+        if (!vector_wait_for_reservation_locked(vector, &timeout)) return Qnil;
+        VALUE current = vector_lookup_index(vector, raw, &index) ? vector->values[index] : Qnil;
+        generation = vector->generation;
+        pthread_mutex_unlock(&vector->lock);
+
+        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->generation != generation) {
+            pthread_mutex_unlock(&vector->lock);
+            continue;
+        }
+        if (!vector_wait_once(vector, &timeout)) return Qnil;
+    }
+}
+
+static VALUE
+vector_wait_until_non_nil(int argc, VALUE *argv, VALUE self)
+{
+    VALUE index_value;
+    VALUE keywords = Qnil;
+    rb_scan_args(argc, argv, "1:", &index_value, &keywords);
+    long long raw = vector_convert_index(index_value);
+    vector_timeout_t timeout = vector_parse_timeout(vector_timeout_keyword(keywords));
+    vector_t *vector = get_vector(self);
+
+    for (;;) {
+        pthread_mutex_lock(&vector->lock);
+        if (!vector_wait_for_reservation_locked(vector, &timeout)) return Qnil;
+        size_t index;
+        VALUE current = vector_lookup_index(vector, raw, &index) ? vector->values[index] : Qnil;
+        if (!NIL_P(current)) {
+            pthread_mutex_unlock(&vector->lock);
+            return current;
+        }
+        if (!vector_wait_once(vector, &timeout)) return Qnil;
+    }
+}
+
+static VALUE
+unshared_vector_capture_values(VALUE self)
+{
+    return rb_ivar_get(self, vector_values_id);
+}
+
+static VALUE
+unshared_vector_read_values(VALUE self)
+{
+    if (rb_ivar_get(self, vector_updating_id) == vector_transaction_marker) {
+        VALUE mutex = rb_ivar_get(self, vector_mutex_id);
+        return rb_mutex_synchronize(mutex, unshared_vector_capture_values, self);
+    }
+    return unshared_vector_capture_values(self);
+}
+
+/* An unshared Array is confined to one Ractor. Its reads run under that
+ * Ractor's GVL, so no Ruby mutex is needed between yields on CRuby. */
+static VALUE
+unshared_vector_each(VALUE self)
+{
+    RETURN_ENUMERATOR(self, 0, NULL);
+    VALUE values = unshared_vector_read_values(self);
+    Check_Type(values, T_ARRAY);
+    long limit = RARRAY_LEN(values);
+    for (long index = 0; index < limit && index < RARRAY_LEN(values); index++) {
+        rb_yield(RARRAY_AREF(values, index));
+    }
+    RB_GC_GUARD(values);
+    return self;
+}
+
+static VALUE
+unshared_vector_reverse_each(VALUE self)
+{
+    RETURN_ENUMERATOR(self, 0, NULL);
+    VALUE values = unshared_vector_read_values(self);
+    Check_Type(values, T_ARRAY);
+    long index = RARRAY_LEN(values);
+    while (index > 0) {
+        if (index > RARRAY_LEN(values)) index = RARRAY_LEN(values);
+        if (index == 0) break;
+        rb_yield(RARRAY_AREF(values, --index));
+    }
+    RB_GC_GUARD(values);
+    return self;
+}
+
+static bool
+vector_transaction_valid(farce_transaction_entry_t *entry)
+{
+    vector_t *vector = entry->source_data;
+    return vector->generation == entry->version && !vector->updating;
+}
+
+static void
+vector_transaction_apply(farce_transaction_entry_t *entry)
+{
+    vector_t *vector = entry->source_data;
+    vector_t *copy = entry->working_data;
+    VALUE *values = vector->values;
+    size_t capacity = vector->capacity, size = vector->size;
+    vector->values = copy->values;
+    vector->capacity = copy->capacity;
+    vector->size = copy->size;
+    copy->values = values;
+    copy->capacity = capacity;
+    copy->size = size;
+}
+
+static void
+vector_transaction_notify(farce_transaction_entry_t *entry)
+{
+    vector_notify_waiters_locked(entry->source_data);
+}
+
+static void
+vector_transaction_reserve(farce_transaction_entry_t *entry, VALUE fiber, VALUE thread)
+{
+    vector_t *vector = entry->source_data;
+    vector->updating = FARCE_TRANSACTION_RESERVED;
+    vector->updating_fiber = fiber;
+    vector->updating_thread = thread;
+}
+
+static void
+vector_transaction_release(farce_transaction_entry_t *entry)
+{
+    vector_t *vector = entry->source_data;
+    vector->updating_fiber = Qnil;
+    vector->updating_thread = Qnil;
+    vector_finish_update_locked(vector);
+}
+
+static const farce_transaction_ops_t vector_transaction_ops = {
+    vector_transaction_valid, vector_transaction_apply, vector_transaction_notify,
+    vector_transaction_reserve, vector_transaction_release,
+};
+
+static VALUE
+vector_transaction_snapshot(VALUE self)
+{
+    vector_t *source = get_vector(self);
+    VALUE working = vector_allocate(cVector);
+    vector_t *copy;
+    TypedData_Get_Struct(working, vector_t, &vector_type, copy);
+    farce_transaction_entry_t *entry;
+    VALUE result = farce_transaction_entry_new(
+        self, working, source, copy, &source->lock, &vector_transaction_ops, &entry
+    );
+    pthread_mutex_lock(&source->lock);
+    copy->values = malloc(source->capacity * sizeof(VALUE));
+    if (!copy->values) {
+        pthread_mutex_unlock(&source->lock);
+        rb_memerror();
+    }
+    memcpy(copy->values, source->values, source->size * sizeof(VALUE));
+    for (size_t i = source->size; i < source->capacity; i++) copy->values[i] = Qnil;
+    copy->capacity = source->capacity;
+    copy->size = source->size;
+    copy->compare_by_identity = source->compare_by_identity;
+    copy->initialized = true;
+    entry->version = source->generation;
+    pthread_mutex_unlock(&source->lock);
+    return result;
+}
+
+void
+containers_init_vector(VALUE namespace)
+{
+    vector_values_id = rb_intern("@values");
+    vector_updating_id = rb_intern("@updating");
+    vector_mutex_id = rb_intern("@mutex");
+    vector_transaction_marker = ID2SYM(rb_intern("transaction"));
+    VALUE iteration = rb_define_module_under(namespace, "UnsharedVectorIteration");
+    rb_define_method(iteration, "each", unshared_vector_each, 0);
+    rb_define_method(iteration, "reverse_each", unshared_vector_reverse_each, 0);
+
+    cVector = rb_define_class_under(namespace, "Vector", rb_cObject);
+    rb_define_alloc_func(cVector, vector_allocate);
+    rb_define_method(cVector, "freeze", vector_freeze, 0);
+    rb_define_method(cVector, "initialize", vector_initialize, -1);
+    rb_define_method(cVector, "size", vector_size, 0);
+    rb_define_method(cVector, "snapshot", vector_snapshot, 0);
+    rb_define_method(cVector, "each", vector_each, 0);
+    rb_define_method(cVector, "reverse_each", vector_reverse_each, 0);
+    rb_define_method(cVector, "fetch", vector_fetch, 1);
+    rb_define_method(cVector, "clear", vector_clear, 0);
+    rb_define_method(cVector, "[]", vector_get_fast, 1);
+    rb_define_method(cVector, "[]=", vector_set_fast, 2);
+    rb_define_method(cVector, "get", vector_get, -1);
+    rb_define_method(cVector, "store", vector_store, -1);
+    rb_define_method(cVector, "push", vector_push, -1);
+    rb_define_method(cVector, "pop", vector_pop, -1);
+    rb_define_method(cVector, "swap", vector_swap, -1);
+    rb_define_method(cVector, "store_if_absent", vector_store_if_absent, -1);
+    rb_define_method(cVector, "transaction_snapshot", vector_transaction_snapshot, 0);
+    rb_define_method(cVector, "compare_and_set", vector_compare_and_set, -1);
+    rb_define_method(cVector, "upsert", vector_upsert, -1);
+    rb_define_method(cVector, "update", vector_update, -1);
+    rb_define_method(cVector, "wait_until_changed", vector_wait_until_changed, -1);
+    rb_define_method(cVector, "wait_until_non_nil", vector_wait_until_non_nil, -1);
+    rb_define_method(cVector, "compare_by_identity?", vector_compare_by_identity_p, 0);
+}