1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280
//! app-world provides a framework agnostic approach to managing frontend application state.
//!
//! # The Data Model
//!
//! An `AppWorld` is a type that you define that holds your application state as well as other
//! resources that you've deemed useful to have around during your application's runtime.
//!
//! Here's an example of what an AppWorld for a basic e-commerce app frontend might look like:
//!
//! ```rust
//! # use std::collections::HashMap;
//! struct MyAppWorld {
//! state: MyAppState,
//! resources: MyAppResources
//! }
//!
//! struct MyAppState {
//! user: User,
//! products: HashMap<Uuid, Product>
//! }
//!
//! struct MyAppResources {
//! file_store: Box<dyn MyFileStoreTrait>,
//! api_client: ApiClient
//! }
//!
//! # trait MyFileStoreTrait {}
//! # type ApiClient = ();
//! # type Product = ();
//! # type User = ();
//! # type Uuid = ();
//! ```
//!
//! The `MyAppWorld` struct would be defined in your crate, but it wouldn't be used directly when
//! you were passing data around to your views.
//!
//! Instead, you wrap it in an `app_world::AppWorldWrapper<W>`
//!
//! ```rust
//! type MyAppWorldWrapper = app_world::AppWorldWrapper<MyAppWorld>;
//!
//! # type MyAppWorld = ();
//! ```
//!
//! # AppWorldWrapper<W: AppWorld>
//!
//! The `AppWorldWrapper` prevents direct mutable access to your application state, so you cannot
//! mutate fields wherever you please.
//!
//! Instead, the [`AppWorld`] trait defines a [`AppWorld.msg()`] method that can be used to update
//! your application state.
//!
//! You can pass your `AppWorldWrapper<W>` to different threads by calling
//! [`AppWorldWrapper.clone()`]. Under the hood an [`Arc`] is used to share your data across
//! threads.
//!
//! # Example Usage
//!
//! TODO
//!
//! # When to Use app-world
//!
//! app-world shines in applications that do not have extreme real time rendering requirements,
//! such as almost all browser, desktop and mobile applications.
//! In games and real-time simulations, you're better off using something like an entity component
//! system to manage your application state.
//!
//! This is because app-world is designed such that your application state can only be written to
//! from one thread at a time. This is totally fine for almost all browser, desktop and mobile
//! applications, but could be an issue for games and simulations.
//!
//! If you're writing a game or simulation you're likely better off reaching for an
//! entity-component-system library. Otherwise, you should be in good hands here.
//! which could be an issue for a high-performing game or simulation.
#![deny(missing_docs)]
use std::cell::RefCell;
use std::ops::Deref;
use std::sync::{Arc, RwLock, RwLockReadGuard};
use std::thread::LocalKey;
/// Holds application state and resources.
/// See the [crate level documentation](crate) for more details.
///
/// # Cloning
///
/// Cloning an `AppWorldWrapper` is a very cheap operation.
///
/// All clones hold pointers to the same inner state.
pub struct AppWorldWrapper<W: AppWorld> {
world: Arc<RwLock<W>>,
}
/// Defines how messages that indicate that something has happened get sent to the World.
pub trait AppWorld: Sized {
/// Indicates that something has happened.
///
/// ```
/// # use std::time::SystemTime;
/// #[allow(unused)]
/// enum MyMessageType {
/// IncreaseClickCounter,
/// SetLastPausedAt(SystemTime)
/// }
/// ```
type Message;
/// Send a message to the state object.
/// This will usually lead to a state update
fn msg(&mut self, message: Self::Message);
}
impl<W: AppWorld + 'static> AppWorldWrapper<W> {
/// Create a new AppWorldWrapper.
pub fn new(world: W) -> Self {
let world = Arc::new(RwLock::new(world));
Self { world }
}
/// Acquire write access to the AppWorld then send a message.
pub fn msg(&self, msg: W::Message) {
self.world.write().unwrap().msg(msg)
}
}
impl<W: AppWorld + 'static> AppWorldWrapper<W> {
thread_local!(
static HAS_READ: RefCell<bool> = RefCell::new(false);
);
/// Acquire read access to AppWorld.
///
/// # Panics
/// Panics if the current thread is already holding a read guard.
///
/// This panic prevents the following scenario from deadlocking:
///
/// 1. Thread A acquires a read guard
/// 2. Thread B calls `AppWorld::msg`, which attempts to acquire a write lock
/// 3. Thread A attempts to acquire a second read guard while the first is still active
pub fn read(&self) -> WorldReadGuard<'_, W> {
Self::HAS_READ.with(|has_read| {
let mut has_read = has_read.borrow_mut();
if *has_read {
panic!("Thread already holds read guard")
}
*has_read = true
});
WorldReadGuard {
guard: self.world.read().unwrap(),
read_tracker: &Self::HAS_READ,
}
}
/// Acquire write access to AppWorld.
///
/// Under normal circumstances you should only ever write to the world through the `.msg()`
/// method.
///
/// This .write() method is useful when writing tests where you want to quickly set up some
/// initial state.
#[cfg(feature = "test-utils")]
pub fn write(&self) -> std::sync::RwLockWriteGuard<'_, W> {
self.world.write().unwrap()
}
}
impl<W: AppWorld> Clone for AppWorldWrapper<W> {
fn clone(&self) -> Self {
AppWorldWrapper {
world: self.world.clone(),
}
}
}
/// Holds a read guard on a World.
pub struct WorldReadGuard<'a, W> {
guard: RwLockReadGuard<'a, W>,
read_tracker: &'static LocalKey<RefCell<bool>>,
}
impl<'a, W> Deref for WorldReadGuard<'a, W> {
type Target = RwLockReadGuard<'a, W>;
fn deref(&self) -> &Self::Target {
&self.guard
}
}
impl<'a, W> Drop for WorldReadGuard<'a, W> {
fn drop(&mut self) {
self.read_tracker.with(|has_reads| {
*has_reads.borrow_mut() = false;
})
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::thread;
use std::time::Duration;
/// Verify that we prevent deadlocks when a thread tries to acquire a read guard on the world
/// twice.
///
/// ---
///
/// Given Thread A and B, a deadlock can occur if:
///
/// 1. Thread A acquires read guard
/// 2. Thread B begins waiting for a write guard
/// 3. Thread A begins waiting for a second read guard
///
/// On some platforms the guard acquisition order would be Thread A, Thread A, Thread B.
/// That is to say that attempts to acquire write guards do not block attempts to acquire read
/// guards.
///
/// On other platforms, attempts to write may take precedence over attempts to read.
///
/// On those platforms, Thread A will deadlock on the second read, and Thread B will deadlock
/// on the write.
///
/// On macOS Ventura the sequence described above will cause a deadlock.
///
/// This test uses two threads and `std::time::sleep` to simulate the sequence above and
/// confirm that we panic if a thread tries to hold two active read guards at once.
#[test]
#[should_panic = "Second read attempt panicked"]
fn deadlock_prevention_same_thread_double_read_another_thread_write() {
let world = AppWorldWrapper::new(TestWorld { was_mutated: false });
let world_clone1 = world.clone();
let world_clone2 = world.clone();
let handle = thread::spawn(move || {
let guard_1 = world.read();
assert_eq!(guard_1.was_mutated, false);
let handle = thread::spawn(move || {
world_clone1.msg(());
});
thread::sleep(Duration::from_millis(50));
let guard_3 = world.read();
assert_eq!(guard_3.was_mutated, true);
handle.join().unwrap();
});
let join = handle.join();
assert_eq!(world_clone2.read().was_mutated, true);
join.expect("Second read attempt panicked");
}
/// Verify that the same thread can acquire a second read guard after the first has been
/// dropped.
#[test]
fn two_non_colliding_reads() {
let world = AppWorldWrapper::new(TestWorld::default());
{
let _guard = world.read();
}
let _guard = world.read();
}
#[derive(Default)]
struct TestWorld {
was_mutated: bool,
}
impl AppWorld for TestWorld {
type Message = ();
fn msg(&mut self, _message: Self::Message) {
self.was_mutated = true;
}
}
}