cruise 0.1.0 → 0.2.1

data/ext/cruise/src/ffi.rs

@@ -0,0 +1,124 @@
+//! C ABI for Cruise.
+//!
+//! # Safety
+//!
+//! Pointer arguments must be valid (or null where documented). String arrays
+//! are `(pointer, count)` pairs of NUL-terminated UTF-8 C strings. Any C string
+//! returned through an out-parameter is heap-allocated by Rust and must be
+//! released with [`cruise_string_free`]; the watcher handle with
+//! [`cruise_watcher_free`]. The read fd returned by [`cruise_watcher_new`] is
+//! transferred to the caller, who is responsible for closing it.
+
+#![allow(clippy::missing_safety_doc)]
+
+use std::ffi::{CStr, CString};
+use std::os::raw::{c_char, c_int};
+use std::ptr;
+
+use crate::Watcher;
+
+/// A single filesystem event handed to the C side. Both strings are owned by
+/// the caller once populated and must be freed with [`cruise_string_free`].
+#[repr(C)]
+pub struct CruiseEvent {
+  pub path: *mut c_char,
+  pub kind: *mut c_char,
+}
+
+unsafe fn c_string_array(pointer: *const *const c_char, count: usize) -> Vec<String> {
+  if pointer.is_null() || count == 0 {
+    return Vec::new();
+  }
+
+  std::slice::from_raw_parts(pointer, count)
+    .iter()
+    .filter_map(|&entry| {
+      if entry.is_null() {
+        None
+      } else {
+        CStr::from_ptr(entry).to_str().ok().map(|value| value.to_string())
+      }
+    })
+    .collect()
+}
+
+/// Create a watcher over `paths`, filtered by `globs` and `only_kinds`.
+///
+/// On success returns a heap-allocated handle and writes the read end of the
+/// event pipe to `out_read_fd` (ownership transfers to the caller). On error
+/// returns null and, when `out_error` is non-null, writes a message to be freed
+/// with [`cruise_string_free`].
+#[no_mangle]
+pub unsafe extern "C" fn cruise_watcher_new(
+  paths: *const *const c_char,
+  path_count: usize,
+  debounce: f64,
+  globs: *const *const c_char,
+  glob_count: usize,
+  only_kinds: *const *const c_char,
+  only_count: usize,
+  out_read_fd: *mut c_int,
+  out_error: *mut *mut c_char,
+) -> *mut Watcher {
+  let paths = c_string_array(paths, path_count);
+  let globs = c_string_array(globs, glob_count);
+  let only = c_string_array(only_kinds, only_count);
+
+  match Watcher::new(&paths, debounce, &globs, only) {
+    Ok((watcher, read_fd)) => {
+      if !out_read_fd.is_null() {
+        *out_read_fd = read_fd;
+      }
+
+      Box::into_raw(Box::new(watcher))
+    }
+    Err(message) => {
+      if !out_error.is_null() {
+        *out_error = CString::new(message).unwrap_or_default().into_raw();
+      }
+
+      ptr::null_mut()
+    }
+  }
+}
+
+/// Non-blocking: pop the next queued event into `out_event` and return true, or
+/// return false if the queue is empty. Never touches Ruby and never blocks — the
+/// C wrapper waits on the pipe fd instead.
+#[no_mangle]
+pub unsafe extern "C" fn cruise_watcher_poll(watcher: *mut Watcher, out_event: *mut CruiseEvent) -> bool {
+  if watcher.is_null() {
+    return false;
+  }
+
+  let watcher = &*watcher;
+
+  match watcher.poll() {
+    Some((path, kind)) => {
+      if !out_event.is_null() {
+        (*out_event).path = CString::new(path).unwrap_or_default().into_raw();
+        (*out_event).kind = CString::new(kind).unwrap_or_default().into_raw();
+      }
+
+      true
+    }
+    None => false,
+  }
+}
+
+/// Free a watcher handle. Stops watching, joins the background thread, and
+/// closes the write end of the pipe (the reader then observes EOF).
+#[no_mangle]
+pub unsafe extern "C" fn cruise_watcher_free(watcher: *mut Watcher) {
+  if !watcher.is_null() {
+    drop(Box::from_raw(watcher));
+  }
+}
+
+/// Free a string previously returned by this library.
+#[no_mangle]
+pub unsafe extern "C" fn cruise_string_free(s: *mut c_char) {
+  if !s.is_null() {
+    drop(CString::from_raw(s));
+  }
+}

