farce 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a54fa924e64dc2414043e8b2593f6f977cb4a553f0b7fc9987dfffdb7ec9bbc3
-  data.tar.gz: ee1c903cd360e77f7ad7449708d57bf69e25ec8cec02b144ff138a4b1ab00095
+  metadata.gz: daac1fc9dbb66e9473f1a61dc6fcaf4a4a0875a9c9f98670d47759d450f2b248
+  data.tar.gz: 3991bfd67d083fe58cd0e808f810e49809d667c11a005f68e63887cd29038b79
 SHA512:
-  metadata.gz: fb0ba4de83addaf9f18c0316e9f325ed52f4d93ec6b81ffc500b6a332fe4fdf9a2d9a46fc5f17e5d011f881ca98e04569d433ecfa3add068fd9be6f3b28c2e7d
-  data.tar.gz: 12d9b698ae002087dbad1637af1c52993b56ffd1b001bcd1aa22c055099ba67cd7896fe8b3104561ee1b6a6fccdffa4bf6282ec63ba4b9daf8a5f538f0da2ed4
+  metadata.gz: 0cbcf7e5769c5084198c06576d27d919501c5a54eafaacd0dccb8d268db416e784ac3556e773a64a4380a4f5c18cbe65fdedfb040ec5c4b0342c75d68eddaae0
+  data.tar.gz: 142f08011fd2704395a1d7ed3f04366e425f9f6a539ef525206b41c14707b03abc4f71d62c53ddcd1a634d11ddf1bcf14f62da034eec94b86ff31905069c78b2

data/CHANGELOG.md

@@ -4,6 +4,12 @@ Farce follows [Semantic Versioning 2.0](http://semver.org/). Any public method o
 
 ## Development Releases
 
+### Farce 0.4.1 (2026-10-16)
+
+* Make sure prebuilt Linux binaries include liburing support.
+* Use a Futex for efficient fiber synchronization if possible.
+* Consistent `wrap_struct_name` across the native extension for debugging.
+
 ### Farce 0.4.0 (2026-10-16)
 
 #### New Features

data/ext/farce/LIBURING-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2020 Jens Axboe
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/ext/farce/atom.c

@@ -1,14 +1,12 @@
 #include "containers.h"
+#include "native_wait.h"
 #include "transaction.h"
 #include "ruby/fiber/scheduler.h"
-#include "ruby/io.h"
 
 #include <errno.h>
-#include <fcntl.h>
 #include <math.h>
 #include <stdint.h>
 #include <time.h>
-#include <unistd.h>
 
 static VALUE cAtom;
 #ifdef RC_HAVE_NATIVE_WEAK_REFERENCES
@@ -24,9 +22,7 @@ bool rb_gc_handle_weak_references_alive_p(VALUE object);
 typedef struct atom_waiter atom_waiter_t;
 
 struct atom_waiter {
-    int read_fd;
-    int write_fd;
-    bool notified;
+    containers_waiter_t notification;
     atom_waiter_t *next;
 };
 
@@ -105,35 +101,13 @@ atom_parse_timeout(VALUE timeout)
     return parsed;
 }
 
-static void
-atom_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 atom->lock held. Every waiter owns a separate descriptor, so a
- * single state transition can wake all waiters without consuming a shared
- * notification. */
+/* Called with atom->lock held. Every registration owns an independent
+ * notification so a transition can wake all waiters. */
 static void
 atom_notify_waiters(atom_t *atom)
 {
-    unsigned char byte = 1;
     for (atom_waiter_t *waiter = atom->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;
-        }
+        (void)containers_waiter_notify(&waiter->notification);
     }
 }
 
