async-broadcast 0.4.1

Async broadcast channels
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
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

# async-broadcast

[![Build](https://github.com/smol-rs/async-broadcast/workflows/Build%20and%20test/badge.svg)](
https://github.com/smol-rs/async-broadcast/actions)
[![License](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue.svg)](
https://github.com/smol-rs/async-broadcast)
[![Cargo](https://img.shields.io/crates/v/async-broadcast.svg)](
https://crates.io/crates/async-broadcast)
[![Documentation](https://docs.rs/async-broadcast/badge.svg)](
https://docs.rs/async-broadcast)

An async multi-producer multi-consumer broadcast channel, where each consumer gets a clone of every
message sent on the channel. For obvious reasons, the channel can only be used to broadcast types
that implement `Clone`.

A channel has the `Sender` and `Receiver` side. Both sides are cloneable and can be shared
among multiple threads.

When all `Sender`s or all `Receiver`s are dropped, the channel becomes closed. When a channel is
closed, no more messages can be sent, but remaining messages can still be received.

The channel can also be closed manually by calling `Sender::close()` or
`Receiver::close()`.

## Examples

```rust
use async_broadcast::{broadcast, TryRecvError};
use futures_lite::{future::block_on, stream::StreamExt};

block_on(async move {
    let (s1, mut r1) = broadcast(2);
    let s2 = s1.clone();
    let mut r2 = r1.clone();

    // Send 2 messages from two different senders.
    s1.broadcast(7).await.unwrap();
    s2.broadcast(8).await.unwrap();

    // Channel is now at capacity so sending more messages will result in an error.
    assert!(s2.try_broadcast(9).unwrap_err().is_full());
    assert!(s1.try_broadcast(10).unwrap_err().is_full());

    // We can use `recv` method of the `Stream` implementation to receive messages.
    assert_eq!(r1.next().await.unwrap(), 7);
    assert_eq!(r1.recv().await.unwrap(), 8);
    assert_eq!(r2.next().await.unwrap(), 7);
    assert_eq!(r2.recv().await.unwrap(), 8);

    // All receiver got all messages so channel is now empty.
    assert_eq!(r1.try_recv(), Err(TryRecvError::Empty));
    assert_eq!(r2.try_recv(), Err(TryRecvError::Empty));

    // Drop both senders, which closes the channel.
    drop(s1);
    drop(s2);

    assert_eq!(r1.try_recv(), Err(TryRecvError::Closed));
    assert_eq!(r2.try_recv(), Err(TryRecvError::Closed));
})
```

## Difference with `async-channel`

This crate is similar to [`async-channel`] in that they both provide an MPMC channel but the main
difference being that in `async-channel`, each message sent on the channel is only received by one
of the receivers. `async-broadcast` on the other hand, delivers each message to every receiver
(IOW broadcast) by cloning it for each receiver.

[`async-channel`]: https://crates.io/crates/async-channel

## Difference with other broadcast crates

* [`broadcaster`]: The main difference would be that `broadcaster` doesn't have a sender and
  receiver split and both sides use clones of the same BroadcastChannel instance. The messages are
  sent are sent to all channel clones. While this can work for many cases, the lack of sender and
  receiver split, means that often times, you'll find yourself having to drain the channel on the
  sending side yourself.

* [`postage`]: this crate provides a [broadcast API][pba] similar to `async_broadcast`. However, it:
  - (at the time of this writing) duplicates [futures] API, which isn't ideal.
  - Does not support overflow mode nor has the concept of inactive receivers, so a slow or inactive
    receiver blocking the whole channel is not a solvable problem.
  - Provides all kinds of channels, which is generally good but if you just need a broadcast
    channel, `async_broadcast` is probably a better choice.

* [`tokio::sync`]: Tokio's `sync` module provides a [broadcast channel][tbc] API. The differences
   here are:
  - While this implementation does provide [overflow mode][tom], it is the default behavior and not
    opt-in.
  - There is no equivalent of inactive receivers.
  - While it's possible to build tokio with only the `sync` module, it comes with other APIs that
    you may not need.

[`broadcaster`]: https://crates.io/crates/broadcaster
[`postage`]: https://crates.io/crates/postage
[pba]: https://docs.rs/postage/0.4.1/postage/broadcast/fn.channel.html
[futures]: https://crates.io/crates/futures
[`tokio::sync`]: https://docs.rs/tokio/1.6.0/tokio/sync
[tbc]: https://docs.rs/tokio/1.6.0/tokio/sync/broadcast/index.html
[tom]: https://docs.rs/tokio/1.6.0/tokio/sync/broadcast/index.html#lagging

## Safety
This crate uses ``#![deny(unsafe_code)]`` to ensure everything is implemented in
100% Safe Rust.

## Contributing
Want to join us? Check out our ["Contributing" guide][contributing] and take a
look at some of these issues:

- [Issues labeled "good first issue"][good-first-issue]
- [Issues labeled "help wanted"][help-wanted]

[contributing]: https://github.com/smol-rs/async-broadcast/blob/master/.github/CONTRIBUTING.md
[good-first-issue]: https://github.com/smol-rs/async-broadcast/labels/good%20first%20issue
[help-wanted]: https://github.com/smol-rs/async-broadcast/labels/help%20wanted

## License

<sup>
Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
</sup>

<br/>

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