data/ext/cruise/src/lib.rs

@@ -1,213 +1,11 @@
-use std::path::PathBuf;
+//! Cruise - a fast, OS-native file watcher.
+//!
+//! This crate contains the platform-agnostic watching logic ([`watcher`]) and a
+//! C ABI ([`ffi`]) that a thin Ruby C extension links against. It deliberately
+//! knows nothing about Ruby: it hands filtered `(path, kind)` pairs across the
+//! FFI boundary and lets the C wrapper turn them into Ruby objects.
 
-use globset::{Glob, GlobSet, GlobSetBuilder};
-use magnus::{method, prelude::*, value::Lazy, Error, IntoValue, RClass, RModule, Ruby, Value};
+mod ffi;
+mod watcher;
 
-use notify::event::{CreateKind, ModifyKind, RemoveKind};
-use notify::{EventKind, RecursiveMode};
-use notify_debouncer_full::{new_debouncer, DebounceEventResult};
-
-static MODULE: Lazy<RModule> = Lazy::new(|ruby| ruby.define_module("Cruise").expect("failed to define Cruise module"));
-
-static EVENT_CLASS: Lazy<RClass> = Lazy::new(|ruby| {
-  let module = ruby.get_inner(&MODULE);
-  let class = module.define_class("Event", ruby.class_object()).expect("failed to define Cruise::Event class");
-
-  class
-    .define_method("path", method!(CruiseEvent::path, 0))
-    .expect("failed to define path method");
-
-  class
-    .define_method("kind", method!(CruiseEvent::kind, 0))
-    .expect("failed to define kind method");
-
-  class
-    .define_method("inspect", method!(CruiseEvent::inspect, 0))
-    .expect("failed to define inspect method");
-
-  class
-    .define_method("to_s", method!(CruiseEvent::to_s, 0))
-    .expect("failed to define to_s method");
-
-  class
-});
-
-#[magnus::wrap(class = "Cruise::Event", free_immediately)]
-struct CruiseEvent {
-  path: String,
-  kind: String,
-}
-
-impl CruiseEvent {
-  fn path(&self) -> &str {
-    &self.path
-  }
-
-  fn kind(&self) -> &str {
-    &self.kind
-  }
-
-  fn inspect(&self) -> String {
-    format!("#<Cruise::Event kind={:?} path={:?}>", self.kind, self.path)
-  }
-
-  fn to_s(&self) -> String {
-    format!("{}: {}", self.kind, self.path)
-  }
-}
-
-fn event_kind_to_string(kind: &EventKind) -> &'static str {
-  match kind {
-    EventKind::Create(CreateKind::File) => "created",
-    EventKind::Create(CreateKind::Folder) => "created",
-    EventKind::Create(_) => "created",
-    EventKind::Modify(ModifyKind::Data(_)) => "modified",
-    EventKind::Modify(ModifyKind::Name(_)) => "renamed",
-    EventKind::Modify(_) => "modified",
-    EventKind::Remove(RemoveKind::File) => "removed",
-    EventKind::Remove(RemoveKind::Folder) => "removed",
-    EventKind::Remove(_) => "removed",
-    EventKind::Access(_) => "accessed",
-    EventKind::Any | EventKind::Other => "changed",
-  }
-}
-
-fn build_glob_set(patterns: Vec<String>) -> Result<Option<GlobSet>, Error> {
-  if patterns.is_empty() {
-    return Ok(None);
-  }
-
-  let mut builder = GlobSetBuilder::new();
-
-  for pattern in &patterns {
-    let glob = Glob::new(pattern).map_err(|error| {
-      Error::new(
-        magnus::Ruby::get().unwrap().exception_arg_error(),
-        format!("Invalid glob pattern '{}': {}", pattern, error),
-      )
-    })?;
-    builder.add(glob);
-  }
-
-  let set = builder.build().map_err(|error| {
-    Error::new(
-      magnus::Ruby::get().unwrap().exception_runtime_error(),
-      format!("Failed to build glob set: {}", error),
-    )
-  })?;
-
-  Ok(Some(set))
-}
-
-enum WaitResult {
-  Event(notify::Event),
-  Timeout,
-  Disconnected,
-}
-
-unsafe extern "C" fn wait_for_event(data: *mut std::ffi::c_void) -> *mut std::ffi::c_void {
-  let receiver = unsafe { &*(data as *const std::sync::mpsc::Receiver<notify::Event>) };
-
-  let result = match receiver.recv_timeout(std::time::Duration::from_millis(200)) {
-    Ok(event) => Box::new(WaitResult::Event(event)),
-    Err(std::sync::mpsc::RecvTimeoutError::Timeout) => Box::new(WaitResult::Timeout),
-    Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => Box::new(WaitResult::Disconnected),
-  };
-
-  Box::into_raw(result) as *mut std::ffi::c_void
-}
-
-unsafe extern "C" fn unblock_wait(_data: *mut std::ffi::c_void) {}
-
-fn watch(
-  ruby: &Ruby,
-  paths: Vec<String>,
-  callback: magnus::block::Proc,
-  debounce: f64,
-  glob_patterns: Vec<String>,
-  only_kinds: Vec<String>,
-) -> Result<magnus::Value, Error> {
-  let debounce_duration = std::time::Duration::from_secs_f64(debounce);
-  let glob_set = build_glob_set(glob_patterns)?;
-  let filter_kinds = if only_kinds.is_empty() { None } else { Some(only_kinds) };
-
-  let (sender, receiver) = std::sync::mpsc::channel::<notify::Event>();
-
-  let mut debouncer = new_debouncer(debounce_duration, None, move |result: DebounceEventResult| {
-    if let Ok(events) = result {
-      for debounced_event in events {
-        let _ = sender.send(debounced_event.event);
-      }
-    }
-  })
-  .map_err(|error| Error::new(ruby.exception_runtime_error(), format!("Failed to create watcher: {error}")))?;
-
-  for path in &paths {
-    let watch_path = PathBuf::from(path);
-
-    if !watch_path.exists() {
-      return Err(Error::new(ruby.exception_arg_error(), format!("Path does not exist: {}", watch_path.display())));
-    }
-
-    debouncer
-      .watch(&watch_path, RecursiveMode::Recursive)
-      .map_err(|error| Error::new(ruby.exception_runtime_error(), format!("Failed to watch path: {error}")))?;
-  }
-
-  loop {
-    let result = unsafe {
-      rb_sys::rb_thread_call_without_gvl(
-        Some(wait_for_event),
-        &receiver as *const _ as *mut std::ffi::c_void,
-        Some(unblock_wait),
-        std::ptr::null_mut(),
-      )
-    };
-
-    let wait_result = unsafe { *Box::from_raw(result as *mut WaitResult) };
-
-    match &wait_result {
-      WaitResult::Event(event) => {
-        let kind_string = event_kind_to_string(&event.kind);
-
-        if let Some(ref allowed) = filter_kinds {
-          if !allowed.iter().any(|kind| kind == kind_string) {
-            continue;
-          }
-        }
-
-        for path in &event.paths {
-          if let Some(ref globs) = glob_set {
-            if !globs.is_match(path) {
-              continue;
-            }
-          }
-
-          let cruise_event = CruiseEvent {
-            path: path.to_string_lossy().to_string(),
-            kind: kind_string.to_string(),
-          };
-
-          let value: Value = cruise_event.into_value_with(ruby);
-          callback.call::<_, Value>((value,))?;
-        }
-      }
-      WaitResult::Timeout => {
-        continue;
-      }
-      WaitResult::Disconnected => {
-        return Err(Error::new(ruby.exception_runtime_error(), "Watcher channel disconnected unexpectedly"));
-      }
-    }
-  }
-}
-
-#[magnus::init]
-fn init(ruby: &Ruby) -> Result<(), Error> {
-  let module = ruby.get_inner(&MODULE);
-  let _ = ruby.get_inner(&EVENT_CLASS);
-
-  module.define_module_function("_watch", magnus::function!(watch, 5))?;
-
-  Ok(())
-}
+pub use watcher::Watcher;

