Final Cleanup

This adds the remaining documentation that was missing. This also fixes
the Continuous Integration and does some other minor cleanup. Lastly it
also finalizes the auto splitter API.

.github/workflows/build.yml

@@ -290,12 +290,14 @@ jobs:
             target: i586-pc-windows-msvc
             os: windows-latest
             cross: skip
+            auto_splitting: skip
             install_target: true
 
           - label: Windows i686
             target: i686-pc-windows-msvc
             os: windows-latest
             cross: skip
+            auto_splitting: skip
             install_target: true
 
           - label: Windows x86_64
@@ -308,6 +310,7 @@ jobs:
             toolchain: stable-i686-pc-windows-gnu
             os: windows-latest
             cross: skip
+            auto_splitting: skip
             install_target: true
 
           - label: Windows x86_64 gnu
@@ -639,6 +642,7 @@ jobs:
         env:
           TARGET: ${{ matrix.target }}
           SKIP_CROSS: ${{ matrix.cross }}
+          SKIP_AUTO_SPLITTING: ${{ matrix.auto_splitting }}
 
       - name: Prepare Release
         if: startsWith(github.ref, 'refs/tags/') && matrix.release == ''

.github/workflows/test.sh

@@ -3,12 +3,15 @@ set -ex
 main() {
     local cargo=cross
 
-    # all features except those that don't easily work with cross such as font-loading
+    # all features except those that don't easily work with cross such as
+    # font-loading or auto-splitting.
     local all_features="--features std,more-image-formats,image-shrinking,rendering,software-rendering,wasm-web,networking"
 
     if [ "$SKIP_CROSS" = "skip" ]; then
         cargo=cargo
-        all_features="--all-features"
+        if [ "$SKIP_AUTO_SPLITTING" -ne "skip" ]; then
+            all_features="--all-features"
+        fi
     fi
 
     if [ "$TARGET" = "wasm32-wasi" ]; then

Cargo.toml

@@ -84,7 +84,7 @@ splits-io-api = { version = "0.2.0", optional = true }
 # Auto Splitting
 livesplit-auto-splitting = { path = "crates/livesplit-auto-splitting", version = "0.1.0", optional = true }
 crossbeam-channel = { version = "0.5.1", default-features = false, optional = true }
-log = { version = "0.4.14", optional = true }
+log = { version = "0.4.14", default-features = false, optional = true }
 
 [target.'cfg(all(target_arch = "wasm32", target_os = "unknown"))'.dependencies]
 # WebAssembly in the Web

crates/livesplit-auto-splitting/Cargo.toml

@@ -5,14 +5,15 @@ authors = ["Christopher Serr <[email protected]>"]
 edition = "2021"
 
 [dependencies]
-anyhow = "1.0.45"
-log = "0.4.14"
-proc-maps = "0.2.0"
-read-process-memory = "0.1.4"
-slotmap = "1.0.2"
-snafu = "0.6.10"
-sysinfo = "0.22.4"
-time = "0.3.3"
-wasmtime = { version = "0.32.0", default-features = false, features = [
+anyhow = { version = "1.0.45", default-features = false }
+log = { version = "0.4.14", default-features = false }
+proc-maps = { version = "0.2.0", default-features = false }
+read-process-memory = { version = "0.1.4", default-features = false }
+slotmap = { version = "1.0.2", default-features = false }
+snafu = { version = "0.6.10", default-features = false, features = ["std"] }
+sysinfo = { version = "0.22.4", default-features = false, features = ["multithread"] }
+time = { version = "0.3.3", default-features = false }
+wasmtime = { version = "0.33.0", default-features = false, features = [
   "cranelift",
+  "parallel-compilation",
 ] }

crates/livesplit-auto-splitting/README.md

@@ -0,0 +1,110 @@
+# <img src="https://raw.githubusercontent.com/LiveSplit/LiveSplit/master/LiveSplit/Resources/Icon.png" alt="LiveSplit" height="42" width="45" align="top"/> livesplit-auto-splitting
+
+livesplit-auto-splitting is a library that provides a runtime for running
+auto splitters that can control a speedrun timer. These auto splitters are
+provided as WebAssembly modules.
+
+## Requirements for the Auto Splitters
+
+The auto splitters must provide an `update` function with the following
+signature:
+
+```rust
+#[no_mangle]
+pub extern "C" fn update() {}
+```
+
+This function is called periodically by the runtime at the configured tick
+rate. The tick rate is 120 Hz by default, but can be changed by the auto
+splitter.
+
+In addition the WebAssembly module is expected to export a memory called
+`memory`.
+
+## API exposed to the Auto Splitters
+
+The following functions are provided to the auto splitters in the module
+`env`:
+
+```rust
+#[repr(transparent)]
+pub struct Address(pub u64);
+
+#[repr(transparent)]
+pub struct NonZeroAddress(pub NonZeroU64);
+
+#[repr(transparent)]
+pub struct ProcessId(NonZeroU64);
+
+#[repr(transparent)]
+pub struct TimerState(u32);
+
+impl TimerState {
+    /// The timer is not running.
+    pub const NOT_RUNNING: Self = Self(0);
+    /// The timer is running.
+    pub const RUNNING: Self = Self(1);
+    /// The timer started but got paused. This is separate from the game
+    /// time being paused. Game time may even always be paused.
+    pub const PAUSED: Self = Self(2);
+    /// The timer has ended, but didn't get reset yet.
+    pub const ENDED: Self = Self(3);
+}
+
+extern "C" {
+    /// Gets the state that the timer currently is in.
+    pub fn timer_get_state() -> TimerState;
+
+    /// Starts the timer.
+    pub fn timer_start();
+    /// Splits the current segment.
+    pub fn timer_split();
+    /// Resets the timer.
+    pub fn timer_reset();
+    /// Sets a custom key value pair. This may be arbitrary information that
+    /// the auto splitter wants to provide for visualization.
+    pub fn timer_set_variable(
+        key_ptr: *const u8,
+        key_len: usize,
+        value_ptr: *const u8,
+        value_len: usize,
+    );
+
+    /// Sets the game time.
+    pub fn timer_set_game_time(secs: i64, nanos: i32);
+    /// Pauses the game time. This does not pause the timer, only the
+    /// automatic flow of time for the game time.
+    pub fn timer_pause_game_time();
+    /// Resumes the game time. This does not resume the timer, only the
+    /// automatic flow of time for the game time.
+    pub fn timer_resume_game_time();
+
+    /// Attaches to a process based on its name.
+    pub fn process_attach(name_ptr: *const u8, name_len: usize) -> Option<ProcessId>;
+    /// Detaches from a process.
+    pub fn process_detach(process: ProcessId);
+    /// Checks whether is a process is still open. You should detach from a
+    /// process and stop using it if this returns `false`.
+    pub fn process_is_open(process: ProcessId) -> bool;
+    /// Reads memory from a process at the address given. This will write
+    /// the memory to the buffer given. Returns `false` if this fails.
+    pub fn process_read(
+        process: ProcessId,
+        address: Address,
+        buf_ptr: *mut u8,
+        buf_len: usize,
+    ) -> bool;
+    /// Gets the address of a module in a process.
+    pub fn process_get_module_address(
+        process: ProcessId,
+        name_ptr: *const u8,
+        name_len: usize,
+    ) -> Option<NonZeroAddress>;
+
+    /// Sets the tick rate of the runtime. This influences the amount of
+    /// times the `update` function is called per second.
+    pub fn runtime_set_tick_rate(ticks_per_second: f64);
+    /// Prints a log message for debugging purposes.
+    pub fn runtime_print_message(text_ptr: *const u8, text_len: usize);
+}
+```

crates/livesplit-auto-splitting/src/lib.rs

@@ -1,7 +1,126 @@
+//! livesplit-auto-splitting is a library that provides a runtime for running
+//! auto splitters that can control a speedrun timer. These auto splitters are
+//! provided as WebAssembly modules.
+//!
+//! # Requirements for the Auto Splitters
+//!
+//! The auto splitters must provide an `update` function with the following
+//! signature:
+//!
+//! ```rust
+//! #[no_mangle]
+//! pub extern "C" fn update() {}
+//! ```
+//!
+//! This function is called periodically by the runtime at the configured tick
+//! rate. The tick rate is 120 Hz by default, but can be changed by the auto
+//! splitter.
+//!
+//! In addition the WebAssembly module is expected to export a memory called
+//! `memory`.
+//!
+//! # API exposed to the Auto Splitters
+//!
+//! The following functions are provided to the auto splitters in the module
+//! `env`:
+//!
+//! ```rust
+//! #[repr(transparent)]
+//! pub struct Address(pub u64);
+//!
+//! #[repr(transparent)]
+//! pub struct NonZeroAddress(pub NonZeroU64);
+//!
+//! #[repr(transparent)]
+//! pub struct ProcessId(NonZeroU64);
+//!
+//! #[repr(transparent)]
+//! pub struct TimerState(u32);
+//!
+//! impl TimerState {
+//!     /// The timer is not running.
+//!     pub const NOT_RUNNING: Self = Self(0);
+//!     /// The timer is running.
+//!     pub const RUNNING: Self = Self(1);
+//!     /// The timer started but got paused. This is separate from the game
+//!     /// time being paused. Game time may even always be paused.
+//!     pub const PAUSED: Self = Self(2);
+//!     /// The timer has ended, but didn't get reset yet.
+//!     pub const ENDED: Self = Self(3);
+//! }
+//!
+//! extern "C" {
+//!     /// Gets the state that the timer currently is in.
+//!     pub fn timer_get_state() -> TimerState;
+//!
+//!     /// Starts the timer.
+//!     pub fn timer_start();
+//!     /// Splits the current segment.
+//!     pub fn timer_split();
+//!     /// Resets the timer.
+//!     pub fn timer_reset();
+//!     /// Sets a custom key value pair. This may be arbitrary information that
+//!     /// the auto splitter wants to provide for visualization.
+//!     pub fn timer_set_variable(
+//!         key_ptr: *const u8,
+//!         key_len: usize,
+//!         value_ptr: *const u8,
+//!         value_len: usize,
+//!     );
+//!
+//!     /// Sets the game time.
+//!     pub fn timer_set_game_time(secs: i64, nanos: i32);
+//!     /// Pauses the game time. This does not pause the timer, only the
+//!     /// automatic flow of time for the game time.
+//!     pub fn timer_pause_game_time();
+//!     /// Resumes the game time. This does not resume the timer, only the
+//!     /// automatic flow of time for the game time.
+//!     pub fn timer_resume_game_time();
+//!
+//!     /// Attaches to a process based on its name.
+//!     pub fn process_attach(name_ptr: *const u8, name_len: usize) -> Option<ProcessId>;
+//!     /// Detaches from a process.
+//!     pub fn process_detach(process: ProcessId);
+//!     /// Checks whether is a process is still open. You should detach from a
+//!     /// process and stop using it if this returns `false`.
+//!     pub fn process_is_open(process: ProcessId) -> bool;
+//!     /// Reads memory from a process at the address given. This will write
+//!     /// the memory to the buffer given. Returns `false` if this fails.
+//!     pub fn process_read(
+//!         process: ProcessId,
+//!         address: Address,
+//!         buf_ptr: *mut u8,
+//!         buf_len: usize,
+//!     ) -> bool;
+//!     /// Gets the address of a module in a process.
+//!     pub fn process_get_module_address(
+//!         process: ProcessId,
+//!         name_ptr: *const u8,
+//!         name_len: usize,
+//!     ) -> Option<NonZeroAddress>;
+//!
+//!     /// Sets the tick rate of the runtime. This influences the amount of
+//!     /// times the `update` function is called per second.
+//!     pub fn runtime_set_tick_rate(ticks_per_second: f64);
+//!     /// Prints a log message for debugging purposes.
+//!     pub fn runtime_print_message(text_ptr: *const u8, text_len: usize);
+//! }
+//! ```
+
+#![warn(
+    clippy::complexity,
+    clippy::correctness,
+    clippy::perf,
+    clippy::style,
+    clippy::missing_const_for_fn,
+    missing_docs,
+    rust_2018_idioms
+)]
+
 mod process;
 mod runtime;
 mod timer;
 
-pub use runtime::{Error, Result, Runtime};
+pub use runtime::{CreationError, RunError, Runtime};
 pub use timer::{Timer, TimerState};
 pub use wasmtime::InterruptHandle;