@@ -201,7 +175,7 @@ atom_memsize(const void *pointer)
 }
 
 static const rb_data_type_t atom_type = {
-    .wrap_struct_name = "Ractor::Containers::Atom",
+    .wrap_struct_name = "Farce::Internal::Atom",
     .function = {
         .dmark = atom_mark,
         .dfree = atom_free,
@@ -352,23 +326,24 @@ typedef struct {
     atom_timeout_t *timeout;
 } atom_wait_context_t;
 
-static bool
-atom_wait_for_descriptor(int fd, atom_timeout_t *timeout)
-{
-    VALUE wait_timeout = Qnil;
-    if (timeout->finite) {
-        double remaining = timeout->deadline - atom_monotonic_now();
-        if (remaining <= 0) return false;
-        wait_timeout = DBL2NUM(remaining);
-    }
-    return containers_wait_for_readable(fd, wait_timeout);
-}
-
 static VALUE
 atom_wait_body(VALUE opaque)
 {
     atom_wait_context_t *context = (atom_wait_context_t *)opaque;
-    return atom_wait_for_descriptor(context->waiter.read_fd, context->timeout) ? Qtrue : Qfalse;
+    atom_timeout_t *timeout = context->timeout;
+    int error = 0;
+    bool awakened = containers_waiter_wait(
+        &context->waiter.notification, &context->atom->lock,
+        timeout->finite, timeout->deadline, &error
+    );
+    if (error) {
+        double seconds = timeout->finite ? timeout->deadline - atom_monotonic_now() : 0;
+        if ((error == EMFILE || error == ENFILE) && timeout->finite && seconds <= 0) return Qfalse;
+        VALUE remaining = timeout->finite ? DBL2NUM(seconds) : Qnil;
+        containers_wait_without_descriptor(error, "pipe", &timeout->collected, remaining);
+        return Qtrue;
+    }
+    return awakened ? Qtrue : Qfalse;
 }
 
 static VALUE
@@ -385,8 +360,7 @@ atom_wait_cleanup(VALUE opaque)
         }
     }
     pthread_mutex_unlock(&context->atom->lock);
-    close(context->waiter.read_fd);
-    close(context->waiter.write_fd);
+    containers_waiter_close(&context->waiter.notification);
     return Qnil;
 }
 