data/ext/cruise/src/watcher.rs

@@ -0,0 +1,196 @@
+//! The platform-agnostic file watcher.
+//!
+//! Knows nothing about Ruby or the C ABI. It watches paths, applies the
+//! configured kind/glob filters on the debouncer's background thread, and
+//! pushes matching `(path, kind)` pairs onto a shared queue. A self-pipe is
+//! written to on every batch so a consumer can wait on a file descriptor
+//! (`IO#wait_readable`) instead of blocking a thread — which is what makes the
+//! watcher cooperate with Ruby's fiber scheduler.
+
+use std::any::Any;
+use std::collections::VecDeque;
+use std::os::fd::RawFd;
+use std::os::raw::{c_int, c_void};
+use std::path::PathBuf;
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use globset::{Glob, GlobSet, GlobSetBuilder};
+use notify::event::{CreateKind, ModifyKind, RemoveKind};
+use notify::{EventKind, RecursiveMode};
+use notify_debouncer_full::{new_debouncer, DebounceEventResult};
+
+struct Shared {
+  pending: Mutex<VecDeque<(String, String)>>,
+  glob_set: Option<GlobSet>,
+  only_kinds: Vec<String>,
+  write_fd: RawFd,
+}
+
+impl Shared {
+  fn enqueue(&self, event: notify::Event) -> bool {
+    let kind = event_kind_to_string(&event.kind);
+
+    if !self.only_kinds.is_empty() && !self.only_kinds.iter().any(|allowed| allowed == kind) {
+      return false;
+    }
+
+    let mut queue = self.pending.lock().unwrap();
+    let mut added = false;
+
+    for path in event.paths {
+      if let Some(ref globs) = self.glob_set {
+        if !globs.is_match(&path) {
+          continue;
+        }
+      }
+
+      queue.push_back((path.to_string_lossy().into_owned(), kind.to_string()));
+      added = true;
+    }
+
+    added
+  }
+
+  fn wake(&self) {
+    let byte = [1u8];
+    let _ = unsafe { libc::write(self.write_fd, byte.as_ptr() as *const c_void, 1) };
+  }
+}
+
+impl Drop for Shared {
+  fn drop(&mut self) {
+    unsafe { libc::close(self.write_fd) };
+  }
+}
+
+/// A live filesystem watcher.
+///
+/// Holds the debouncer alive (dropping it stops watching) and the shared queue
+/// the consumer drains. The read end of the self-pipe is handed to the caller
+/// by [`Watcher::new`] and owned by them from that point on.
+pub struct Watcher {
+  _debouncer: Box<dyn Any>,
+  shared: Arc<Shared>,
+}
+
+impl Watcher {
+  pub fn new(paths: &[String], debounce: f64, globs: &[String], only_kinds: Vec<String>) -> Result<(Self, RawFd), String> {
+    let glob_set = build_glob_set(globs)?;
+    let (read_fd, write_fd) = make_pipe()?;
+
+    let shared = Arc::new(Shared {
+      pending: Mutex::new(VecDeque::new()),
+      glob_set,
+      only_kinds,
+      write_fd,
+    });
+
+    let callback_shared = Arc::clone(&shared);
+
+    let mut debouncer = match new_debouncer(Duration::from_secs_f64(debounce), None, move |result: DebounceEventResult| {
+      if let Ok(events) = result {
+        let mut added = false;
+
+        for debounced_event in events {
+          if callback_shared.enqueue(debounced_event.event) {
+            added = true;
+          }
+        }
+
+        if added {
+          callback_shared.wake();
+        }
+      }
+    }) {
+      Ok(debouncer) => debouncer,
+
+      Err(error) => {
+        unsafe { libc::close(read_fd) };
+        return Err(format!("Failed to create watcher: {error}"));
+      }
+    };
+
+    for path in paths {
+      let watch_path = PathBuf::from(path);
+
+      if !watch_path.exists() {
+        unsafe { libc::close(read_fd) };
+        return Err(format!("Path does not exist: {}", watch_path.display()));
+      }
+
+      if let Err(error) = debouncer.watch(&watch_path, RecursiveMode::Recursive) {
+        unsafe { libc::close(read_fd) };
+        return Err(format!("Failed to watch path: {error}"));
+      }
+    }
+
+    Ok((
+      Watcher {
+        _debouncer: Box::new(debouncer),
+        shared,
+      },
+      read_fd,
+    ))
+  }
+
+  pub fn poll(&self) -> Option<(String, String)> {
+    self.shared.pending.lock().unwrap().pop_front()
+  }
+}
+
+fn make_pipe() -> Result<(RawFd, RawFd), String> {
+  let mut fds = [0 as c_int; 2];
+
+  if unsafe { libc::pipe(fds.as_mut_ptr()) } != 0 {
+    return Err("Failed to create event pipe".to_string());
+  }
+
+  set_nonblock_cloexec(fds[0]);
+  set_nonblock_cloexec(fds[1]);
+
+  Ok((fds[0], fds[1]))
+}
+
+fn set_nonblock_cloexec(fd: c_int) {
+  unsafe {
+    let flags = libc::fcntl(fd, libc::F_GETFL);
+    libc::fcntl(fd, libc::F_SETFL, flags | libc::O_NONBLOCK);
+
+    let fd_flags = libc::fcntl(fd, libc::F_GETFD);
+    libc::fcntl(fd, libc::F_SETFD, fd_flags | libc::FD_CLOEXEC);
+  }
+}
+
+fn build_glob_set(patterns: &[String]) -> Result<Option<GlobSet>, String> {
+  if patterns.is_empty() {
+    return Ok(None);
+  }
+
+  let mut builder = GlobSetBuilder::new();
+
+  for pattern in patterns {
+    let glob = Glob::new(pattern).map_err(|error| format!("Invalid glob pattern '{}': {}", pattern, error))?;
+    builder.add(glob);
+  }
+
+  let set = builder.build().map_err(|error| format!("Failed to build glob set: {}", error))?;
+
+  Ok(Some(set))
+}
+
+fn event_kind_to_string(kind: &EventKind) -> &'static str {
+  match kind {
+    EventKind::Create(CreateKind::File) => "created",
+    EventKind::Create(CreateKind::Folder) => "created",
+    EventKind::Create(_) => "created",
+    EventKind::Modify(ModifyKind::Data(_)) => "modified",
+    EventKind::Modify(ModifyKind::Name(_)) => "renamed",
+    EventKind::Modify(_) => "modified",
+    EventKind::Remove(RemoveKind::File) => "removed",
+    EventKind::Remove(RemoveKind::Folder) => "removed",
+    EventKind::Remove(_) => "removed",
+    EventKind::Access(_) => "accessed",
+    EventKind::Any | EventKind::Other => "changed",
+  }
+}

