# Desync
```toml
[dependencies]
desync = "0.8"
```
Desync provides a new synchronisation type, `Desync<T>`, which works by ordering operations on
its enclosed data type instead of the traditional method of using mutexes to protect critical
sections. This allows concurrency to be built around two basic operations:
* `desync_thing.sync(|thing| /* ... */)` for synchronous access to the data
* `desync_thing.desync(|thing| /* ... */)` for asynchronous access to the data - running the supplied task in the background.
If only the `sync()` operation is used, this is roughly equivalent to a standard `Mutex`, except
with much stronger guarantees about which thread gets the data first. The other operation,
`desync()` effectively replaces the need to spawn threads and move data around in order to
add concurrency to a program.
Desync also provides equivalent methods for async code: `future_sync()` will perform an operation
in the current async context and `future_desync()` will schedule an operation in the background.
These can be freely mixed with the `sync()` and `desync()` operations so it becomes fairly easy to
mix code using traditional threading and code using async futures. As Desync uses order-of-operations
to guarantee exclusive access to the data, these operations can borrow the contained data across any
`await`s that might be needed, unlike locks created using the `Mutex` type, which can't be sent
between threads.
Desync provides fairly strong ordering guarantees: in particular, when any of the methods return,
the ordering of the operation is guaranteed relative to any following operation. This property makes
desync code quite easy to follow and less prone to race conditions than traditional threading. The
ability to easily schedule updates asynchronously provides a way around common scenarios where the
need to lock multiple mutexes can create deadlocks.
# Quick start
Desync provides a single type, `Desync<T>` that can be used to replace both threads and mutexes.
This type schedules operations for a contained data structure so that they are always performed
in order and optionally in the background.
Such a `Desync` object can be created like so:
```Rust
use desync::Desync;
let number = Desync::new(0);
```
It supports two main operations. `desync` will schedule a new job for the object that will run
in a background thread. It's useful for deferring long-running operations and moving updates
so they can run in parallel.
```Rust
let number = Desync::new(0);
thread::sleep(Duration::from_millis(100));
*val = 42;
});
// We can carry on what we're doing with the update now running in the background
```
The other operation is `sync`, which schedules a job to run synchronously on the data structure.
This is useful for retrieving values from a `Desync`.
```Rust
let new_number = number.sync(|val| *val); // = 42
```
`Desync` objects always run operations in the order that is provided, so all operations are
serialized from the point of view of the data that they contain. When combined with the ability
to perform operations asynchronously, this provides a useful way to immediately parallelize
long-running operations.
# Working with futures
Desync has support for the `futures` library. The simplest operation is `future_sync()`, which
creates a future that runs asynchronously on a `Desync` object but - unlike `desync()` can
return a result. It works like this:
```Rust