farce 0.0.1.alpha2-x86_64-linux-gnu

data/ext/farce/dict.h

@@ -0,0 +1,152 @@
+/*
+ * Dictionary Abstract Data Type
+ * Copyright (C) 1997 Kaz Kylheku <kaz@ashi.footprints.net>
+ *
+ * Free Software License:
+ *
+ * All rights are reserved by the author, with the following exceptions:
+ * Permission is granted to freely reproduce and distribute this software,
+ * possibly in exchange for a fee, provided that this copyright notice appears
+ * intact. Permission is also granted to adapt this software to produce
+ * derivative works, as long as the modified versions carry this copyright
+ * notice and additional notices stating that the work has been modified.
+ * This source code may be translated into executable form and incorporated
+ * into proprietary software; there is no requirement for such software to
+ * contain a copyright notice related to this source.
+ *
+ * $Id: dict.h,v 1.22.2.6 2000/11/13 01:36:44 kaz Exp $
+ * $Name: kazlib_1_20 $
+ */
+
+/*
+ * Modified for Ruby/RBTree.
+ * Modified by Farce to expose reusable unique-key insertion positions.
+ */
+
+#ifndef DICT_H
+#define DICT_H
+
+#include <limits.h>
+#ifdef KAZLIB_SIDEEFFECT_DEBUG
+#include "sfx.h"
+#endif
+
+/*
+ * Blurb for inclusion into C++ translation units
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef unsigned long dictcount_t;
+#define DICTCOUNT_T_MAX ULONG_MAX
+
+/*
+ * The dictionary is implemented as a red-black tree
+ */
+
+typedef enum { dnode_red, dnode_black } dnode_color_t;
+
+typedef struct dnode_t {
+    #if defined(DICT_IMPLEMENTATION) || !defined(KAZLIB_OPAQUE_DEBUG)
+    struct dnode_t *dict_left;
+    struct dnode_t *dict_right;
+    struct dnode_t *dict_parent;
+    dnode_color_t dict_color;
+    const void *dict_key;
+    void *dict_data;
+    #else
+    int dict_dummy;
+    #endif
+} dnode_t;
+
+typedef int (*dict_comp_t)(const void *, const void *, void *);
+typedef dnode_t *(*dnode_alloc_t)(void *);
+typedef void (*dnode_free_t)(dnode_t *, void *);
+
+typedef struct dict_t {
+    #if defined(DICT_IMPLEMENTATION) || !defined(KAZLIB_OPAQUE_DEBUG)
+    dnode_t dict_nilnode;
+    dictcount_t dict_nodecount;
+    dict_comp_t dict_compare;
+    dnode_alloc_t dict_allocnode;
+    dnode_free_t dict_freenode;
+    void *dict_context;
+    int dict_dupes;
+    #else
+    int dict_dummmy;
+    #endif
+} dict_t;
+
+typedef void (*dnode_process_t)(dict_t *, dnode_t *, void *);
+
+typedef struct dict_load_t {
+    #if defined(DICT_IMPLEMENTATION) || !defined(KAZLIB_OPAQUE_DEBUG)
+    dict_t *dict_dictptr;
+    dnode_t dict_nilnode;
+    #else
+    int dict_dummmy;
+    #endif
+} dict_load_t;
+
+extern dict_t *dict_create(dict_comp_t);
+extern void dict_set_allocator(dict_t *, dnode_alloc_t, dnode_free_t, void *);
+extern void dict_destroy(dict_t *);
+extern void dict_free_nodes(dict_t *);
+extern void dict_free(dict_t *);
+extern dict_t *dict_init(dict_t *, dict_comp_t);
+extern void dict_init_like(dict_t *, const dict_t *);
+extern int dict_verify(dict_t *);
+extern int dict_similar(const dict_t *, const dict_t *);
+extern dnode_t *dict_lookup(dict_t *, const void *);
+extern dnode_t *dict_lower_bound(dict_t *, const void *);
+extern dnode_t *dict_upper_bound(dict_t *, const void *);
+extern int dict_insert(dict_t *, dnode_t *, const void *);
+/* Farce extension: find a unique key or retain its insertion position. The
+ * caller must keep the tree and key ordering unchanged until insert_at. */
+extern dnode_t *dict_lookup_position(dict_t *, const void *, dnode_t **, int *);
+extern int dict_insert_at(dict_t *, dnode_t *, const void *, dnode_t *, int);
+extern dnode_t *dict_delete(dict_t *, dnode_t *);
+extern int dict_alloc_insert(dict_t *, const void *, void *);
+extern void dict_delete_free(dict_t *, dnode_t *);
+extern dnode_t *dict_first(dict_t *);
+extern dnode_t *dict_last(dict_t *);
+extern dnode_t *dict_next(dict_t *, dnode_t *);
+extern dnode_t *dict_prev(dict_t *, dnode_t *);
+extern dictcount_t dict_count(dict_t *);
+extern int dict_isempty(dict_t *);
+extern int dict_isfull(dict_t *);
+extern int dict_contains(dict_t *, dnode_t *);
+extern void dict_allow_dupes(dict_t *);
+extern int dnode_is_in_a_dict(dnode_t *);
+extern dnode_t *dnode_create(void *);
+extern dnode_t *dnode_init(dnode_t *, void *);
+extern void dnode_destroy(dnode_t *);
+extern void *dnode_get(dnode_t *);
+extern const void *dnode_getkey(dnode_t *);
+extern void dnode_put(dnode_t *, void *);
+extern void dict_process(dict_t *, void *, dnode_process_t);
+extern void dict_load_begin(dict_load_t *, dict_t *);
+extern void dict_load_next(dict_load_t *, dnode_t *, const void *);
+extern void dict_load_end(dict_load_t *);
+extern void dict_merge(dict_t *, dict_t *);
+
+#if defined(DICT_IMPLEMENTATION) || !defined(KAZLIB_OPAQUE_DEBUG)
+#ifdef KAZLIB_SIDEEFFECT_DEBUG
+#define dict_isfull(D) (SFX_CHECK(D)->dict_nodecount == (D)->dict_maxcount)
+#else
+#define dict_isfull(D) ((D)->dict_nodecount == DICTCOUNT_T_MAX)
+#endif
+#define dict_count(D) ((D)->dict_nodecount)
+#define dict_isempty(D) ((D)->dict_nodecount == 0)
+#define dnode_get(N) ((N)->dict_data)
+#define dnode_getkey(N) ((N)->dict_key)
+#define dnode_put(N, X) ((N)->dict_data = (X))
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