data/lib/cruise/event.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Cruise
+  class Event
+    attr_reader :path #: String
+    attr_reader :kind #: String
+
+    #: (String path, String kind) -> void
+    def initialize(path, kind)
+      @path = path
+      @kind = kind
+    end
+
+    #: () -> String
+    def inspect
+      "#<Cruise::Event kind=#{kind.inspect} path=#{path.inspect}>"
+    end
+
+    #: () -> String
+    def to_s
+      "#{kind}: #{path}"
+    end
+  end
+end

data/lib/cruise/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cruise
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/cruise/watcher.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Cruise
+  class Watcher
+    #: (*paths paths, ?glob: globs?, ?debounce: debounce, ?only: kinds?) -> void
+    def initialize(*paths, glob: nil, debounce: DEFAULT_DEBOUNCE, only: nil)
+      paths = paths.flatten.grep(String)
+
+      raise ArgumentError, "Cruise::Watcher requires at least one path" if paths.empty?
+
+      glob_patterns = glob ? Array(glob) : [] #: Array[String]
+      only_kinds = only ? Array(only).map(&:to_s) : [] #: Array[String]
+
+      initialize_native(paths, debounce.to_f, glob_patterns, only_kinds)
+    end
+
+    #: () -> IO
+    def io
+      raise NotImplementedError, "Cruise::Watcher#io is provided by the native extension"
+    end
+
+    #: () -> Event?
+    def poll
+      raise NotImplementedError, "Cruise::Watcher#poll is provided by the native extension"
+    end
+
+    #: () -> void
+    def close
+      raise NotImplementedError, "Cruise::Watcher#close is provided by the native extension"
+    end
+
+    private
+
+    #: (Array[String] paths, Float debounce, Array[String] globs, Array[String] only_kinds) -> void
+    def initialize_native(_paths, _debounce, _globs, _only_kinds)
+      raise NotImplementedError, "Cruise::Watcher#initialize_native is provided by the native extension"
+    end
+  end
+end

