ractor-sharing 0.2.0 → 0.3.0

data/ext/ractor/lock/keylockhash.c

@@ -0,0 +1,445 @@
+#include "lock.h"
+#include "ruby/st.h"
+
+/* Ractor::KeyLockHash - a hash with one lock per key, near enough.
+ *
+ * Ractor::LockHash is the table lock: one lock over the whole hash, so a
+ * section is atomic across its keys and unrelated keys wait for each other.
+ * This is the row lock: an update touches one key under one lock, and updates
+ * to unrelated keys run in parallel.  Nothing here is atomic across two keys;
+ * that is LockHash's job (or Ractor::TVar's).
+ *
+ * "Near enough": the implementation is sharded, the textbook name is lock
+ * striping.  Keys hash onto a fixed number of shards, each a table with a lock
+ * of its own, so two keys sometimes share a lock.  That costs a collision now
+ * and then and buys freedom from per-entry lock lifetime problems.
+ *
+ * A plain write is []=, with no ceremony: one key's write is atomic on its
+ * own.  #update exists for one reason only, computing the new value from the
+ * old one, read and stored under the same hold of that key's lock; its block
+ * runs exactly once.  The claim idiom falls out: whether the block saw nil
+ * tells you whether you won.
+ *
+ *     mine = false
+ *     m.update(id) {|v| v ? v : (mine = true; :claimed) }
+ */
+
+#define KLH_NSHARDS 64
+
+static VALUE rb_cRactorKeyLockHash;
+static ID id_plus;
+
+struct klh_shard {
+    st_table *tbl;              /* shareable VALUE => shareable VALUE */
+    struct rs_lock lock;
+};
+
+struct keylockhash {
+    struct klh_shard shards[KLH_NSHARDS];
+};
+
+static st_index_t
+klh_key_hash(st_data_t key)
+{
+    return (st_index_t)NUM2LONG(rb_hash((VALUE)key));
+}
+
+static int
+klh_key_cmp(st_data_t a, st_data_t b)
+{
+    return rb_eql((VALUE)a, (VALUE)b) ? 0 : 1;
+}
+
+static const struct st_hash_type klh_type = { klh_key_cmp, klh_key_hash };
+
+static int
+klh_mark_i(st_data_t key, st_data_t value, st_data_t arg)
+{
+    rb_gc_mark((VALUE)key);
+    rb_gc_mark((VALUE)value);
+    return ST_CONTINUE;
+}
+
+static void
+klh_mark(void *ptr)
+{
+    struct keylockhash *kh = ptr;
+    for (int i = 0; i < KLH_NSHARDS; i++) {
+        st_foreach(kh->shards[i].tbl, klh_mark_i, 0);
+    }
+}
+
+static void
+klh_free(void *ptr)
+{
+    struct keylockhash *kh = ptr;
+    for (int i = 0; i < KLH_NSHARDS; i++) {
+        st_free_table(kh->shards[i].tbl);
+        rs_lock_destroy(&kh->shards[i].lock);
+    }
+    ruby_xfree(kh);
+}
+
+static size_t
+klh_memsize(const void *ptr)
+{
+    const struct keylockhash *kh = ptr;
+    size_t n = sizeof(struct keylockhash);
+    for (int i = 0; i < KLH_NSHARDS; i++) n += st_memsize(kh->shards[i].tbl);
+    return n;
+}
+
+static const rb_data_type_t klh_data_type = {
+    "Ractor::KeyLockHash",
+    {klh_mark, klh_free, klh_memsize, NULL},
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_FROZEN_SHAREABLE
+};
+
+static struct keylockhash *
+klh_ptr(VALUE self)
+{
+    struct keylockhash *kh;
+    TypedData_Get_Struct(self, struct keylockhash, &klh_data_type, kh);
+    return kh;
+}
+
+static void
+klh_check_shareable(VALUE val)
+{
+    if (RB_UNLIKELY(!rb_ractor_shareable_p(val))) {
+        rb_raise(rb_eArgError, "only shareable object are allowed");
+    }
+}
+
+/* The key's #hash runs here, outside every lock. */
+static struct klh_shard *
+klh_shard_for(VALUE self, VALUE key)
+{
+    unsigned long h = (unsigned long)NUM2LONG(rb_hash(key));
+    return &klh_ptr(self)->shards[h % KLH_NSHARDS];
+}
+
+static VALUE
+klh_alloc(VALUE klass)
+{
+    struct keylockhash *kh;
+    VALUE obj = TypedData_Make_Struct(klass, struct keylockhash, &klh_data_type, kh);
+    for (int i = 0; i < KLH_NSHARDS; i++) {
+        kh->shards[i].tbl = st_init_table(&klh_type);
+        rs_lock_init(&kh->shards[i].lock);
+    }
+    return obj;
+}
+
+static int
+klh_copy_pair(VALUE key, VALUE value, VALUE selfv)
+{
+    key = rs_hash_key(key);
+    klh_check_shareable(key);
+    value = rs_shareable_value(value);
+    /* single-threaded: nobody else has seen self yet */
+    st_insert(klh_shard_for((VALUE)selfv, key)->tbl, (st_data_t)key, (st_data_t)value);
+    return ST_CONTINUE;
+}
+
+static VALUE
+klh_initialize(int argc, VALUE *argv, VALUE self)
+{
+    VALUE init = Qnil;
+    rb_check_frozen(self);   /* send(:initialize) again would write past the locks */
+    rb_scan_args(argc, argv, "01", &init);
+    if (!NIL_P(init)) {
+        Check_Type(init, T_HASH);
+        rb_hash_foreach(init, klh_copy_pair, self);
+    }
+    rb_obj_freeze(self);
+    rb_ractor_make_shareable(self);
+    return self;
+}
+
+/* --- guarded bodies ------------------------------------------------------- */
+
+struct klh_op {
+    struct klh_shard *shard;
+    VALUE key;
+    VALUE value;
+};
+
+static VALUE
+klh_lookup_body(VALUE ptr)
+{
+    struct rs_guard_arg *arg = (struct rs_guard_arg *)ptr;
+    struct klh_op *op = arg->data;
+    st_data_t found;
+
+    if (st_lookup(op->shard->tbl, (st_data_t)op->key, &found)) return (VALUE)found;
+    return Qundef;
+}
+
+static VALUE
+klh_update_body(VALUE ptr)
+{
+    struct rs_guard_arg *arg = (struct rs_guard_arg *)ptr;
+    struct klh_op *op = arg->data;
+    st_data_t found;
+    VALUE old = Qnil, next;
+
+    if (st_lookup(op->shard->tbl, (st_data_t)op->key, &found)) old = (VALUE)found;
+    next = rs_shareable_value(rb_yield(old));
+    st_insert(op->shard->tbl, (st_data_t)op->key, (st_data_t)next);
+    return next;
+}
+
+/* (old or 0) + amount, stored under the key's lock.  A missing key counts as
+ * zero, the way ActorHash#increment counts it: the tally shape needs no
+ * seeding.  Fixnums that stay Fixnums skip the dispatch. */
+static VALUE
+klh_increment_body(VALUE ptr)
+{
+    struct rs_guard_arg *arg = (struct rs_guard_arg *)ptr;
+    struct klh_op *op = arg->data;
+    st_data_t found;
+    VALUE old = INT2FIX(0), next;
+
+    if (st_lookup(op->shard->tbl, (st_data_t)op->key, &found)) old = (VALUE)found;
+    next = rs_fixnum_add(old, op->value);
+    if (RB_UNDEF_P(next)) {
+        next = rs_shareable_value(rb_funcall(old, id_plus, 1, op->value));
+    }
+    st_insert(op->shard->tbl, (st_data_t)op->key, (st_data_t)next);
+    return next;
+}
+
+static VALUE
+klh_aset_body(VALUE ptr)
+{
+    struct rs_guard_arg *arg = (struct rs_guard_arg *)ptr;
+    struct klh_op *op = arg->data;
+
+    st_insert(op->shard->tbl, (st_data_t)op->key, (st_data_t)op->value);
+    return op->value;
+}
+
+static VALUE
+klh_delete_body(VALUE ptr)
+{
+    struct rs_guard_arg *arg = (struct rs_guard_arg *)ptr;
+    struct klh_op *op = arg->data;
+    st_data_t key = (st_data_t)op->key, old;
+
+    if (st_delete(op->shard->tbl, &key, &old)) return (VALUE)old;
+    return Qnil;
+}
+
+static int
+klh_collect_key(st_data_t key, st_data_t value, st_data_t ary)
+{
+    rb_ary_push((VALUE)ary, (VALUE)key);
+    return ST_CONTINUE;
+}
+
+static int
+klh_collect_pair(st_data_t key, st_data_t value, st_data_t hash)
+{
+    rb_hash_aset((VALUE)hash, (VALUE)key, (VALUE)value);
+    return ST_CONTINUE;
+}
+
+static VALUE
+klh_collect_body(VALUE ptr)
+{
+    struct rs_guard_arg *arg = (struct rs_guard_arg *)ptr;
+    struct klh_op *op = arg->data;
+
+    st_foreach(op->shard->tbl, RB_TYPE_P(op->value, T_ARRAY) ? klh_collect_key : klh_collect_pair,
+               (st_data_t)op->value);
+    return Qnil;
+}
+
+/* One key's #hash or #eql? reaching back into this map raises NestedLockError
+ * rather than deadlocking: the inner call may want a shard this thread does
+ * not hold, so unlike LockHash there is no safe reentrant path. */
+#define KLH_GUARDED(self, op, body) \
+    rs_guarded((self), &(op)->shard->lock, (body), (op), false, \
+               "one key is already in hand; two keys together is Ractor::LockHash's job")
+
+/* --- methods -------------------------------------------------------------- */
+
+/*
+ *  call-seq:
+ *     keylockhash[key] -> value or nil
+ *
+ *  Reads one key under that key's shard lock.  Unrelated keys do not wait.
+ */
+static VALUE
+klh_aref(VALUE self, VALUE key)
+{
+    struct klh_op op = { klh_shard_for(self, key), key, Qnil };
+    VALUE found = KLH_GUARDED(self, &op, klh_lookup_body);
+    return RB_UNDEF_P(found) ? Qnil : found;
+}
+
+/*
+ *  call-seq:
+ *     keylockhash.fetch(key)            -> value or KeyError
+ *     keylockhash.fetch(key, default)   -> value or default
+ *     keylockhash.fetch(key) {|k| ... } -> value or block result
+ *
+ *  The default and the block run with the lock released.
+ */
+static VALUE
+klh_fetch(int argc, VALUE *argv, VALUE self)
+{
+    VALUE key, def, found;
+    struct klh_op op;
+
+    rb_check_arity(argc, 1, 2);
+    key = argv[0];
+    def = argc > 1 ? argv[1] : Qundef;
+
+    op.shard = klh_shard_for(self, key);
+    op.key = key;
+    op.value = Qnil;
+    found = KLH_GUARDED(self, &op, klh_lookup_body);
+    if (!RB_UNDEF_P(found)) return found;
+    if (rb_block_given_p()) return rb_yield(key);
+    if (!RB_UNDEF_P(def)) return def;
+    rb_raise(rb_eKeyError, "key not found: %+"PRIsVALUE, key);
+}
+
+static VALUE
+klh_key_p(VALUE self, VALUE key)
+{
+    struct klh_op op = { klh_shard_for(self, key), key, Qnil };
+    return RB_UNDEF_P(KLH_GUARDED(self, &op, klh_lookup_body)) ? Qfalse : Qtrue;
+}
+
+/*
+ *  call-seq:
+ *     keylockhash.update(key) {|value_or_nil| new_value } -> new_value
+ *
+ *  Reads, yields and stores under that key's lock: an atomic
+ *  read-modify-write for one key, and the block runs exactly once.  Yields
+ *  nil for a missing key, so "whether the block saw nil" is "whether you
+ *  created it" -- the put-if-absent idiom needs nothing more.
+ */
+static VALUE
+klh_update(VALUE self, VALUE key)
+{
+    struct klh_op op;
+    rb_need_block();
+    key = rs_hash_key(key);     /* may insert it */
+    klh_check_shareable(key);
+    op = (struct klh_op){ klh_shard_for(self, key), key, Qnil };
+    return KLH_GUARDED(self, &op, klh_update_body);
+}
+
+/*
+ *  call-seq:
+ *     keylockhash.increment(key, by = 1) -> new value
+ *
+ *  Adds +by+ under that key's lock; a missing key counts as zero.  The same
+ *  as <code>update(key) {|v| (v || 0) + by }</code>.
+ */
+static VALUE
+klh_increment(int argc, VALUE *argv, VALUE self)
+{
+    VALUE key, by;
+    struct klh_op op;
+
+    rb_check_arity(argc, 1, 2);
+    key = rs_hash_key(argv[0]);
+    klh_check_shareable(key);   /* may insert it */
+    by = argc < 2 ? INT2FIX(1) : argv[1];
+    op = (struct klh_op){ klh_shard_for(self, key), key, by };
+    return KLH_GUARDED(self, &op, klh_increment_body);
+}
+
+/*
+ *  call-seq:
+ *     keylockhash[key] = value -> value
+ *
+ *  Stores under that key's lock.  No ceremony: a plain write is atomic on its
+ *  own here, because nothing in this class is atomic across two keys anyway.
+ *  Reach for #update only when the new value is computed from the old one.
+ */
+static VALUE
+klh_aset(VALUE self, VALUE key, VALUE value)
+{
+    struct klh_op op;
+
+    key = rs_hash_key(key);
+    klh_check_shareable(key);
+    value = rs_shareable_value(value);
+    op = (struct klh_op){ klh_shard_for(self, key), key, value };
+    return KLH_GUARDED(self, &op, klh_aset_body);
+}
+
+/*
+ *  call-seq:
+ *     keylockhash.delete(key) -> old value or nil
+ */
+static VALUE
+klh_delete(VALUE self, VALUE key)
+{
+    struct klh_op op = { klh_shard_for(self, key), key, Qnil };
+    return KLH_GUARDED(self, &op, klh_delete_body);
+}
+
+/* keys and to_h visit the shards one at a time, each under its own lock: a
+ * plain mutable copy, consistent per shard but NOT a snapshot of the whole
+ * map at one moment.  A cross-key snapshot is LockHash territory. */
+static VALUE
+klh_keys(VALUE self)
+{
+    VALUE ary = rb_ary_new();
+    struct keylockhash *kh = klh_ptr(self);
+
+    for (int i = 0; i < KLH_NSHARDS; i++) {
+        struct klh_op op = { &kh->shards[i], Qnil, ary };
+        KLH_GUARDED(self, &op, klh_collect_body);
+    }
+    return ary;
+}
+
+static VALUE
+klh_to_h(VALUE self)
+{
+    VALUE hash = rb_hash_new();
+    struct keylockhash *kh = klh_ptr(self);
+
+    for (int i = 0; i < KLH_NSHARDS; i++) {
+        struct klh_op op = { &kh->shards[i], Qnil, hash };
+        KLH_GUARDED(self, &op, klh_collect_body);
+    }
+    return hash;
+}
+
+static VALUE
+klh_inspect(VALUE self)
+{
+    if (!NIL_P(rs_held(rb_thread_current()))) {
+        return rb_sprintf("#<%"PRIsVALUE" ...>", rb_obj_class(self));
+    }
+    return rb_sprintf("#<%"PRIsVALUE" %+"PRIsVALUE">", rb_obj_class(self), klh_to_h(self));
+}
+
+void
+Init_keylockhash_class(void)
+{
+    id_plus = rb_intern("+");
+    rb_cRactorKeyLockHash = rb_define_class_under(rb_cRactor, "KeyLockHash", rb_cObject);
+    rb_define_alloc_func(rb_cRactorKeyLockHash, klh_alloc);
+    rb_define_method(rb_cRactorKeyLockHash, "initialize", klh_initialize, -1);
+
+    rb_define_method(rb_cRactorKeyLockHash, "[]", klh_aref, 1);
+    rb_define_method(rb_cRactorKeyLockHash, "fetch", klh_fetch, -1);
+    rb_define_method(rb_cRactorKeyLockHash, "key?", klh_key_p, 1);
+    rb_define_method(rb_cRactorKeyLockHash, "update", klh_update, 1);
+    rb_define_method(rb_cRactorKeyLockHash, "increment", klh_increment, -1);
+    rb_define_method(rb_cRactorKeyLockHash, "[]=", klh_aset, 2);
+    rb_define_method(rb_cRactorKeyLockHash, "delete", klh_delete, 1);
+    rb_define_method(rb_cRactorKeyLockHash, "keys", klh_keys, 0);
+    rb_define_method(rb_cRactorKeyLockHash, "to_h", klh_to_h, 0);
+    rb_define_method(rb_cRactorKeyLockHash, "inspect", klh_inspect, 0);
+}