data/ext/farce/drivers.c

@@ -0,0 +1,237 @@
+#include "reactor.h"
+#include <unistd.h>
+#include <poll.h>
+#include <errno.h>
+#include <limits.h>
+#include <fcntl.h>
+#include <math.h>
+#ifdef HAVE_SYS_EPOLL_H
+#include <sys/epoll.h>
+#endif
+#ifdef HAVE_SYS_EVENT_H
+#include <sys/event.h>
+#endif
+
+static struct timespec relative_time(double seconds) {
+    struct timespec t;
+    t.tv_sec = (time_t)seconds;
+    t.tv_nsec = (long)((seconds - (double)t.tv_sec) * 1e9);
+    return t;
+}
+
+int fs_driver_init(fs_state *s, int driver) {
+    s->driver = driver;
+#ifdef HAVE_SYS_EPOLL_H
+    if (driver == FS_EPOLL) {
+        s->descriptor = epoll_create1(EPOLL_CLOEXEC);
+        return s->descriptor < 0 ? errno : 0;
+    }
+#endif
+#ifdef HAVE_SYS_EVENT_H
+    if (driver == FS_KQUEUE) {
+        s->descriptor = kqueue();
+        return s->descriptor < 0 ? errno : 0;
+    }
+#endif
+#ifdef FARCE_URING
+    if (driver == FS_URING_DRIVER) {
+        int result = io_uring_queue_init(1024, &s->ring, 0);
+        if (result < 0) return -result;
+        s->ring_live = 1;
+        return 0;
+    }
+#endif
+    return ENOSYS;
+}
+
+#ifdef FARCE_URING
+static struct io_uring_sqe *sqe(fs_state *s) {
+    struct io_uring_sqe *entry = io_uring_get_sqe(&s->ring);
+    if (!entry) {
+        int result = io_uring_submit(&s->ring);
+        if (result < 0) { errno = -result; return NULL; }
+        entry = io_uring_get_sqe(&s->ring);
+    }
+    if (!entry) errno = EBUSY;
+    return entry;
+}
+#endif
+
+int fs_driver_receive(fs_state *s, fs_wait *w, int fd, void *buffer, size_t size) {
+#ifdef FARCE_URING
+    struct io_uring_sqe *entry = sqe(s);
+    if (!entry) return errno;
+    io_uring_prep_recv(entry, fd, buffer, size > INT_MAX ? INT_MAX : (unsigned)size, 0);
+#ifdef IORING_RECVSEND_POLL_FIRST
+    entry->ioprio |= IORING_RECVSEND_POLL_FIRST;
+#endif
+    entry->user_data = FS_RECEIVE | NUM2ULL(w->token);
+    w->receive_pending = 1;
+    // Consume every queued SQE while holding the GVL, before Ruby can close or
+    // reopen this fd. SQPOLL is not enabled. The kernel then owns its file ref.
+    while (io_uring_sq_ready(&s->ring)) {
+        int result = io_uring_submit(&s->ring);
+        if (result < 0 && result != -EINTR) return -result;
+    }
+    return 0;
+#else
+    return ENOSYS;
+#endif
+}
+
+int fs_driver_update(fs_state *s, fs_reg *reg, int events) {
+    uint64_t previous = reg->generation;
+    uint64_t generation = ++s->generation;
+    int old = reg->events;
+#ifdef HAVE_SYS_EPOLL_H
+    if (s->driver == FS_EPOLL) {
+        struct epoll_event ev = {.data.u64 = generation};
+        if (events & FS_READ) ev.events |= EPOLLIN | EPOLLRDHUP;
+        if (events & FS_WRITE) ev.events |= EPOLLOUT;
+        if (events & FS_PRI) ev.events |= EPOLLPRI;
+        int action = !events ? EPOLL_CTL_DEL : old ? EPOLL_CTL_MOD : EPOLL_CTL_ADD;
+        if (epoll_ctl(s->descriptor, action, reg->fd, &ev) < 0 &&
+            !(events == 0 && (errno == ENOENT || errno == EBADF))) return errno;
+    }
+#endif
+#ifdef HAVE_SYS_EVENT_H
+    if (s->driver == FS_KQUEUE) {
+        struct timespec zero = {0, 0};
+        for (int bit = FS_READ; bit <= FS_WRITE; bit <<= 1) {
+            if (!(old & bit) && !(events & bit)) continue;
+            if (reg->poll_events & bit) continue;
+            if (bit != FS_PRI) {
+                if (s->change_count == s->change_capacity) {
+                    s->change_capacity = s->change_capacity ? s->change_capacity * 2 : 256;
+                    REALLOC_N(s->changes, struct kevent, s->change_capacity);
+                }
+                struct kevent *change = &s->changes[s->change_count++];
+                EV_SET(change, reg->fd, bit == FS_READ ? EVFILT_READ : EVFILT_WRITE,
+                    events & bit ? EV_ADD | EV_ENABLE : EV_DELETE, 0, 0, (void *)(uintptr_t)generation);
+                continue;
+            }
+            struct kevent change, result;
+            EV_SET(&change, reg->fd, bit == FS_READ ? EVFILT_READ : bit == FS_WRITE ? EVFILT_WRITE : EVFILT_EXCEPT,
+                (events & bit ? EV_ADD | EV_ENABLE : EV_DELETE) | EV_RECEIPT, bit == FS_PRI ? NOTE_OOB : 0, 0,
+                (void *)(uintptr_t)generation);
+            int count = kevent(s->descriptor, &change, 1, &result, 1, &zero);
+            if (count < 0) return errno;
+            // EVFILT_EXCEPT is not supported by every descriptor (e.g. pipes).
+            // Retain the logical interest and snapshot it with poll instead.
+            if (count && bit == FS_PRI && (events & bit) &&
+                (result.data == EINVAL || result.data == ENOTSUP)) {
+                reg->poll_events |= bit;
+                s->polling_regs++;
+                continue;
+            }
+            if (count && result.data && !(!(events & bit) &&
+                (result.data == ENOENT || result.data == EBADF))) return (int)result.data;
+        }
+    }
+#endif
+#ifdef FARCE_URING
+    if (s->driver == FS_URING_DRIVER) {
+        if (old) {
+            struct io_uring_sqe *entry = sqe(s);
+            if (!entry) return errno;
+            io_uring_prep_poll_remove(entry, previous);
+            entry->user_data = 0; // cancellation acknowledgement has no storage pointer
+        }
+        if (events) {
+            struct io_uring_sqe *entry = sqe(s);
+            if (!entry) return errno;
+            unsigned mask = 0;
+            if (events & FS_READ) mask |= POLLIN;
+            if (events & FS_WRITE) mask |= POLLOUT;
+            if (events & FS_PRI) mask |= POLLPRI;
+            io_uring_prep_poll_add(entry, reg->fd, mask);
+            entry->user_data = generation;
+        }
+    }
+#endif
+    if (previous) { st_data_t key = previous; st_delete(s->generations, &key, NULL); }
+    reg->generation = generation;
+    reg->events = events;
+    if (events) st_insert(s->generations, generation, (st_data_t)reg);
+    return 0;
+}
+
+void *fs_driver_poll(void *data) {
+    fs_state *s = data;
+    s->event_count = s->poll_error = 0;
+    struct timespec t = relative_time(s->timeout < 0 ? 0 : s->timeout);
+#ifdef HAVE_SYS_EPOLL_H
+    if (s->driver == FS_EPOLL) {
+        struct epoll_event events[FS_EVENTS];
+        int n;
+#ifdef HAVE_EPOLL_PWAIT2
+        n = epoll_pwait2(s->descriptor, events, FS_EVENTS, s->timeout < 0 ? NULL : &t, NULL);
+        if (n < 0 && errno == ENOSYS)
+#endif
+        n = epoll_wait(s->descriptor, events, FS_EVENTS,
+            s->timeout < 0 ? -1 : (int)fmin(ceil(s->timeout * 1000), INT_MAX));
+        if (n < 0) { s->poll_error = errno; return NULL; }
+        for (int i = 0; i < n; i++) {
+            uint32_t e = events[i].events;
+            int mask = 0;
+            if (e & (EPOLLIN | EPOLLRDHUP | EPOLLHUP | EPOLLERR)) mask |= FS_READ;
+            if (e & (EPOLLOUT | EPOLLHUP | EPOLLERR)) mask |= FS_WRITE;
+            if (e & EPOLLPRI) mask |= FS_PRI;
+            s->events[s->event_count++] = (fs_event){events[i].data.u64, mask, 0};
+        }
+    }
+#endif
+#ifdef HAVE_SYS_EVENT_H
+    if (s->driver == FS_KQUEUE) {
+        struct kevent events[FS_EVENTS];
+        int n = kevent(s->descriptor, s->changes, s->change_count, events, FS_EVENTS, s->timeout < 0 ? NULL : &t);
+        if (n < 0) { s->poll_error = errno; return NULL; }
+        s->change_count = 0;
+        for (int i = 0; i < n; i++)
+            s->events[s->event_count++] = (fs_event){(uint64_t)(uintptr_t)events[i].udata,
+                events[i].filter == EVFILT_READ ? FS_READ : events[i].filter == EVFILT_WRITE ? FS_WRITE : FS_PRI,
+                events[i].flags & EV_ERROR ? (int)events[i].data : 0};
+    }
+#endif
+#ifdef FARCE_URING
+    if (s->driver == FS_URING_DRIVER) {
+        int result = io_uring_submit(&s->ring);
+        if (result < 0) { s->poll_error = -result; return NULL; }
+        struct io_uring_cqe *cqe;
+        if (s->timeout != 0 && io_uring_peek_cqe(&s->ring, &cqe) == -EAGAIN) {
+            struct __kernel_timespec kt = {t.tv_sec, t.tv_nsec};
+            result = s->timeout < 0 ? io_uring_wait_cqe(&s->ring, &cqe) :
+                io_uring_wait_cqe_timeout(&s->ring, &cqe, &kt);
+            if (result < 0 && result != -ETIME && result != -EINTR) s->poll_error = -result;
+        }
+        unsigned head, consumed = 0;
+        io_uring_for_each_cqe(&s->ring, head, cqe) {
+            if (s->event_count == FS_EVENTS) break;
+            consumed++;
+            if (cqe->user_data && cqe->user_data != LIBURING_UDATA_TIMEOUT) {
+                int e = cqe->res, mask = 0;
+                if (!(cqe->user_data & FS_RECEIVE) && e >= 0) {
+                    if (e & (POLLIN | POLLHUP | POLLERR)) mask |= FS_READ;
+                    if (e & (POLLOUT | POLLHUP | POLLERR)) mask |= FS_WRITE;
+                    if (e & POLLPRI) mask |= FS_PRI;
+                }
+                s->events[s->event_count++] = (fs_event){cqe->user_data, mask,
+                    cqe->user_data & FS_RECEIVE ? e : e < 0 && e != -ECANCELED ? -e : 0};
+            }
+        }
+        io_uring_cq_advance(&s->ring, consumed);
+    }
+#endif
+    return NULL;
+}
+
+void fs_driver_close(fs_state *s) {
+#ifdef HAVE_SYS_EVENT_H
+    xfree(s->changes); s->changes = NULL;
+    s->change_count = s->change_capacity = 0;
+#endif
+#ifdef FARCE_URING
+    if (s->ring_live) { io_uring_queue_exit(&s->ring); s->ring_live = 0; }
+#endif
+    if (s->descriptor >= 0) { close(s->descriptor); s->descriptor = -1; }
+}

