yew/platform.rs
1//! Yew's compatibility between JavaScript Runtime and Native Runtimes.
2//!
3//! This module is also published under the name [tokise] on crates.io.
4//!
5//! # Rationale
6//!
7//! When designing components and libraries that works on both WebAssembly targets backed by
8//! JavaScript Runtime and non-WebAssembly targets with Native Runtimes. Developers usually face
9//! challenges that requires applying multiple feature flags throughout their application:
10//!
11//! 1. Select I/O and timers that works with the target runtime.
12//! 2. Native Runtimes usually require `Send` futures and WebAssembly types are usually `!Send`.
13//!
14//! # Implementation
15//!
16//! To alleviate these issues, Yew implements a single-threaded runtime that executes `?Send`
17//! (`Send` or `!Send`) futures.
18//!
19//! On platforms with multi-threading support, Yew spawns multiple independent runtimes
20//! proportional to the CPU core number. When tasks are spawned with a runtime handle, it will
21//! randomly select a worker thread from the internal pool. All tasks spawned with `spawn_local`
22//! will run on the same thread as the thread the task was running. When the runtime runs in a
23//! WebAssembly target, all tasks will be scheduled on the main thread.
24//!
25//! This runtime is designed in favour of IO-bounded workload with similar runtime cost.
26//! When running I/O workloads, it would produce a slightly better performance as tasks are
27//! never moved to another thread. However, If a worker thread is busy,
28//! other threads will not be able to steal tasks scheduled on the busy thread.
29//! When you have a CPU-bounded task where CPU time is significantly
30//! more expensive, it should be spawned with a dedicated thread (or Web Worker) and communicates
31//! with the application using channels.
32//!
33//! Yew platform provides the following components:
34//!
35//! 1. A Task Scheduler that is capable of running non-Send tasks.
36//! 2. A Timer that is compatible with the scheduler backend.
37//! 3. Task Synchronisation Mechanisms.
38//!
39//! # Runtime Backend
40//!
41//! The Yew runtime is implemented with different runtimes depending on the target platform and can
42//! use all features (timers / IO / task synchronisation) from the selected native runtime:
43//!
44//! - `wasm-bindgen-futures` (WebAssembly targets)
45//! - `tokio` (non-WebAssembly targets)
46
47#[doc(inline)]
48pub use tokise::*;