farce 0.0.1.alpha2-x86-linux-gnu

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

@@ -0,0 +1,373 @@
+package org.farce;
+
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.Map;
+import java.util.TreeMap;
+import java.util.concurrent.locks.ReentrantLock;
+import java.util.function.BiPredicate;
+import java.util.function.BooleanSupplier;
+import java.util.function.Consumer;
+import java.util.function.Function;
+
+/** Ordered FIFO buckets with opaque Ruby values and transactional callbacks. */
+public final class PriorityQueue {
+    public static final class Failure extends RuntimeException {
+        private final int code;
+        Failure(int code, String message) { super(message); this.code = code; }
+        public int getCode() { return code; }
+    }
+
+    private static final class Bucket {
+        Entry head;
+        Entry tail;
+        int size;
+        HashMap<Object, Entry> identities;
+    }
+
+    private static class Entry {
+        final Object value;
+        Entry previous;
+        Entry next;
+        Object token;
+        Entry identityPrevious;
+        Entry identityNext;
+        boolean committed;
+        Entry(Object value) { this.value = value; }
+    }
+
+    private static final class TrackedEntry extends Entry {
+        final long enqueuedAt;
+        TrackedEntry agePrevious;
+        TrackedEntry ageNext;
+        TrackedEntry(Object value) { super(value); enqueuedAt = System.nanoTime(); }
+    }
+
+    private final ReentrantLock lock = new ReentrantLock();
+    private final TreeMap<PriorityKey, Bucket> tree;
+    private final Function<PriorityKey, PriorityKey> snapshot;
+    private final Function<Object, Object> identity;
+    private final BiPredicate<Object, Object> equal;
+    private final BiPredicate<Object, Object> identical;
+    private final BiPredicate<Object, Object> match;
+    private final Consumer<Runnable> committer;
+    private final QueueSignal signal;
+    private final BooleanSupplier scheduled;
+    private final long capacity;
+    private final boolean trackAge;
+    private long size;
+    private long generation;
+    private TrackedEntry ageHead;
+    private TrackedEntry ageTail;
+    private boolean sealed;
+    private boolean closed;
+
+    public PriorityQueue(Comparator<PriorityKey> comparator,
+                         Function<PriorityKey, PriorityKey> snapshot,
+                         Function<Object, Object> identity,
+                         BiPredicate<Object, Object> equal,
+                         BiPredicate<Object, Object> identical,
+                         BiPredicate<Object, Object> match,
+                         Consumer<Runnable> committer,
+                         BooleanSupplier scheduled, long capacity, QueueSignal signal,
+                         boolean trackAge) {
+        this.tree = new TreeMap<>(comparator);
+        this.snapshot = snapshot;
+        this.identity = identity;
+        this.equal = equal;
+        this.identical = identical;
+        this.match = match;
+        this.committer = committer;
+        this.signal = signal;
+        this.scheduled = scheduled;
+        this.capacity = capacity;
+        this.trackAge = trackAge;
+    }
+
+    private void enter() {
+        if (lock.isHeldByCurrentThread())
+            throw new Failure(1, "recursive priority queue access");
+        if (!lock.tryLock()) {
+            if (scheduled.getAsBoolean())
+                throw new Failure(3, "shared JVM container contention cannot block a scheduled Fiber");
+            lock.lock();
+        }
+    }
+
+    private void checkPushOpen() {
+        if (closed) throw new Failure(2, "queue is closed");
+        if (sealed) throw new Failure(4, "queue is sealed");
+    }
+
+    private void checkReadOpen() {
+        if (closed) throw new Failure(2, "queue is closed");
+    }
+
+    private void commit(Runnable operation) {
+        if (signal != null && signal.commitWithoutFiberWaiters(operation)) return;
+        if (committer == null) operation.run();
+        else committer.accept(operation);
+    }
+
+    // Construct keys inside Java to avoid allocating a Ruby Java-proxy per key.
+    public boolean pushFloat(double priority, Object rubyPriority, Object value) {
+        return push(new PriorityKey(rubyPriority, true, priority), value);
+    }
+
+    public Object readBefore(double cutoff, Object rubyCutoff) {
+        return read(0, false, new PriorityKey(rubyCutoff, true, cutoff));
+    }
+
+    public boolean push(PriorityKey query, Object value) {
+        enter();
+        Bucket candidate = null;
+        Bucket bucket = null;
+        Entry entry = null;
+        try {
+            checkPushOpen();
+            if (capacity > 0 && size >= capacity) return false;
+            bucket = tree.get(query);
+            if (bucket == null) {
+                PriorityKey key = query.requiresSnapshot() ? snapshot.apply(query) : query;
+                candidate = new Bucket();
+                Bucket existing = tree.putIfAbsent(key, candidate);
+                bucket = existing == null ? candidate : existing;
+            }
+            entry = trackAge ? new TrackedEntry(value) : new Entry(value);
+            if (bucket.identities != null) addIdentity(bucket.identities, entry);
+            Bucket target = bucket;
+            Entry added = entry;
+            commit(() -> {
+                added.previous = target.tail;
+                if (target.tail == null) target.head = added;
+                else target.tail.next = added;
+                target.tail = added;
+                target.size++;
+                size++;
+                trackPush(added);
+                added.committed = true;
+            });
+            return true;
+        } finally {
+            if (entry == null || !entry.committed) {
+                if (entry != null && entry.identityNext != null) discardIdentity(bucket.identities, entry);
+                if (candidate != null && candidate.size == 0) removeEmpty(candidate);
+            }
+            lock.unlock();
+        }
+    }
+
+    private void removeEmpty(Bucket bucket) {
+        Iterator<Bucket> iterator = tree.values().iterator();
+        while (iterator.hasNext()) {
+            if (iterator.next() == bucket) { iterator.remove(); return; }
+        }
+    }
+
+    private Iterator<Map.Entry<PriorityKey, Bucket>> iterator(boolean last) {
+        return (last ? tree.descendingMap() : tree).entrySet().iterator();
+    }
+
+    // kind: 0 = pop, 1 = peek, 2 = priority. Null cutoff means unbounded.
+    public Object read(int kind, boolean last, PriorityKey cutoff) {
+        enter();
+        try {
+            checkReadOpen();
+            Iterator<Map.Entry<PriorityKey, Bucket>> iterator = iterator(last);
+            if (!iterator.hasNext()) return null;
+            Map.Entry<PriorityKey, Bucket> item = iterator.next();
+            if (kind == 2) return item.getKey().getRubyKey();
+            if (cutoff != null && tree.comparator().compare(item.getKey(), cutoff) > 0) return null;
+            Bucket bucket = item.getValue();
+            Entry entry = bucket.head;
+            if (kind == 1) return entry.value;
+            commit(() -> {
+                unlink(bucket, entry);
+                if (bucket.size == 0) iterator.remove();
+            });
+            return entry.value;
+        } finally { lock.unlock(); }
+    }
+
+    // kind: 0 = stored == requested, 1 = identity, 2 = requested === stored.
+    public boolean removeValue(PriorityKey key, Object value, int kind) {
+        enter();
+        try {
+            checkReadOpen();
+            Bucket bucket = tree.get(key);
+            if (bucket == null) return false;
+            Entry found = null;
+            if (kind == 1 && bucket.size >= 32 && bucket.identities == null) buildIdentities(bucket);
+            if (kind == 1 && bucket.identities != null) {
+                Entry head = bucket.identities.get(identity.apply(value));
+                if (head != null && identical.test(head.value, value)) found = head;
+            } else {
+                BiPredicate<Object, Object> predicate = kind == 1 ? identical : kind == 2 ? match : equal;
+                for (Entry entry = bucket.head; entry != null; entry = entry.next) {
+                    if (predicate.test(entry.value, value)) { found = entry; break; }
+                }
+            }
+            if (found == null) return false;
+            Iterator<Map.Entry<PriorityKey, Bucket>> removal = null;
+            if (bucket.size == 1) {
+                removal = tree.tailMap(key, true).entrySet().iterator();
+                if (!removal.hasNext() || removal.next().getValue() != bucket)
+                    throw new IllegalStateException("priority map lost its bucket");
+            }
+            Entry selected = found;
+            Iterator<Map.Entry<PriorityKey, Bucket>> positioned = removal;
+            commit(() -> {
+                unlink(bucket, selected);
+                if (positioned != null) positioned.remove();
+            });
+            return true;
+        } finally { lock.unlock(); }
+    }
+
+    private void unlink(Bucket bucket, Entry entry) {
+        if (entry.previous == null) bucket.head = entry.next;
+        else entry.previous.next = entry.next;
+        if (entry.next == null) bucket.tail = entry.previous;
+        else entry.next.previous = entry.previous;
+        entry.previous = entry.next = null;
+        if (bucket.identities != null) discardIdentity(bucket.identities, entry);
+        bucket.size--;
+        size--;
+        trackRemove(entry);
+        if (sealed && size == 0) closed = true;
+    }
+
+    private void trackPush(Entry entry) {
+        if (!trackAge) return;
+        TrackedEntry tracked = (TrackedEntry)entry;
+        tracked.agePrevious = ageTail;
+        if (ageTail == null) ageHead = tracked;
+        else ageTail.ageNext = tracked;
+        ageTail = tracked;
+        generation++;
+    }
+
+    private void trackRemove(Entry entry) {
+        if (!trackAge) return;
+        TrackedEntry tracked = (TrackedEntry)entry;
+        if (tracked.agePrevious == null) ageHead = tracked.ageNext;
+        else tracked.agePrevious.ageNext = tracked.ageNext;
+        if (tracked.ageNext == null) ageTail = tracked.agePrevious;
+        else tracked.ageNext.agePrevious = tracked.agePrevious;
+        generation++;
+    }
+
+    // Circular identity FIFOs need no separate slot allocation and retain no dead entries.
+    private void addIdentity(HashMap<Object, Entry> index, Entry entry) {
+        Object token = identity.apply(entry.value);
+        Entry head = index.get(token);
+        entry.token = token;
+        if (head == null) {
+            index.put(token, entry);
+            entry.identityNext = entry.identityPrevious = entry;
+        } else {
+            Entry tail = head.identityPrevious;
+            entry.identityNext = head;
+            entry.identityPrevious = tail;
+            tail.identityNext = head.identityPrevious = entry;
+        }
+    }
+
+    private void discardIdentity(HashMap<Object, Entry> index, Entry entry) {
+        if (entry.identityNext == entry) index.remove(entry.token);
+        else {
+            entry.identityPrevious.identityNext = entry.identityNext;
+            entry.identityNext.identityPrevious = entry.identityPrevious;
+            if (index.get(entry.token) == entry) index.put(entry.token, entry.identityNext);
+        }
+        entry.token = null;
+        entry.identityNext = entry.identityPrevious = null;
+    }
+
+    private void buildIdentities(Bucket bucket) {
+        HashMap<Object, Entry> index = new HashMap<>();
+        boolean completed = false;
+        try {
+            for (Entry entry = bucket.head; entry != null; entry = entry.next) addIdentity(index, entry);
+            bucket.identities = index;
+            completed = true;
+        } finally {
+            if (!completed) {
+                for (Entry entry = bucket.head; entry != null; entry = entry.next) {
+                    entry.token = null;
+                    entry.identityNext = entry.identityPrevious = null;
+                }
+            }
+        }
+    }
+
+    public long size() {
+        enter();
+        try { return size; } finally { lock.unlock(); }
+    }
+
+    public boolean isClosed() {
+        enter();
+        try { return closed; } finally { lock.unlock(); }
+    }
+
+    public boolean isSealed() {
+        enter();
+        try { return sealed; } finally { lock.unlock(); }
+    }
+
+    public boolean isAgeTracking() { return trackAge; }
+
+    public Long generation() {
+        if (!trackAge) return null;
+        enter();
+        try { return generation; } finally { lock.unlock(); }
+    }
+
+    public Double oldestEnqueuedAt() {
+        if (!trackAge) return null;
+        enter();
+        try { return ageHead == null ? null : ageHead.enqueuedAt / 1_000_000_000.0; }
+        finally { lock.unlock(); }
+    }
+
+    public Double oldestAge() {
+        if (!trackAge) return null;
+        enter();
+        try { return ageHead == null ? null : (System.nanoTime() - ageHead.enqueuedAt) / 1_000_000_000.0; }
+        finally { lock.unlock(); }
+    }
+
+    public void clear() {
+        enter();
+        try { commit(() -> {
+            tree.clear();
+            if (trackAge && size > 0) generation++;
+            size = 0;
+            ageHead = ageTail = null;
+            if (sealed) closed = true;
+        }); }
+        finally { lock.unlock(); }
+    }
+
+    public void seal() {
+        enter();
+        try { commit(() -> {
+            if (!sealed && trackAge) generation++;
+            sealed = true;
+            if (size == 0) closed = true;
+        }); }
+        finally { lock.unlock(); }
+    }
+
+    public void close() {
+        enter();
+        try { commit(() -> {
+            if (!closed && trackAge) generation++;
+            sealed = true;
+            closed = true;
+        }); }
+        finally { lock.unlock(); }
+    }
+}

