cruise 0.1.0-x86_64-linux-gnu → 0.2.0-x86_64-linux-gnu

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

@@ -0,0 +1,11 @@
+//! 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.
+
+mod ffi;
+mod watcher;
+
+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,20 @@
+# frozen_string_literal: true
+
+module Cruise
+  class Event
+    attr_reader :path, :kind
+
+    def initialize(path, kind)
+      @path = path
+      @kind = kind
+    end
+
+    def inspect
+      "#<Cruise::Event kind=#{kind.inspect} path=#{path.inspect}>"
+    end
+
+    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.0"
 end

data/lib/cruise/watcher.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Cruise
+  class Watcher
+    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) : []
+      only_kinds = only ? Array(only).map(&:to_s) : []
+
+      initialize_native(paths, debounce.to_f, glob_patterns, only_kinds)
+    end
+
+    def io
+      raise NotImplementedError, "Cruise::Watcher#io is provided by the native extension"
+    end
+
+    def poll
+      raise NotImplementedError, "Cruise::Watcher#poll is provided by the native extension"
+    end
+
+    def close
+      raise NotImplementedError, "Cruise::Watcher#close is provided by the native extension"
+    end
+
+    private
+
+    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,6 +1,10 @@
 # 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(".")
@@ -18,17 +22,44 @@ module Cruise
   DEFAULT_DEBOUNCE = 0.1
 
   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.
+    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)
+    def drain_wakeups(io)
+      loop { io.read_nonblock(4096) }
+    rescue IO::WaitReadable
+      false
+    rescue IOError
+      true
     end
   end
 end

metadata

@@ -1,32 +1,45 @@
 --- !ruby/object:Gem::Specification
 name: cruise
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: x86_64-linux-gnu
 authors:
 - Marco Roth
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-03-24 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies: []
-description: Cruise is a Rust-powered file system watcher with native OS integration.
-  Uses FSEvents on macOS and inotify on Linux.
+description: Cruise is a file system watcher built on native OS events. Uses FSEvents
+  on macOS and inotify on Linux.
 email:
 - marco.roth@intergga.ch
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- Cargo.lock
+- Cargo.toml
 - LICENSE.txt
+- README.md
 - Rakefile
 - cruise.gemspec
+- ext/cruise/Cargo.toml
+- ext/cruise/build.rs
+- ext/cruise/cbindgen.toml
+- ext/cruise/cruise.c
+- ext/cruise/extconf.rb
+- ext/cruise/src/ffi.rs
+- ext/cruise/src/lib.rs
+- ext/cruise/src/watcher.rs
 - lib/cruise.rb
 - lib/cruise/3.2/cruise.so
 - lib/cruise/3.3/cruise.so
 - lib/cruise/3.4/cruise.so
 - lib/cruise/4.0/cruise.so
+- lib/cruise/event.rb
 - lib/cruise/version.rb
+- lib/cruise/watcher.rb
 homepage: https://github.com/marcoroth/cruise
 licenses:
 - MIT
@@ -58,5 +71,5 @@ requirements: []
 rubygems_version: 3.5.23
 signing_key: 
 specification_version: 4
-summary: A fast, native file watcher for Ruby
+summary: A fast, OS-native file watcher for Ruby
 test_files: []