data/ext/ractor/lock/lock.c

@@ -263,6 +263,40 @@ rs_guarded(VALUE self, struct rs_lock *lk, VALUE (*body)(VALUE), void *data,
     return rb_ensure(rs_guard_body, (VALUE)&arg, rs_guard_ensure, (VALUE)&arg);
 }
 
+/* Hash dups and freezes a bare String key rather than rejecting it, and so do
+ * we: the copy is shareable, and the caller's string stays their own. */
+VALUE
+rs_hash_key(VALUE key)
+{
+    if (RB_TYPE_P(key, T_STRING) && !RB_OBJ_FROZEN(key)) {
+        return rb_str_new_frozen(key);
+    }
+    return key;
+}
+
+VALUE
+rs_fixnum_add(VALUE a, VALUE b)
+{
+    long x, y;
+
+    if (!FIXNUM_P(a) || !FIXNUM_P(b)) return Qundef;
+    x = FIX2LONG(a); y = FIX2LONG(b);
+    if (y > 0 ? x > FIXNUM_MAX - y : x < FIXNUM_MIN - y) return Qundef;
+    return LONG2FIX(x + y);
+}
+
+/* Values are made shareable on the way in: a frozen literal passes through
+ * untouched, anything else is deep-frozen IN PLACE.  Storing a value here
+ * means sharing it. */
+VALUE
+rs_shareable_value(VALUE val)
+{
+    if (RB_UNLIKELY(!rb_ractor_shareable_p(val))) {
+        return rb_ractor_make_shareable(val);
+    }
+    return val;
+}
+
 void
 rs_lock_init_class(void)
 {
@@ -285,4 +319,5 @@ Init_lock(void)
     rs_lock_init_class();
     Init_lockvar_class();
     Init_lockhash_class();
+    Init_keylockhash_class();
 }