data/ext/java/org/farce/QueueSignal.java

@@ -0,0 +1,28 @@
+package org.farce;
+
+import java.util.concurrent.Phaser;
+
+/** Thread-only notification and queue commit can execute without Ruby callbacks. */
+public class QueueSignal extends Phaser {
+    private int schedulerWaiters;
+
+    public QueueSignal() { super(1); }
+
+    public synchronized int broadcastThreads() {
+        int previous = arrive();
+        return previous == Integer.MAX_VALUE ? 0 : previous + 1;
+    }
+
+    // Registration and commits use the SAME monitor. A new waiter can never
+    // register between the zero-waiter check and the phase advance/commit.
+    public synchronized void beginSchedulerWait() { schedulerWaiters++; }
+
+    public synchronized void endSchedulerWait() { schedulerWaiters--; }
+
+    public synchronized boolean commitWithoutFiberWaiters(Runnable operation) {
+        if (schedulerWaiters != 0) return false;
+        broadcastThreads();
+        operation.run();
+        return true;
+    }
+}

data/ext/rebind/README.md

@@ -0,0 +1,14 @@
+# Block rebinding
+
+A small extension for block rebinding on CRuby.
+
+Rebinding rather than wrapping procs is necessary for some use cases, such as retaining Ractor-shareability.
+It also produces significantly faster and smaller procs than wrapping or casting to an unbound method and rebinding.
+
+It does however rely on MRI internals, as there are no public APIs for this, so it needs to be verified for each new Ruby version. This is in part why it is kept as a separate extension.
+
+On Ruby implementations other than MRI it generates a dummy Makefile, so it still "compiles".
+
+## AI Usage
+
+Anthropic's Claude AI has been used to explore the underlying data structures, identify edge cases, and helped write the patch. All generated code has been reviewed extensively if it ended up being used in the final implementation.

