desync 0.2.0

A hassle-free data type for asynchronous programming
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

# Desync

```toml
[dependencies]
desync = "0.2"
```

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. `async` 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);
number.async(|val| {
    // Long update here
    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()`, which creates
a future that runs asynchronously on a `Desync` object but - unlike `async()` can return a result.
It works like this:

```Rust
let future_number = number.future(|val| *val);
assert!(executor::spawn(future_number).wait_future().unwrap() == 42);
```

There is also support for streams, via the `pipe_in()` and `pipe()` functions. These work on
`Arc<Desync<T>>` references and provide a way to process a stream asynchronously. These two
functions provide a powerful way to process input and also to connect `Desync` objects together
using message-passing for communication.

```Rust
let some_object = Arc::new(Desync::new(some_object));

pipe_in(Arc::clone(&number), some_stream, 
    |some_object, input| input.map(|input| some_object.process(input)));

let output_stream = pipe(Arc::clone(&number), some_stream, 
    |some_object, input| input.map(|input| some_object.process_with_output(input)));
```