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 $traits with Send marker trait added when “sync” feature is enabled.

dyn_maybe_send_sync

Expands to dyn $traits with Sync marker trait added when “sync” feature is enabled.

dyn_maybe_sync

Expands to dyn $traits with Sync marker trait added when “sync” feature is enabled.

Structs

Mutex

Mutex implementation to use in conjunction with MaybeSync bound.

Traits

MaybeSend

Marker trait that can represent nothing if feature “sync” is not enabled. Or be reexport of std::marker::Send if “sync” feature is enabled.

MaybeSync

Marker trait that can represent nothing if feature “sync” is not enabled. Or be reexport of std::marker::Sync if “sync” feature is enabled.

Type Aliases

AtomicBool

A boolean type which can be safely shared between threads when “sync” feature is enabled.
A boolean type with non-threadsafe interior mutability when “sync” feature is not enabled.

AtomicI8

A integer type which can be safely shared between threads when “sync” feature is enabled.
A integer type with non-threadsafe interior mutability when “sync” feature is not enabled.

AtomicI16

A integer type which can be safely shared between threads when “sync” feature is enabled.
A integer type with non-threadsafe interior mutability when “sync” feature is not enabled.

AtomicI32

A integer type which can be safely shared between threads when “sync” feature is enabled.
A integer type with non-threadsafe interior mutability when “sync” feature is not enabled.

AtomicIsize

A integer type which can be safely shared between threads when “sync” feature is enabled.
A integer type with non-threadsafe interior mutability when “sync” feature is not enabled.

AtomicPtr

A raw pointer type which can be safely shared between threads when “sync” feature is enabled.
A raw pointer type with non-threadsafe interior mutability when “sync” feature is not enabled.

AtomicU8

A integer type which can be safely shared between threads when “sync” feature is enabled.
A integer type with non-threadsafe interior mutability when “sync” feature is not enabled.

AtomicU16

A integer type which can be safely shared between threads when “sync” feature is enabled.
A integer type with non-threadsafe interior mutability when “sync” feature is not enabled.

AtomicU32

A integer type which can be safely shared between threads when “sync” feature is enabled.
A integer type with non-threadsafe interior mutability when “sync” feature is not enabled.

AtomicUsize

A integer type which can be safely shared between threads when “sync” feature is enabled.
A integer type with non-threadsafe interior mutability when “sync” feature is not enabled.

BoxFuturealloc

An owned dynamically typed Future for use at return position in cases when type is opaque and existential type cannot be used, or when multiple types can be returned.

Rcalloc

A pointer type which can be safely shared between threads when “sync” feature is enabled.
A pointer type which can be shared, but only within single thread where it was created when “sync” feature is not enabled.