data/ext/rebind/extconf.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require_relative "../ext_helper"
+
+if RUBY_ENGINE == "ruby"
+  create_makefile ExtHelper.ext_path("rebind")
+else
+  File.write("Makefile", "all:\ninstall:\n")
+end

data/ext/rebind/rebind.c

@@ -0,0 +1,186 @@
+#include <ruby.h>
+#include <ruby/version.h>
+
+#include <stddef.h>
+
+/*
+ * Private CRuby layout mirrored from vm_core.h.
+ *
+ * Ruby 4.1 split Proc's storage into separate representations sharing a
+ * header. Older supported CRuby versions store the captured block first.
+ * We deliberately mirror only the prefix we need.
+ */
+
+union farce_block_code
+{
+    const void *iseq;
+    const void *ifunc;
+    VALUE val;
+};
+
+struct farce_captured_block
+{
+    VALUE self;
+    const VALUE *ep;
+    union farce_block_code code;
+};
+
+enum farce_block_type
+{
+    FARCE_BLOCK_ISEQ   = 0,
+    FARCE_BLOCK_IFUNC  = 1,
+    FARCE_BLOCK_SYMBOL = 2,
+    FARCE_BLOCK_PROC   = 3
+};
+
+struct farce_block
+{
+    union
+    {
+        struct farce_captured_block captured;
+        VALUE symbol;
+        VALUE proc;
+    } as;
+
+    enum farce_block_type type;
+};
+
+#if RUBY_API_VERSION_MAJOR == 4 && RUBY_API_VERSION_MINOR >= 1
+struct farce_proc_header
+{
+    enum farce_block_type type : 8;
+    unsigned int is_from_method : 1;
+    unsigned int is_lambda      : 1;
+    unsigned int is_isolated    : 1;
+    unsigned int is_refined     : 1;
+};
+
+struct farce_proc_captured
+{
+    struct farce_proc_header header;
+    struct farce_captured_block captured;
+};
+
+union farce_proc
+{
+    struct farce_block block;
+    struct farce_proc_header header;
+    struct farce_proc_captured captured;
+};
+
+typedef union farce_proc farce_proc_t;
+
+#define FARCE_PROC_TYPE(proc) ((proc)->header.type)
+#define FARCE_PROC_SELF(proc) (&(proc)->captured.captured.self)
+#define FARCE_PROC_LAMBDA(proc) ((proc)->header.is_lambda)
+
+#else
+struct farce_proc
+{
+    struct farce_block block;
+
+    unsigned int is_from_method : 1;
+    unsigned int is_lambda      : 1;
+    unsigned int is_isolated    : 1;
+};
+
+typedef struct farce_proc farce_proc_t;
+
+#define FARCE_PROC_TYPE(proc) ((proc)->block.type)
+#define FARCE_PROC_SELF(proc) (&(proc)->block.as.captured.self)
+#define FARCE_PROC_LAMBDA(proc) ((proc)->is_lambda)
+#endif
+
+#define FARCE_STATIC_ASSERT(name, expr) \
+    typedef char farce_static_assert_##name[(expr) ? 1 : -1]
+
+FARCE_STATIC_ASSERT(
+    captured_block_is_three_words,
+    sizeof(struct farce_captured_block) == 3 * sizeof(VALUE));
+
+FARCE_STATIC_ASSERT(
+    captured_self_is_first,
+    offsetof(struct farce_captured_block, self) == 0);
+
+FARCE_STATIC_ASSERT(
+    block_is_four_words,
+    sizeof(struct farce_block) == 4 * sizeof(VALUE));
+
+#if RUBY_API_VERSION_MAJOR == 4 && RUBY_API_VERSION_MINOR >= 1
+FARCE_STATIC_ASSERT(
+    captured_self_offset,
+    offsetof(union farce_proc, captured.captured.self) == sizeof(VALUE));
+#else
+FARCE_STATIC_ASSERT(
+    proc_starts_with_block,
+    offsetof(struct farce_proc, block) == 0);
+#endif
+
+#if !((RUBY_API_VERSION_MAJOR == 3 && RUBY_API_VERSION_MINOR == 4) || \
+      (RUBY_API_VERSION_MAJOR == 4 && RUBY_API_VERSION_MINOR <= 1))
+#error "Farce's Proc layout needs verification for this CRuby version"
+#endif
+
+static farce_proc_t *
+farce_proc_ptr(VALUE proc)
+{
+    return (farce_proc_t *)RTYPEDDATA_GET_DATA(proc);
+}
+
+static int
+farce_proc_rebindable_p(farce_proc_t *proc)
+{
+    return (FARCE_PROC_TYPE(proc) == FARCE_BLOCK_ISEQ || FARCE_PROC_TYPE(proc) == FARCE_BLOCK_IFUNC);
+}
+
+static VALUE
+proc_rebindable_p(VALUE module, VALUE proc_val)
+{
+    farce_proc_t *proc;
+
+    (void)module;
+
+    if (!rb_obj_is_proc(proc_val)) return Qfalse;
+    proc = farce_proc_ptr(proc_val);
+    return farce_proc_rebindable_p(proc) ? Qtrue : Qfalse;
+}
+
+static VALUE
+rebind_proc_self(VALUE module, VALUE proc_val, VALUE new_self, VALUE lambda_mode)
+{
+    VALUE new_proc;
+    farce_proc_t *proc;
+
+    (void)module;
+
+    if (!rb_obj_is_proc(proc_val))
+        rb_raise(rb_eTypeError, "expected a Proc");
+
+    if (lambda_mode != Qnil && lambda_mode != Qtrue && lambda_mode != Qfalse)
+        rb_raise(rb_eArgError, "lambda mode must be true, false, or nil");
+
+    new_proc = rb_funcall(proc_val, rb_intern("dup"), 0);
+    proc = farce_proc_ptr(new_proc);
+
+    if (!farce_proc_rebindable_p(proc))
+        rb_raise(rb_eTypeError, "cannot rebind this Proc representation");
+
+    RB_OBJ_WRITE(new_proc, FARCE_PROC_SELF(proc), new_self);
+
+    if (lambda_mode != Qnil)
+        FARCE_PROC_LAMBDA(proc) = lambda_mode == Qtrue;
+
+    return new_proc;
+}
+
+void Init_rebind(void)
+{
+#ifdef HAVE_RB_EXT_RACTOR_SAFE
+    rb_ext_ractor_safe(true);
+#endif
+
+    VALUE mFarce = rb_const_get(rb_cObject, rb_intern("Farce"));
+    VALUE mInternal = rb_const_get(mFarce, rb_intern("Internal"));
+    rb_define_module_function(mInternal, "rebind", rebind_proc_self, 3);
+    rb_define_module_function(mInternal, "rebindable?", proc_rebindable_p, 1);
+}