data/ext/ractor/lock/lock.h

@@ -30,6 +30,15 @@ void rs_lock_destroy(struct rs_lock *lk);
 void rs_lock_acquire(struct rs_lock *lk);
 void rs_lock_release(struct rs_lock *lk);
 
+/* a + b when both are Fixnums and the sum still is; Qundef otherwise. */
+VALUE rs_fixnum_add(VALUE a, VALUE b);
+
+/* A stored value is deep-frozen in place unless already shareable. */
+VALUE rs_shareable_value(VALUE val);
+
+/* A bare String key becomes a frozen copy, the way Hash stores one. */
+VALUE rs_hash_key(VALUE key);
+
 /* Which lock object this thread is inside, or Qnil. */
 VALUE rs_held(VALUE thread);
 void rs_held_set(VALUE thread, VALUE obj);
@@ -55,5 +64,6 @@ extern VALUE rb_eRactorNestedLock;
 void rs_lock_init_class(void);
 void Init_lockvar_class(void);
 void Init_lockhash_class(void);
+void Init_keylockhash_class(void);
 
 #endif

data/ext/ractor/lock/lockhash.c

@@ -132,8 +132,9 @@ lockhash_alloc(VALUE klass)
 static int
 lockhash_copy_pair(VALUE key, VALUE value, VALUE dest)
 {
+    key = rs_hash_key(key);
     lockhash_check_shareable(key);
-    lockhash_check_shareable(value);
+    value = rs_shareable_value(value);
     st_insert(((struct lockhash *)dest)->tbl, (st_data_t)key, (st_data_t)value);
     return ST_CONTINUE;
 }
