[−][src]Crate maybe_sync
This crates helps creating flexible libraries that may work in either multithreaded and singlethreaded environments.
Why it exists?
Creating library that works in either desktop/server or web-browser environment could be tough.
In desktop/server environments crates tend to be usable with multiple threads
and add Send and Sync trait bounds where needed.
In the same time web-sys - a de facto standard crate to use browser API -
provides programmer with !Send + !Sync types that cannot be used when Send
or Sync bounds are placed on the API calls.
For example asset loading crate goods uses generic executors to drive
loading process.
Some executors work with sendable futures only: tokio,
some requre sendable future to run them on multiple threads:
async-std, actix-rt,
Others work with any futures in single thread: wasm_bindgen_futures::spawn_local
In goods one of the basic data sources for web - FetchSource - uses
browser's Fetch API to retreive data from web and produces non-sendable future.
That's why goods::Spawn::spawn takes maybe_sync::BoxFuture that is
a sendable boxed future when "sync" feature is enabled,
allowing using multithreaded future executors.
And without "sync" feature maybe_sync::BoxFuture is
a non-sendable boxed future and only then FetchSource exists.
Similar story with ECS crates.
Most of them require that components are Send + Sync
so systems can access them from any thread.
This makes it impossible to have types from web-sys in components.
Some small application may desire to turn off "sync" feature in their dependencies as they are singlethreaded and would rather not pay for what they don't use.
MaybeSend and MaybeSync
Marker traits MaybeSend and MaybeSync can be used in place of
Send and Sync traits in where clauses and bounds.
When "sync" feature is enabled then MaybeSend is actually reexported Send
and MaybeSync is reexported Sync trait.
Thus allowing types with those bounds to be sent or shared across threads.
When "sync" feature is not enabled then MaybeSend and MaybeSync are empty
traits implemented for all types and when used as bounds permit types that
does not satisfy Send or Sync bounds.
This makes it impossible to forget enable "sync" feature and accidentally send
!Send value to another thread.
Function that uncodintionally send value to another thread
should not use MaybeSend bound, but an actual Send.
BoxFuture
Type alias for boxed future. Sendable if "sync" feature is enabled.
It is designed to be used as return type from trait functions
where trait implementations that produce non-sendable futures
exist only when "sync" feature is not enabled.
It can be used as function argument type when MaybeSend bound is placed.
Rc
Type alias to alloc::rc::Rc when "sync" feature is not enabled, or
alloc::sync::Arc when "sync" feature is enabled. Serves for optimization
purposes for crates that already use maybe-sync crate.
Mutex
Type alias to parking_lot::Mutex when "sync" feature is enabled, or
thin wrapper arond core::cell::RefCell otherwise. Serves for optimization
purposes for crates that already use maybe-sync crate.
Macros
| dyn_maybe_send | Expands to |
| dyn_maybe_send_sync | Expands to |
| dyn_maybe_sync | Expands to |
Structs
| Mutex | Mutex implementation to use in conjunction with |
Traits
| MaybeSend | Marker trait that can represent nothing if feature "sync" is not enabled.
Or be reexport of |
| MaybeSync | Marker trait that can represent nothing if feature "sync" is not enabled.
Or be reexport of |
Type Definitions
| AtomicBool | A boolean type which can be safely shared between threads
when "sync" feature is enabled. |
| AtomicI8 | A integer type which can be safely shared between threads
when "sync" feature is enabled. |
| AtomicI16 | A integer type which can be safely shared between threads
when "sync" feature is enabled. |
| AtomicI32 | A integer type which can be safely shared between threads
when "sync" feature is enabled. |
| AtomicIsize | A integer type which can be safely shared between threads
when "sync" feature is enabled. |
| AtomicPtr | A raw pointer type which can be safely shared between threads
when "sync" feature is enabled. |
| AtomicU8 | A integer type which can be safely shared between threads
when "sync" feature is enabled. |
| AtomicU16 | A integer type which can be safely shared between threads
when "sync" feature is enabled. |
| AtomicU32 | A integer type which can be safely shared between threads
when "sync" feature is enabled. |
| AtomicUsize | A integer type which can be safely shared between threads
when "sync" feature is enabled. |
| BoxFuture | feature="alloc"An owned dynamically typed |
| Rc | feature="alloc"A pointer type which can be safely shared between threads
when "sync" feature is enabled. |