data/lib/cruise.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require "io/wait"
+
 require_relative "cruise/version"
+require_relative "cruise/event"
+require_relative "cruise/watcher"
 
 begin
-  ruby_version = RUBY_VERSION.split(".")[0..1].join(".")
+  ruby_version = RUBY_VERSION.split(".").take(2).join(".")
 
   begin
     require "cruise/#{ruby_version}/cruise"
@@ -15,20 +19,49 @@ rescue LoadError => e
 end
 
 module Cruise
-  DEFAULT_DEBOUNCE = 0.1
+  DEFAULT_DEBOUNCE = 0.1 #: Float
 
   class << self
-    def watch(*args, glob: nil, debounce: DEFAULT_DEBOUNCE, only: nil, callback: nil, &block)
+    # Watch one or more paths and yield a Cruise::Event for each change.
+    #
+    # Blocks until interrupted. Waiting happens on the watcher's pipe via
+    # IO#wait_readable, so this releases the GVL for other threads and, when a
+    # Fiber scheduler is set (e.g. inside Async), yields to other fibers instead
+    # of blocking the reactor.
+    #: (*paths paths, ?glob: globs?, ?debounce: debounce, ?only: kinds?, ?callback: callback?) ?{ (Event) -> void } -> void
+    def watch(*paths, glob: nil, debounce: DEFAULT_DEBOUNCE, only: nil, callback: nil, &block)
       callback = block || callback
