chrono_machines 0.2.0 → 0.5.0

data/ext/chrono_machines_native/core/src/sleep.rs

@@ -0,0 +1,97 @@
+//! Sleep abstraction for no_std compatibility
+//!
+//! This module provides traits and implementations for sleeping/delaying
+//! in various environments (std, async, embedded).
+
+/// Trait for sleep/delay implementations
+///
+/// This trait abstracts sleep operations to support different runtime environments:
+/// - Standard library blocking sleep
+/// - Tokio/async-std async sleep
+/// - Embassy timer for embedded
+/// - Custom implementations
+pub trait Sleeper {
+    /// Sleep for the specified number of milliseconds
+    fn sleep_ms(&self, ms: u64);
+}
+
+/// Standard library sleeper using `std::thread::sleep`
+///
+/// Only available when the `std` feature is enabled.
+///
+/// # Example
+///
+/// ```rust
+/// use chrono_machines::sleep::StdSleeper;
+/// use chrono_machines::sleep::Sleeper;
+///
+/// let sleeper = StdSleeper;
+/// sleeper.sleep_ms(100); // Sleep for 100ms
+/// ```
+#[cfg(feature = "std")]
+#[derive(Debug, Clone, Copy)]
+pub struct StdSleeper;
+
+#[cfg(feature = "std")]
+impl Sleeper for StdSleeper {
+    fn sleep_ms(&self, ms: u64) {
+        std::thread::sleep(std::time::Duration::from_millis(ms));
+    }
+}
+
+/// Function pointer sleeper for custom sleep implementations
+///
+/// Wraps a function pointer that takes milliseconds and performs sleep.
+/// Useful for async runtimes or testing.
+///
+/// # Example
+///
+/// ```rust
+/// use chrono_machines::sleep::{FnSleeper, Sleeper};
+///
+/// // Custom sleep function
+/// fn my_sleep(ms: u64) {
+///     // Custom implementation
+///     std::thread::sleep(std::time::Duration::from_millis(ms));
+/// }
+///
+/// let sleeper = FnSleeper(my_sleep);
+/// sleeper.sleep_ms(100);
+/// ```
+#[derive(Clone, Copy)]
+pub struct FnSleeper(pub fn(u64));
+
+impl Sleeper for FnSleeper {
+    fn sleep_ms(&self, ms: u64) {
+        (self.0)(ms);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[cfg(feature = "std")]
+    #[test]
+    fn test_std_sleeper() {
+        let sleeper = StdSleeper;
+        let start = std::time::Instant::now();
+        sleeper.sleep_ms(10);
+        let elapsed = start.elapsed();
+
+        // Allow some margin for timing precision
+        assert!(elapsed.as_millis() >= 9 && elapsed.as_millis() <= 20);
+    }
+
+    #[test]
+    fn test_fn_sleeper() {
+        fn test_sleep(ms: u64) {
+            // In a real test, we'd need interior mutability
+            // For this test, we just verify it compiles and runs
+            assert!(ms > 0);
+        }
+
+        let sleeper = FnSleeper(test_sleep);
+        sleeper.sleep_ms(100);
+    }
+}

data/ext/chrono_machines_native/extconf.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ffi/extconf'

data/ext/chrono_machines_native/ffi/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "chrono_machines_native"
+version = "0.3.0"
+edition = "2024"
+authors = ["Abdelkader Boudih <terminale@gmail.com>"]
+license = "MIT"
+description = "Ruby FFI binding for chrono_machines"
+repository = "https://github.com/seuros/chrono_machines"
+publish = false
+
+[lib]
+name = "chrono_machines_native"
+crate-type = ["cdylib"]
+
+[dependencies]
+chrono-machines = { workspace = true, features = ["std"] }
+magnus = "0.8.2"
+rand = { workspace = true }
+rb-sys = { version = "0.9.117", default-features = false, features = ["stable-api-compiled-fallback"] }
+
+[features]
+default = ["std"]
+std = ["chrono-machines/std"]

data/ext/chrono_machines_native/ffi/extconf.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+def create_noop_makefile(message)
+  warn message
+  warn 'ChronoMachines will fall back to pure Ruby backend.'
+  File.write('Makefile', <<~MAKE)
+    all:
+    	@echo '#{message}'
+    install:
+    	@echo '#{message}'
+  MAKE
+  exit 0
+end
+
+# Skip native extension compilation outside CRuby
+unless RUBY_ENGINE == 'ruby'
+  create_noop_makefile("Skipping native extension on #{RUBY_ENGINE}")
+end
+
+# Check if Cargo is available
+def cargo_available?
+  system('cargo --version > /dev/null 2>&1')
+end
+
+unless cargo_available?
+  create_noop_makefile('Skipping native extension (Cargo not found)')
+end
+
+# Use rb_sys to compile the Rust extension
+require 'mkmf'
+
+# Wrap entire compilation process in error handling to ensure gem install never fails
+begin
+  require 'rb_sys/mkmf'
+
+  require 'pathname'
+
+  create_rust_makefile('chrono_machines_native/chrono_machines_native') do |r|
+    ffi_dir = Pathname(__dir__)
+    r.ext_dir = begin
+      ffi_dir.relative_path_from(Pathname(Dir.pwd)).to_s
+    rescue ArgumentError
+      ffi_dir.expand_path.to_s
+    end
+    # Profile configuration
+    r.profile = ENV.fetch('RB_SYS_CARGO_PROFILE', :release).to_sym
+  end
+
+  makefile_path = File.join(Dir.pwd, 'Makefile')
+  if File.exist?(makefile_path)
+    manifest_path = File.expand_path(__dir__)
+    contents = File.read(makefile_path)
+    contents.gsub!(/^RB_SYS_CARGO_MANIFEST_DIR \?=.*$/, "RB_SYS_CARGO_MANIFEST_DIR ?= #{manifest_path}")
+    File.write(makefile_path, contents)
+  end
+rescue LoadError => e
+  # rb_sys not available
+  create_noop_makefile("Skipping native extension (rb_sys gem not available: #{e.message})")
+rescue StandardError => e
+  # Any other compilation setup failure (Rust compilation errors, Makefile generation, etc.)
+  create_noop_makefile("Skipping native extension (compilation setup failed: #{e.message})")
+end

data/ext/chrono_machines_native/ffi/src/lib.rs

@@ -0,0 +1,192 @@
+//! Ruby FFI binding for chrono_machines
+//!
+//! This crate provides a Magnus-based Ruby binding for the chrono_machines library.
+//! It exposes a simple helper function for calculating delays with exponential backoff.
+
+#![warn(rust_2024_compatibility)]
+#![warn(clippy::all)]
+
+use chrono_machines::fibonacci;
+use magnus::{function, Error, Ruby};
+use rand::rngs::StdRng;
+use rand::RngExt;
+use std::cell::RefCell;
+
+// Thread-local RNG for performance (avoids reseeding from entropy on every call)
+thread_local! {
+    static RNG: RefCell<StdRng> = RefCell::new(rand::make_rng());
+}
+
+/// Calculate delay using exponential backoff with configurable jitter
+///
+/// # Arguments
+/// * `attempt` - The current attempt number (1-indexed)
+/// * `base_delay` - Base delay in seconds
+/// * `multiplier` - Exponential multiplier
+/// * `max_delay` - Maximum delay cap in seconds
+/// * `jitter_factor` - Jitter multiplier (0.0 = no jitter, 1.0 = full jitter)
+///
+/// # Returns
+/// Calculated delay in seconds with jitter applied
+fn calculate_delay_exponential(
+    attempt: i64,
+    base_delay: f64,
+    multiplier: f64,
+    max_delay: f64,
+    jitter_factor: f64,
+) -> f64 {
+    let jitter_factor = normalize_jitter(jitter_factor);
+    let attempt_u8 = attempt.clamp(1, 255) as u8;
+    let exponent = attempt_u8.saturating_sub(1) as i32;
+
+    let base_exponential = base_delay * multiplier.powi(exponent);
+    let capped = base_exponential.min(max_delay);
+
+    apply_jitter(capped, jitter_factor)
+}
+
+/// Calculate delay using constant backoff with optional jitter
+///
+/// # Arguments
+/// * `_attempt` - The current attempt number (unused for constant backoff)
+/// * `delay` - Constant delay in seconds
+/// * `jitter_factor` - Jitter multiplier (0.0 = no jitter, 1.0 = full jitter)
+///
+/// # Returns
+/// Constant delay with jitter applied
+fn calculate_delay_constant(_attempt: i64, delay: f64, jitter_factor: f64) -> f64 {
+    let jitter_factor = normalize_jitter(jitter_factor);
+    apply_jitter(delay, jitter_factor)
+}
+
+/// Calculate delay using Fibonacci backoff with optional jitter
+///
+/// # Arguments
+/// * `attempt` - The current attempt number (1-indexed)
+/// * `base_delay` - Base delay in seconds (multiplied by Fibonacci number)
+/// * `max_delay` - Maximum delay cap in seconds
+/// * `jitter_factor` - Jitter multiplier (0.0 = no jitter, 1.0 = full jitter)
+///
+/// # Returns
+/// Fibonacci-based delay with jitter applied
+fn calculate_delay_fibonacci(
+    attempt: i64,
+    base_delay: f64,
+    max_delay: f64,
+    jitter_factor: f64,
+) -> f64 {
+    let jitter_factor = normalize_jitter(jitter_factor);
+    let attempt_u8 = attempt.clamp(1, 255) as u8;
+
+    let fib = fibonacci(attempt_u8);
+    let base = (base_delay * fib as f64).min(max_delay);
+
+    apply_jitter(base, jitter_factor)
+}
+
+/// Normalize jitter factor to [0.0, 1.0] range
+fn normalize_jitter(jitter_factor: f64) -> f64 {
+    if jitter_factor.is_nan() {
+        1.0
+    } else {
+        jitter_factor.clamp(0.0, 1.0)
+    }
+}
+
+/// Apply jitter to a base delay value
+fn apply_jitter(base: f64, jitter_factor: f64) -> f64 {
+    RNG.with(|rng| {
+        let mut rng = rng.borrow_mut();
+        let random_scalar: f64 = rng.random_range(0.0..=1.0);
+        let jitter_blend = 1.0 - jitter_factor + random_scalar * jitter_factor;
+        base * jitter_blend
+    })
+}
+
+/// Initialize the Ruby extension
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    // Create ChronoMachinesNative module
+    let module = ruby.define_module("ChronoMachinesNative")?;
+
+    // Expose backoff strategy functions
+    module.define_module_function(
+        "exponential_delay",
+        function!(calculate_delay_exponential, 5),
+    )?;
+    module.define_module_function("constant_delay", function!(calculate_delay_constant, 3))?;
+    module.define_module_function("fibonacci_delay", function!(calculate_delay_fibonacci, 4))?;
+
+    // Backward compatibility: alias old name to exponential
+    module.define_module_function("calculate_delay", function!(calculate_delay_exponential, 5))?;
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use rand::SeedableRng;
+
+    #[test]
+    fn test_exponential_delay() {
+        RNG.with(|rng| {
+            *rng.borrow_mut() = StdRng::seed_from_u64(1337);
+        });
+
+        let delay = calculate_delay_exponential(1, 0.0004, 1.0, 0.001, 0.5);
+
+        assert!(
+            delay >= 0.0002 && delay <= 0.0004,
+            "expected delay in [0.0002, 0.0004], got {delay}"
+        );
+    }
+
+    #[test]
+    fn test_constant_delay() {
+        RNG.with(|rng| {
+            *rng.borrow_mut() = StdRng::seed_from_u64(42);
+        });
+
+        // Constant delay with 10% jitter should be 90-100% of base
+        let delay = calculate_delay_constant(5, 1.0, 0.1);
+        assert!(delay >= 0.9 && delay <= 1.0, "got {delay}");
+
+        // No jitter should return exact value
+        let delay = calculate_delay_constant(3, 0.5, 0.0);
+        assert_eq!(delay, 0.5);
+    }
+
+    #[test]
+    fn test_fibonacci_delay() {
+        RNG.with(|rng| {
+            *rng.borrow_mut() = StdRng::seed_from_u64(123);
+        });
+
+        // Fibonacci sequence: 1, 1, 2, 3, 5, 8, 13...
+        // Attempt 1: base_delay * 1 = 0.1
+        let delay1 = calculate_delay_fibonacci(1, 0.1, 10.0, 0.0);
+        assert_eq!(delay1, 0.1);
+
+        // Attempt 5: base_delay * 5 = 0.5
+        let delay5 = calculate_delay_fibonacci(5, 0.1, 10.0, 0.0);
+        assert_eq!(delay5, 0.5);
+
+        // Attempt 8: base_delay * 21 = 2.1
+        let delay8 = calculate_delay_fibonacci(8, 0.1, 10.0, 0.0);
+        assert_eq!(delay8, 2.1);
+    }
+
+    #[test]
+    fn test_fibonacci_sequence() {
+        assert_eq!(fibonacci(0), 0);
+        assert_eq!(fibonacci(1), 1);
+        assert_eq!(fibonacci(2), 1);
+        assert_eq!(fibonacci(3), 2);
+        assert_eq!(fibonacci(4), 3);
+        assert_eq!(fibonacci(5), 5);
+        assert_eq!(fibonacci(6), 8);
+        assert_eq!(fibonacci(7), 13);
+        assert_eq!(fibonacci(8), 21);
+    }
+}