@@ -319,9 +320,10 @@ lockhash_to_h(VALUE self)
 static VALUE
 lockhash_aset(VALUE self, VALUE key, VALUE value)
 {
+    key = rs_hash_key(key);
     lockhash_check_writable(self, "[]=");
     lockhash_check_shareable(key);
-    lockhash_check_shareable(value);
+    value = rs_shareable_value(value);
     st_insert(lockhash_ptr(self)->tbl, (st_data_t)key, (st_data_t)value);
     RB_OBJ_WRITTEN(self, Qundef, key);
     RB_OBJ_WRITTEN(self, Qundef, value);

data/ext/ractor/lock/lockvar.c

@@ -60,14 +60,6 @@ lockvar_ptr(VALUE self)
     return lv;
 }
 
-static void
-lockvar_check_shareable(VALUE val)
-{
-    if (RB_UNLIKELY(!rb_ractor_shareable_p(val))) {
-        rb_raise(rb_eArgError, "only shareable object are allowed");
-    }
-}
-
 static VALUE
 lockvar_alloc(VALUE klass)
 {
@@ -84,7 +76,7 @@ lockvar_initialize(int argc, VALUE *argv, VALUE self)
     VALUE init = Qnil;
     rb_check_frozen(self);   /* send(:initialize) again would write past the lock */
     rb_scan_args(argc, argv, "01", &init);
-    lockvar_check_shareable(init);
+    init = rs_shareable_value(init);
     lockvar_ptr(self)->value = init;
     /* Only the guarded slot changes, so the LockVar itself can be frozen and
      * shared; RUBY_TYPED_FROZEN_SHAREABLE is what permits it for a T_DATA. */
@@ -108,9 +100,8 @@ lockvar_update_body(VALUE ptr)
 {
     struct rs_guard_arg *arg = (struct rs_guard_arg *)ptr;
     struct lockvar *lv = lockvar_ptr(arg->self);
-    VALUE next = rb_yield(lv->value);   /* rs_guarded has marked the lock held */
+    VALUE next = rs_shareable_value(rb_yield(lv->value));   /* guard marked it held */
 
-    lockvar_check_shareable(next);
     lv->value = next;
     return next;
 }
@@ -121,9 +112,8 @@ lockvar_increment_body(VALUE ptr)
 {
     struct rs_guard_arg *arg = (struct rs_guard_arg *)ptr;
     struct lockvar *lv = lockvar_ptr(arg->self);
-    VALUE next = rb_funcall(lv->value, id_plus, 1, (VALUE)arg->data);
+    VALUE next = rs_shareable_value(rb_funcall(lv->value, id_plus, 1, (VALUE)arg->data));
 
-    lockvar_check_shareable(next);
     lv->value = next;
     return next;
 }
@@ -162,17 +152,6 @@ lockvar_update(VALUE self)
  * be interrupted and nothing can re-enter. That lets the whole ceremony go --
  * the held marker, the ensure, the shareable check, the method dispatch -- and
  * leaves the lock and one add. Returns Qundef when it does not apply. */
-static VALUE
-lockvar_fixnum_add(VALUE a, VALUE b)
-{
-    long x, y;
-
-    if (!FIXNUM_P(a) || !FIXNUM_P(b)) return Qundef;
-    x = FIX2LONG(a);
-    y = FIX2LONG(b);
-    if (y > 0 ? x > FIXNUM_MAX - y : x < FIXNUM_MIN - y) return Qundef;
-    return LONG2FIX(x + y);
-}
 
 static VALUE
 lockvar_increment(int argc, VALUE *argv, VALUE self)
@@ -189,7 +168,7 @@ lockvar_increment(int argc, VALUE *argv, VALUE self)
         VALUE next;
 
         rs_lock_acquire(&lv->lock);
-        next = lockvar_fixnum_add(lv->value, amount);
+        next = rs_fixnum_add(lv->value, amount);
         if (!RB_UNDEF_P(next)) lv->value = next;
         rs_lock_release(&lv->lock);
 

data/ext/ractor/tvar/tvar.c

@@ -612,13 +612,23 @@ tvar_ptr(VALUE self)
     return slot;
 }
 