@@ -394,29 +368,12 @@ atom_wait_cleanup(VALUE opaque)
 static bool
 atom_wait_once(atom_t *atom, atom_timeout_t *timeout)
 {
-    int descriptors[2];
-    if (pipe(descriptors) != 0) {
-        int error = errno;
-        pthread_mutex_unlock(&atom->lock);
-        double seconds = timeout->finite ? timeout->deadline - atom_monotonic_now() : 0;
-        if ((error == EMFILE || error == ENFILE) && timeout->finite && seconds <= 0) return false;
-        VALUE remaining = timeout->finite ? DBL2NUM(seconds) : Qnil;
-        containers_wait_without_descriptor(error, "pipe", &timeout->collected, remaining);
-        return true;
-    }
-    atom_set_fd_flags(descriptors[0]);
-    atom_set_fd_flags(descriptors[1]);
-
     atom_wait_context_t context = {
         .atom = atom,
-        .waiter = {
-            .read_fd = descriptors[0],
-            .write_fd = descriptors[1],
-            .notified = false,
-            .next = atom->waiters,
-        },
+        .waiter = {.next = atom->waiters},
         .timeout = timeout,
     };
+    containers_waiter_init(&context.waiter.notification);
     atom->waiters = &context.waiter;
     pthread_mutex_unlock(&atom->lock);
     return RTEST(rb_ensure(atom_wait_body, (VALUE)&context, atom_wait_cleanup, (VALUE)&context));

data/ext/farce/counter.c

@@ -55,7 +55,7 @@ RUBY_REFERENCES(counter_references) = {
 };
 
 static const rb_data_type_t counter_type = {
-    .wrap_struct_name = "Ractor::Containers::Counter",
+    .wrap_struct_name = "Farce::Internal::Counter",
     .function = {
         .dmark = RUBY_REFS_LIST_PTR(counter_references),
         .dfree = counter_free,

data/ext/farce/depend

@@ -1,12 +1,20 @@
 bounded_map.o: bounded_map.c containers.h
 dict.o: dict.c dict.h
-farce.o: farce.c containers.h shareable.h
-lock.o: lock.c containers.h
-priority_queue.o: priority_queue.c containers.h dict.h unshared_wait.h
-reactor.o: reactor.c reactor.h
-drivers.o: drivers.c reactor.h
-io.o: io.c reactor.h
-tree_map.o: tree_map.c containers.h
+farce.o: farce.c containers.h shareable.h futex.h
+lock.o: lock.c containers.h native_wait.h futex.h
+priority_queue.o: priority_queue.c containers.h dict.h unshared_wait.h native_wait.h futex.h
+reactor.o: reactor.c reactor.h futex.h
+drivers.o: drivers.c reactor.h futex.h
+io.o: io.c reactor.h futex.h
+tree_map.o: tree_map.c containers.h native_wait.h futex.h
 
 queue.o: queue.c containers.h unshared_wait.h
 unshared_signal.o: unshared_signal.c containers.h unshared_wait.h unshared_io_pool.h
+
+atom.o: atom.c containers.h transaction.h native_wait.h futex.h
+map.o: map.c containers.h transaction.h native_wait.h futex.h
+vector.o: vector.c containers.h transaction.h native_wait.h futex.h
+signal.o: signal.c containers.h native_wait.h futex.h
+futex.o: futex.c futex.h
+native_wait.o: native_wait.c native_wait.h containers.h futex.h
+unsupported.o: unsupported.c futex.h

data/ext/farce/drivers.c

@@ -5,6 +5,9 @@
 #include <limits.h>
 #include <fcntl.h>
 #include <math.h>
+#ifdef FARCE_HAVE_URING_FUTEX
+#include <linux/futex.h>
+#endif
 #ifdef HAVE_SYS_EPOLL_H
 #include <sys/epoll.h>
 #endif
@@ -12,6 +15,16 @@
 #include <sys/event.h>
 #endif
 
+// Keep compiled backends identifiable when static dependency symbols are hidden.
+#ifdef FARCE_URING
+RUBY_FUNC_EXPORTED const char farce_backend_io_uring[];
+const char farce_backend_io_uring[] = "io_uring";
+#endif
+#ifdef HAVE_SYS_EVENT_H
+RUBY_FUNC_EXPORTED const char farce_backend_kqueue[];
+const char farce_backend_kqueue[] = "kqueue";
+#endif
+
 static struct timespec relative_time(double seconds) {
     struct timespec t;
     t.tv_sec = (time_t)seconds;
@@ -38,6 +51,13 @@ int fs_driver_init(fs_state *s, int driver) {
         int result = io_uring_queue_init(1024, &s->ring, 0);
         if (result < 0) return -result;
         s->ring_live = 1;
+#ifdef FARCE_HAVE_URING_FUTEX
+        struct io_uring_probe *probe = io_uring_get_probe_ring(&s->ring);
+        if (probe) {
+            s->futex_supported = io_uring_opcode_supported(probe, IORING_OP_FUTEX_WAIT);
+            io_uring_free_probe(probe);
+        }
+#endif
         return 0;
     }
 #endif
@@ -79,6 +99,28 @@ int fs_driver_receive(fs_state *s, fs_wait *w, int fd, void *buffer, size_t size
 #endif
 }
 
+// Submit one private 32-bit futex wait. The caller retains the word until the
+// original completion has been consumed, including after timeout or cancellation.
+int fs_driver_futex(fs_state *s, fs_wait *w, containers_futex_t *word) {
+#ifdef FARCE_HAVE_URING_FUTEX
+    struct io_uring_sqe *entry = sqe(s);
+    if (!entry) return errno;
+    io_uring_prep_futex_wait(entry, (uint32_t *)&word->value, 0,
+        FUTEX_BITSET_MATCH_ANY, FUTEX_32 | FUTEX_PRIVATE_FLAG, 0);
+    entry->user_data = FS_FUTEX | NUM2ULL(w->token);
+    w->futex_pending = 1;
+    // Submit before yielding. Once queued, cleanup must drain the original CQE
+    // even if submission fails after making some progress.
+    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;
@@ -210,13 +252,13 @@ void *fs_driver_poll(void *data) {
             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 (!(cqe->user_data & FS_OPERATION) && 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};
+                    cqe->user_data & FS_OPERATION ? e : e < 0 && e != -ECANCELED ? -e : 0};
             }
         }
         io_uring_cq_advance(&s->ring, consumed);

data/ext/farce/exchanger.c

@@ -140,7 +140,7 @@ exchanger_memsize(const void *pointer)
 }
 
 static const rb_data_type_t exchanger_type = {
-    .wrap_struct_name = "Ractor::Containers::Exchanger",
+    .wrap_struct_name = "Farce::Internal::Exchanger",
     .function = {
         .dmark = NULL,
         .dfree = exchanger_free,

data/ext/farce/extconf.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
 
 require "mkmf"
 require_relative "../ext_helper"
@@ -44,19 +46,60 @@ end
 
 have_func("sysctlbyname", "sys/sysctl.h") if have_header("sys/sysctl.h")
 
+futex = false
+if enable_config("futex", true) && RUBY_PLATFORM.include?("linux") &&
+    have_header("linux/futex.h") && have_header("sys/syscall.h")
+  futex = try_compile(<<~SOURCE)
+    #include <linux/futex.h>
+    #include <sys/syscall.h>
+    #include <stdint.h>
+    #include <stdatomic.h>
+    #include <time.h>
+    #include <unistd.h>
+
+    _Static_assert(sizeof(_Atomic(uint32_t)) == 4, "32-bit futex word");
+    _Static_assert(_Alignof(_Atomic(uint32_t)) >= 4, "aligned futex word");
+    int main(void) {
+        _Atomic(uint32_t) word = 1;
+        struct timespec now;
+        (void)clock_gettime(CLOCK_MONOTONIC, &now);
+        (void)syscall(SYS_futex, &word, FUTEX_WAIT_PRIVATE, 0, 0, 0, 0);
+        (void)syscall(SYS_futex, &word, FUTEX_WAKE_PRIVATE, 1, 0, 0, 0);
+        return 0;
+    }
+  SOURCE
+end
+$defs << "-DFARCE_HAVE_FUTEX" if futex
+
 epoll = have_header("sys/epoll.h")
 kqueue = have_header("sys/event.h")
 $srcs = %w[
-  atom.c bounded_map.c counter.c darwin.c dict.c exchanger.c farce.c flag.c lock.c map.c priority_queue.c
-  queue.c signal.c transaction.c tree_map.c trie.c unshareable.c unshared_signal.c vector.c weak_map.c
+  atom.c bounded_map.c counter.c darwin.c dict.c exchanger.c farce.c flag.c futex.c lock.c map.c native_wait.c
+  priority_queue.c queue.c signal.c transaction.c tree_map.c trie.c unshareable.c unshared_signal.c vector.c weak_map.c
 ]
 $srcs.concat(epoll || kqueue ? %w[drivers.c io.c reactor.c] : ["unsupported.c"])
 
 if epoll || kqueue
+  dir_config("uring")
   have_func("epoll_pwait2", "sys/epoll.h") if epoll
   have_func("rb_io_timeout", "ruby/io.h")
   if enable_config("io-uring", true) && have_header("liburing.h") && have_library("uring", "io_uring_queue_init")
     $defs << "-DFARCE_HAVE_LIBURING"
+    $DLDFLAGS << " -Wl,--exclude-libs,liburing.a" if enable_config("uring-static", false)
+    if futex && try_compile(<<~SOURCE)
+      #include <linux/futex.h>
+      #include <liburing.h>
+
+      int main(void) {
+          struct io_uring_sqe sqe;
+          uint32_t word = 0;
+          io_uring_prep_futex_wait(&sqe, &word, 0, FUTEX_BITSET_MATCH_ANY,
+              FUTEX_32 | FUTEX_PRIVATE_FLAG, 0);
+          return IORING_OP_FUTEX_WAIT == 0;
+      }
+    SOURCE
+      $defs << "-DFARCE_HAVE_URING_FUTEX"
+    end
   end
 end
 

data/ext/farce/farce.c

@@ -1,4 +1,5 @@
 #include "containers.h"
+#include "futex.h"
 #include "transaction.h"
 #include "shareable.h"
 #include "ruby/fiber/scheduler.h"
@@ -305,6 +306,12 @@ containers_raise_key_error(VALUE receiver, VALUE key)
     rb_exc_raise(exception);
 }
 
+static VALUE
+farce_futex_supported(VALUE namespace)
+{
+    return containers_futex_available() ? Qtrue : Qfalse;
+}
+
 static VALUE
 farce_load_native_fiber_scheduler(VALUE namespace)
 {
@@ -338,6 +345,7 @@ Init_farce(void)
         farce_load_native_fiber_scheduler,
         0
     );
+    rb_define_private_method(singleton, "futex_supported?", farce_futex_supported, 0);
     containers_init_transaction(mInternal);
     containers_init_atom(mInternal);
     containers_init_counter(mInternal);

data/ext/farce/flag.c

@@ -49,7 +49,7 @@ RUBY_REFERENCES(flag_references) = {
 };
 
 static const rb_data_type_t flag_type = {
-    .wrap_struct_name = "Ractor::Containers::Flag",
+    .wrap_struct_name = "Farce::Internal::Flag",
     .function = {
         .dmark = RUBY_REFS_LIST_PTR(flag_references),
         .dfree = flag_free,

data/ext/farce/futex.c

@@ -0,0 +1,76 @@
+#include "futex.h"
+
+#include <errno.h>
+
+#ifdef FARCE_HAVE_FUTEX
+#include <linux/futex.h>
+#include <pthread.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+
+enum { FUTEX_WAITING = 0, FUTEX_NOTIFIED = 1 };
+
+static pthread_once_t futex_probe_once = PTHREAD_ONCE_INIT;
+static int futex_probe_error;
+static bool futex_supported;
+
+static bool
+futex_unsupported_error(int error)
+{
+    return error == ENOSYS || error == EPERM || error == EACCES || error == EOPNOTSUPP;
+}
+
+static void
+futex_probe(void)
+{
+    containers_futex_t futex;
+    atomic_init(&futex.value, FUTEX_NOTIFIED);
+    /* The mismatch never sleeps, including on kernels without futex support. */
+    long result = syscall(SYS_futex, &futex.value, FUTEX_WAIT_PRIVATE,
+        FUTEX_WAITING, NULL, NULL, 0);
+    if (result != -1 || errno != EAGAIN) {
+        futex_probe_error = result == -1 ? errno : EIO;
+        return;
+    }
+    result = syscall(SYS_futex, &futex.value, FUTEX_WAKE_PRIVATE, 1, NULL, NULL, 0);
+    if (result < 0) {
+        futex_probe_error = errno;
+        return;
+    }
+    futex_supported = true;
+}
+
+#endif
+
+bool
+containers_futex_available(void)
+{
+#ifdef FARCE_HAVE_FUTEX
+    int error = pthread_once(&futex_probe_once, futex_probe);
+    if (error) rb_syserr_fail(error, "pthread_once");
+    if (futex_probe_error && !futex_unsupported_error(futex_probe_error)) {
+        rb_syserr_fail(futex_probe_error, "futex capability probe");
+    }
+    return futex_supported;
+#else
+    return false;
+#endif
+}
+
+void
+containers_futex_init(containers_futex_t *futex)
+{
+    atomic_init(&futex->value, 0);
+}
+
+void
+containers_futex_notify(containers_futex_t *futex)
+{
+    atomic_store_explicit(&futex->value, 1, memory_order_release);
+#ifdef FARCE_HAVE_FUTEX
+    int saved_errno = errno;
+    while (syscall(SYS_futex, &futex->value, FUTEX_WAKE_PRIVATE,
+        1, NULL, NULL, 0) < 0 && errno == EINTR) {}
+    errno = saved_errno;
+#endif
+}

data/ext/farce/futex.h

@@ -0,0 +1,31 @@
+#ifndef FARCE_FUTEX_H
+#define FARCE_FUTEX_H
+
+#include "ruby.h"
+
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdatomic.h>
+
+/* Each registered waiter owns this word until all native waits have ended. */
+typedef struct {
+    _Atomic(uint32_t) value;
+} containers_futex_t;
+
+_Static_assert(sizeof(containers_futex_t) == 4, "a futex word must contain exactly 32 bits");
+_Static_assert(_Alignof(containers_futex_t) >= 4, "a futex word must be four-byte aligned");
+
+/* Call without native container locks. Unsupported builds and kernels return false. */
+bool containers_futex_available(void);
+/* These two operations are native-only and may run under a container mutex. */
+void containers_futex_init(containers_futex_t *futex);
+void containers_futex_notify(containers_futex_t *futex);
+
+/* Scheduler support is opt-in and never blocks an unsupported event loop. */
+bool containers_futex_scheduler_supported(VALUE scheduler);
+/* True requests a condition/deadline recheck after notification or backend
+ * rejection. False means the scheduler timer expired. Every caller still
+ * rechecks synchronized state and its original absolute deadline. */
+bool containers_futex_scheduler_wait(VALUE scheduler, containers_futex_t *futex, VALUE timeout);
+
+#endif