data/lib/farce/_yard/internal.rb

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

data/lib/farce/_yard/macros.rb

@@ -0,0 +1,61 @@
+# @!macro unsafe
+#   @note
+#     Instances of this class are **not thread-safe** and should not be shared concurrently.
+#     This does not just apply to Ractors, but also Threads and possibly Fibers.
+#
+#     Only use them if you are absolutely certain of this and they do not leave a tightly controlled scope.
+#     They can provide a memory or performance advantage over their thread-safe counterparts, so they
+#     might be useful for hot path optimizations.
+#
+#     Concurrent access, especially modifications, may corrupt the internal state of the object.
+
+# @!macro modes
+#   Valid modes are:
+#   * `:copy` - The value will be copied between Ractors. This is the default mode.
+#   * `:make_shareable` - The value will be made Ractor-shareable using {Ractor.make_shareable}.
+#   * `:move` - The value will be moved between Ractors. This saves memory compared to copying, and supports values
+#     that can't be copied but moved (like IO objects). However, the value will no longer be accessible on the Ractor
+#     that pushed it.
+#   * `:mutable` - A {Farce::Mutable} instance will be created for the value. This isn't done recursively and thus will fail for nested unshareable values.
+#   * `:local` - The value will be kept local to the Ractor that pushed it. Another ractor trying to receive it will
+#     get an error. Useful for usage contained within a single Ractor.
+#   * `:proxy` - The value will be wrapped in a `Farce::Proxy` that executes calls in the original Ractor.
+#   * `:raise` - An error will be raised if the value is not Ractor-shareable. Useful for enforcing shareability.
+#   * `:dedup` - The value will be deduplicated using {Farce.dedup}, then made Ractor-shareable.
+#     This may update and freeze the original. Already-shareable values pass through unchanged.
+#   * `:shareable_copy` - The value will be copied and the copy will be made Ractor-shareable.
+
+# @!macro scopes
+#   Valid scopes are:
+#   * `:ractor` - The value is shared by all threads within the same Ractor.
+#   * `:thread_group` - The value is shared by all threads within the same thread group.
+#   * `:thread` - The value is shared by all fibers within the same thread.
+#   * `:fiber_storage` - The value is shared by all fibers using the same storage.
+#     Unless explicitly specified, storage is inherited from the parent fiber for blocking fibers,
+#     but not for non-blocking fibers (such as those created by {Scheduler#schedule}).
+#   * `:fiber` - Each fiber has its own independent value.
+
+# @!macro key_normalization
+#   @param normalize_keys [Symbol, Proc, Hash, Farce::Abstract::Map, nil]
+#     Converts incoming keys to their canonical stored form:
+#     * If a `Symbol` is provided, it will be used as a method name to call on each key.
+#     * If a `Proc` is provided, it will be called with each key and should return the normalized key.
+#     * If a `Hash` or {Farce::Abstract::Map Map} is provided, it will be used to look up the normalized key for each incoming key.
+
+# @!macro map_initialization
+#   Create a map with optional initial entries.
+#   @param initial_mapping [Hash, Farce::Abstract::Map, #each, nil]
+#     The entries to store initially. Each iteration must yield a key-value pair.
+#     Nil creates an empty map.
+#   @!macro key_normalization
+#   @param compare_by_identity [Boolean]
+#     The default identity-comparison setting for keys and values. Defaults to false.
+#   @param compare_keys_by_identity [Boolean]
+#     Whether keys use object identity instead of `hash` and `eql?`.
+#     Defaults to `compare_by_identity`.
+#   @param compare_values_by_identity [Boolean]
+#     Whether values use object identity instead of `==`.
+#     Defaults to `compare_by_identity`.
+
+# @!macro active_support
+#   @note This methods is only available if ActiveSupport has been loaded.