-      paths = args.flatten.grep(String)
 
-      raise ArgumentError, "Cruise.watch requires at least one path" if paths.empty?
       raise ArgumentError, "Cruise.watch requires a block or callback" unless callback
 
-      glob_patterns = glob ? Array(glob) : []
-      only_kinds = only ? Array(only).map(&:to_s) : []
+      watcher = Watcher.new(*paths, glob: glob, debounce: debounce, only: only)
+      io = watcher.io
+
+      begin
+        loop do
+          io.wait_readable
+          closed = drain_wakeups(io)
+
+          while (event = watcher.poll)
+            callback.call(event)
+          end
+
+          break if closed
+        end
+      ensure
+        watcher.close
+      end
+    end
+
+    private
 
-      _watch(paths, callback, debounce.to_f, glob_patterns, only_kinds)
+    #: (IO io) -> bool
+    def drain_wakeups(io)
+      loop { io.read_nonblock(4096) }
+    rescue IO::WaitReadable
+      false
+    rescue IOError
+      true
     end
   end
 end

data/sig/cruise/event.rbs

@@ -0,0 +1,18 @@
+# Generated from lib/cruise/event.rb with RBS::Inline
+
+module Cruise
+  class Event
+    attr_reader path: String
+
+    attr_reader kind: String
+
+    # : (String path, String kind) -> void
+    def initialize: (String path, String kind) -> void
+
+    # : () -> String
+    def inspect: () -> String
+
+    # : () -> String
+    def to_s: () -> String
+  end
+end