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.

License

This repository is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution Licensing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.