+/* Values are made shareable on the way in: a frozen literal passes through
+ * untouched (one shareable_p check), anything else is deep-frozen IN PLACE.
+ * Storing a value here means sharing it; freezing it is not a side effect of
+ * that, it is the meaning of it. */
 static VALUE
-tvar_new_(VALUE self, VALUE init)
+tvar_shareable_value(VALUE val)
 {
-    // init should be shareable
-    if (RB_UNLIKELY(!rb_ractor_shareable_p(init))) {
-        rb_raise(rb_eArgError, "only shareable object are allowed");
+    if (RB_UNLIKELY(!rb_ractor_shareable_p(val))) {
+        return rb_ractor_make_shareable(val);
     }
+    return val;
+}
+
+static VALUE
+tvar_new_(VALUE self, VALUE init)
+{
+    init = tvar_shareable_value(init);
 
     struct tx_global *txg = tx_global_ptr();
     struct tvar_slot *slot;
@@ -664,9 +674,7 @@ tvar_value(VALUE self)
 static VALUE
 tvar_value_set(VALUE self, VALUE val)
 {
-    if (RB_UNLIKELY(!rb_ractor_shareable_p(val))) {
-        rb_raise(rb_eArgError, "only shareable object are allowed");
-    }
+    val = tvar_shareable_value(val);
 
     struct tx_logs *tx = tx_logs();
     tx_check(tx);
@@ -725,12 +733,8 @@ tvar_value_increment_(VALUE self, VALUE inc)
     else {
         recv = tx_get(tx, slot, self);
         if (RB_UNLIKELY((ret = tvar_calc_inc(recv, inc)) == Qundef)) {
-            /* + can return anything; a TVar only ever holds shareable values, and
-             * outside a transaction this path is checked by #value=. */
-            ret = rb_funcall(recv, rb_intern("+"), 1, inc);
-            if (RB_UNLIKELY(!rb_ractor_shareable_p(ret))) {
-                rb_raise(rb_eArgError, "only shareable object are allowed");
-            }
+            /* + can return anything; a TVar only ever holds shareable values. */
+            ret = tvar_shareable_value(rb_funcall(recv, rb_intern("+"), 1, inc));
         }
         tx_set(tx, ret, slot, self);
     }

data/lib/ractor/keylockhash.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "ractor/lock.so"

data/lib/ractor/sharing/version.rb

@@ -2,6 +2,6 @@
 
 class Ractor
   module Sharing
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/ractor/sharing.rb

@@ -3,6 +3,7 @@
 require_relative "sharing/version"
 require_relative "lockvar"
 require_relative "lockhash"
+require_relative "keylockhash"
 require_relative "tvar"
 require_relative "active_object"
 require_relative "actor_hash"
@@ -15,6 +16,7 @@ class Ractor
   #   Ractor::TVar          one or more variables, changed together -- start here
   #   Ractor::LockVar       one variable, and a block that runs exactly once
   #   Ractor::LockHash      a hash of those, atomic across its own keys
+  #   Ractor::KeyLockHash   a hash with one lock per key: parallel across keys
   #   Ractor::ActiveObject  an object of your own, owned by one Ractor
   #   Ractor::ActorHash     the same, with the interface already chosen: a hash
   #
@@ -23,6 +25,7 @@ class Ractor
   #   require "ractor/tvar"
   #   require "ractor/lockvar"
   #   require "ractor/lockhash"
+  #   require "ractor/keylockhash"
   #   require "ractor/active_object"
   #   require "ractor/actor_hash"
   module Sharing