data/ext/farce/exchanger.c

@@ -0,0 +1,299 @@
+#include "containers.h"
+#include "ruby/io.h"
+
+#include <errno.h>
+#include <fcntl.h>
+#include <math.h>
+#include <time.h>
+#include <unistd.h>
+
+static VALUE cExchanger;
+
+typedef struct {
+    int read_fd;
+    int write_fd;
+} exchanger_signal_t;
+
+typedef struct exchanger_waiter {
+    VALUE offered;
+    VALUE received;
+    exchanger_signal_t signal;
+    bool matched;
+} exchanger_waiter_t;
+
+typedef struct {
+    pthread_mutex_t lock;
+    exchanger_waiter_t *waiting;
+    bool initialized;
+} exchanger_t;
+
+typedef struct {
+    bool finite;
+    double deadline;
+} exchanger_timeout_t;
+
+typedef struct {
+    exchanger_t *exchanger;
+    exchanger_waiter_t *waiter;
+    exchanger_timeout_t *timeout;
+} exchanger_wait_context_t;
+
+static void
+exchanger_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
+}
+
+static bool
+exchanger_signal_initialize(exchanger_signal_t *signal)
+{
+    int descriptors[2];
+    if (pipe(descriptors) != 0) return false;
+    signal->read_fd = descriptors[0];
+    signal->write_fd = descriptors[1];
+    exchanger_set_fd_flags(signal->read_fd);
+    exchanger_set_fd_flags(signal->write_fd);
+    return true;
+}
+
+static void
+exchanger_signal_close(exchanger_signal_t *signal)
+{
+    if (signal->read_fd >= 0) close(signal->read_fd);
+    if (signal->write_fd >= 0) close(signal->write_fd);
+    signal->read_fd = -1;
+    signal->write_fd = -1;
+}
+
+static void
+exchanger_signal_set(exchanger_signal_t *signal)
+{
+    unsigned char byte = 1;
+    ssize_t result;
+
+    do {
+        result = write(signal->write_fd, &byte, 1);
+    } while (result < 0 && errno == EINTR);
+}
+
+static double
+exchanger_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 exchanger_timeout_t
+exchanger_parse_timeout(VALUE timeout)
+{
+    exchanger_timeout_t parsed = {.finite = false, .deadline = 0};
+    if (NIL_P(timeout)) return parsed;
+
+    double seconds = NUM2DBL(timeout);
+    if (!isfinite(seconds) || seconds < 0) {
+        rb_raise(rb_eArgError, "timeout must be a finite, non-negative number or nil");
+    }
+    parsed.finite = true;
+    parsed.deadline = exchanger_monotonic_now() + seconds;
+    return parsed;
+}
+
+static bool
+exchanger_wait_for_descriptor(int fd, exchanger_timeout_t *timeout)
+{
+    VALUE wait_timeout = Qnil;
+    if (timeout->finite) {
+        double remaining = timeout->deadline - exchanger_monotonic_now();
+        if (remaining <= 0) return false;
+        wait_timeout = DBL2NUM(remaining);
+    }
+
+    return containers_wait_for_readable(fd, wait_timeout);
+}
+
+static void
+exchanger_free(void *pointer)
+{
+    exchanger_t *exchanger = pointer;
+    pthread_mutex_destroy(&exchanger->lock);
+    ruby_xfree(exchanger);
+}
+
+static size_t
+exchanger_memsize(const void *pointer)
+{
+    return pointer ? sizeof(exchanger_t) : 0;
+}
+
+static const rb_data_type_t exchanger_type = {
+    .wrap_struct_name = "Ractor::Containers::Exchanger",
+    .function = {
+        .dmark = NULL,
+        .dfree = exchanger_free,
+        .dsize = exchanger_memsize,
+        .dcompact = NULL,
+    },
+    .flags = RUBY_TYPED_FROZEN_SHAREABLE,
+};
+
+static VALUE
+exchanger_allocate(VALUE klass)
+{
+    exchanger_t *exchanger;
+    VALUE object = TypedData_Make_Struct(klass, exchanger_t, &exchanger_type, exchanger);
+    pthread_mutex_init(&exchanger->lock, NULL);
+    exchanger->waiting = NULL;
+    exchanger->initialized = false;
+    return object;
+}
+
+static exchanger_t *
+get_exchanger(VALUE self)
+{
+    exchanger_t *exchanger;
+    TypedData_Get_Struct(self, exchanger_t, &exchanger_type, exchanger);
+    if (!exchanger->initialized) rb_raise(rb_eRuntimeError, "uninitialized Exchanger");
+    return exchanger;
+}
+
+static VALUE
+exchanger_frozen_p(VALUE self)
+{
+    (void)self;
+    return Qfalse;
+}
+
+static VALUE
+exchanger_freeze(VALUE self)
+{
+    containers_raise_unfreezable(self);
+    return Qnil;
+}
+
+static VALUE
+exchanger_initialize(VALUE self)
+{
+    exchanger_t *exchanger;
+    TypedData_Get_Struct(self, exchanger_t, &exchanger_type, exchanger);
+    if (exchanger->initialized) rb_raise(rb_eRuntimeError, "Exchanger is already initialized");
+    exchanger->initialized = true;
+    containers_publish_native_reference_free(self);
+    return self;
+}
+
+static VALUE
+exchanger_wait_body(VALUE opaque)
+{
+    exchanger_wait_context_t *context = (exchanger_wait_context_t *)opaque;
+    return exchanger_wait_for_descriptor(context->waiter->signal.read_fd, context->timeout)
+        ? Qtrue
+        : Qfalse;
+}
+
+static VALUE
+exchanger_wait_cleanup(VALUE opaque)
+{
+    exchanger_wait_context_t *context = (exchanger_wait_context_t *)opaque;
+    pthread_mutex_lock(&context->exchanger->lock);
+    if (context->exchanger->waiting == context->waiter) {
+        context->exchanger->waiting = NULL;
+    }
+    pthread_mutex_unlock(&context->exchanger->lock);
+    exchanger_signal_close(&context->waiter->signal);
+    return Qnil;
+}
+
+static VALUE
+exchanger_exchange(int argc, VALUE *argv, VALUE self)
+{
+    VALUE offered;
+    VALUE keywords = Qnil;
+    VALUE timeout_value = Qnil;
+    ID keyword_ids[] = {rb_intern("timeout")};
+    VALUE keyword_values[1];
+
+    rb_scan_args(argc, argv, "1:", &offered, &keywords);
+    if (!NIL_P(keywords)) {
+        rb_get_kwargs(keywords, keyword_ids, 0, 1, keyword_values);
+        if (keyword_values[0] != Qundef) timeout_value = keyword_values[0];
+    }
+
+    containers_check_shareable(offered);
+    exchanger_timeout_t timeout = exchanger_parse_timeout(timeout_value);
+    exchanger_t *exchanger = get_exchanger(self);
+
+    pthread_mutex_lock(&exchanger->lock);
+    if (exchanger->waiting != NULL) {
+        exchanger_waiter_t *partner = exchanger->waiting;
+        exchanger->waiting = NULL;
+        VALUE received = partner->offered;
+        partner->received = offered;
+        partner->matched = true;
+        exchanger_signal_set(&partner->signal);
+        pthread_mutex_unlock(&exchanger->lock);
+        RB_GC_GUARD(offered);
+        return received;
+    }
+
+    if (timeout.finite && timeout.deadline <= exchanger_monotonic_now()) {
+        pthread_mutex_unlock(&exchanger->lock);
+        return rb_block_given_p() ? rb_yield_values(0) : Qnil;
+    }
+
+    exchanger_waiter_t waiter = {
+        .offered = offered,
+        .received = Qnil,
+        .signal = {.read_fd = -1, .write_fd = -1},
+        .matched = false,
+    };
+    if (!exchanger_signal_initialize(&waiter.signal)) {
+        int error = errno;
+        pthread_mutex_unlock(&exchanger->lock);
+        errno = error;
+        rb_sys_fail("pipe");
+    }
+    exchanger->waiting = &waiter;
+    pthread_mutex_unlock(&exchanger->lock);
+
+    exchanger_wait_context_t context = {
+        .exchanger = exchanger,
+        .waiter = &waiter,
+        .timeout = &timeout,
+    };
+    (void)rb_ensure(
+        exchanger_wait_body,
+        (VALUE)&context,
+        exchanger_wait_cleanup,
+        (VALUE)&context
+    );
+
+    RB_GC_GUARD(offered);
+    RB_GC_GUARD(waiter.received);
+    if (waiter.matched) return waiter.received;
+    return rb_block_given_p() ? rb_yield_values(0) : Qnil;
+}
+
+void
+containers_init_exchanger(VALUE namespace)
+{
+    cExchanger = rb_define_class_under(namespace, "Exchanger", rb_cObject);
+    rb_define_alloc_func(cExchanger, exchanger_allocate);
+    rb_define_method(cExchanger, "initialize", exchanger_initialize, 0);
+    rb_define_method(cExchanger, "exchange", exchanger_exchange, -1);
+    rb_define_method(cExchanger, "freeze", exchanger_freeze, 0);
+    rb_define_method(cExchanger, "frozen?", exchanger_frozen_p, 0);
+}