Add spin_sleep_util crate (#23)

* Add spin_sleep_util crate

* Deprecate LoopHelper

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
     steps:
     - run: rustup update stable
     - uses: actions/checkout@v4
-    - run: cargo test
+    - run: cargo test --workspace
 
   rustfmt:
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -1,4 +1,5 @@
 # Unreleased (v1.2.0)
+* Deprecate `LoopHelper`. Instead use _spin_sleep_util_ crate.
 * Windows: Use a high resolution waitable timer when available (>= Windows 10, version 1803).
 * Windows: Replace _winapi_ with _windows-sys_ dependency.
 * Windows: Remove _once_cell_ dependency.

Cargo.toml

@@ -1,17 +1,21 @@
 [package]
 name = "spin_sleep"
 version = "1.1.1"
-authors = ["Alex Butler <[email protected]>"]
 edition = "2021"
+authors = ["Alex Butler <[email protected]>"]
 description = "Accurate sleeping. Only use native sleep as far as it can be trusted, then spin."
 repository = "https://github.com/alexheretic/spin-sleep"
 keywords = ["sleep"]
 license = "Apache-2.0"
-readme="README.md"
+readme = "README.md"
 
 [target.'cfg(windows)'.dependencies]
 windows-sys = { version = "0.52", features = [
-    "Win32_Foundation", "Win32_Security", "Win32_System", "Win32_System_Threading", "Win32_Media"
+    "Win32_Foundation",
+    "Win32_Security",
+    "Win32_System",
+    "Win32_System_Threading",
+    "Win32_Media",
 ] }
 
 [dev-dependencies]
@@ -20,3 +24,6 @@ approx = "0.5"
 [features]
 # Controls certain tests that are not deterministic
 nondeterministic_tests = []
+
+[workspace]
+members = ["util"]

src/loop_helper.rs

@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 use super::*;
 use std::time::{Duration, Instant};
 
@@ -8,36 +10,8 @@ use std::time::{Duration, Instant};
 ///
 /// Can limit a loop rate to a desired target using
 /// [`LoopHelper::loop_sleep`](struct.LoopHelper.html#method.loop_sleep).
-///
-/// # Issues
-/// There are known limitations/flaws, see [#19](https://github.com/alexheretic/spin-sleep/issues/19).
-/// `LoopHelper` will probably be deprecated for removal in the future.
-///
-/// # Example
-///
-/// ```no_run
-/// use spin_sleep::LoopHelper;
-///
-/// let mut loop_helper = LoopHelper::builder()
-///     .report_interval_s(0.5) // report every half a second
-///     .build_with_target_rate(250.0); // limit to 250 FPS if possible
-///
-/// let mut current_fps = None;
-///
-/// loop {
-///     let delta = loop_helper.loop_start(); // or .loop_start_s() for f64 seconds
-///
-///     // compute_something(delta);
-///
-///     if let Some(fps) = loop_helper.report_rate() {
-///         current_fps = Some(fps.round());
-///     }
-///
-///     // render_fps(current_fps);
-///
-///     loop_helper.loop_sleep(); // sleeps to achieve a 250 FPS rate
-/// }
-/// ```
+#[doc(hidden)]
+#[deprecated = "Use spin_sleep_util crate"]
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct LoopHelper {
     target_delta: Duration,
@@ -51,6 +25,8 @@ pub struct LoopHelper {
 }
 
 /// Builds [`LoopHelper`](struct.LoopHelper.html).
+#[doc(hidden)]
+#[deprecated = "Use spin_sleep_util crate"]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct LoopHelperBuilder {
     report_interval: Option<Duration>,

util/CHANGELOG.md

@@ -0,0 +1,2 @@
+# v0.1.0
+* Add `Interval`, `RateReporter`.

util/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "spin_sleep_util"
+version = "0.1.0"
+edition = "2021"
+authors = ["Alex Butler <[email protected]>"]
+description = "Utils using spin_sleep"
+repository = "https://github.com/alexheretic/spin-sleep"
+keywords = ["sleep", "loop", "interval"]
+license = "Apache-2.0"
+readme = "README.md"
+
+[dependencies]
+spin_sleep = { path = "..", version = "1" }

util/LICENSE

@@ -0,0 +1 @@
+../LICENSE

util/README.md

@@ -0,0 +1,20 @@
+spin_sleep_util
+[![crates.io](https://img.shields.io/crates/v/spin_sleep_util.svg)](https://crates.io/crates/spin_sleep_util)
+[![Documentation](https://docs.rs/spin_sleep_util/badge.svg)](https://docs.rs/spin_sleep_util)
+===============
+Utils using spin_sleep.
+
+## Example: Frame limiter
+`Interval` may be used to limit a loop to a max fps by calling `Interval::tick` at the start or end of each loop.
+
+```rust
+// Create an interval to tick 144 times each second
+let mut interval = spin_sleep_util::interval(Duration::from_secs(1) / 144);
+loop {
+    compute_something(); // do loop work
+
+    // tick: sleep using a SpinSleeper until next tick.
+    // The default `Skip` missed ticke behaviour is appropriate for a frame limiter
+    interval.tick();
+}
+```