tokio::sync::broadcast

Struct Sender

Source
pub struct Sender<T> { /* private fields */ }
Expand description

Sending-half of the broadcast channel.

May be used from many threads. Messages can be sent with send.

§Examples

use tokio::sync::broadcast;

#[tokio::main]
async fn main() {
    let (tx, mut rx1) = broadcast::channel(16);
    let mut rx2 = tx.subscribe();

    tokio::spawn(async move {
        assert_eq!(rx1.recv().await.unwrap(), 10);
        assert_eq!(rx1.recv().await.unwrap(), 20);
    });

    tokio::spawn(async move {
        assert_eq!(rx2.recv().await.unwrap(), 10);
        assert_eq!(rx2.recv().await.unwrap(), 20);
    });

    tx.send(10).unwrap();
    tx.send(20).unwrap();
}

Implementations§

Source§

impl<T> Sender<T>

Source

pub fn new(capacity: usize) -> Self

Creates the sending-half of the broadcast channel.

See the documentation of broadcast::channel for more information on this method.

Source

pub fn send(&self, value: T) -> Result<usize, SendError<T>>

Attempts to send a value to all active Receiver handles, returning it back if it could not be sent.

A successful send occurs when there is at least one active Receiver handle. An unsuccessful send would be one where all associated Receiver handles have already been dropped.

§Return

On success, the number of subscribed Receiver handles is returned. This does not mean that this number of receivers will see the message as a receiver may drop or lag (see lagging) before receiving the message.

§Note

A return value of Ok does not mean that the sent value will be observed by all or any of the active Receiver handles. Receiver handles may be dropped before receiving the sent message.

A return value of Err does not mean that future calls to send will fail. New Receiver handles may be created by calling subscribe.

§Examples
use tokio::sync::broadcast;

#[tokio::main]
async fn main() {
    let (tx, mut rx1) = broadcast::channel(16);
    let mut rx2 = tx.subscribe();

    tokio::spawn(async move {
        assert_eq!(rx1.recv().await.unwrap(), 10);
        assert_eq!(rx1.recv().await.unwrap(), 20);
    });

    tokio::spawn(async move {
        assert_eq!(rx2.recv().await.unwrap(), 10);
        assert_eq!(rx2.recv().await.unwrap(), 20);
    });

    tx.send(10).unwrap();
    tx.send(20).unwrap();
}
Source

pub fn subscribe(&self) -> Receiver<T>

Creates a new Receiver handle that will receive values sent after this call to subscribe.

§Examples
use tokio::sync::broadcast;

#[tokio::main]
async fn main() {
    let (tx, _rx) = broadcast::channel(16);

    // Will not be seen
    tx.send(10).unwrap();

    let mut rx = tx.subscribe();

    tx.send(20).unwrap();

    let value = rx.recv().await.unwrap();
    assert_eq!(20, value);
}
Source

pub fn len(&self) -> usize

Returns the number of queued values.

A value is queued until it has either been seen by all receivers that were alive at the time it was sent, or has been evicted from the queue by subsequent sends that exceeded the queue’s capacity.

§Note

In contrast to Receiver::len, this method only reports queued values and not values that have been evicted from the queue before being seen by all receivers.

§Examples
use tokio::sync::broadcast;

#[tokio::main]
async fn main() {
    let (tx, mut rx1) = broadcast::channel(16);
    let mut rx2 = tx.subscribe();

    tx.send(10).unwrap();
    tx.send(20).unwrap();
    tx.send(30).unwrap();

    assert_eq!(tx.len(), 3);

    rx1.recv().await.unwrap();

    // The len is still 3 since rx2 hasn't seen the first value yet.
    assert_eq!(tx.len(), 3);

    rx2.recv().await.unwrap();

    assert_eq!(tx.len(), 2);
}
Source

pub fn is_empty(&self) -> bool

Returns true if there are no queued values.

§Examples
use tokio::sync::broadcast;

#[tokio::main]
async fn main() {
    let (tx, mut rx1) = broadcast::channel(16);
    let mut rx2 = tx.subscribe();

    assert!(tx.is_empty());

    tx.send(10).unwrap();

    assert!(!tx.is_empty());

    rx1.recv().await.unwrap();

    // The queue is still not empty since rx2 hasn't seen the value.
    assert!(!tx.is_empty());

    rx2.recv().await.unwrap();

    assert!(tx.is_empty());
}
Source

pub fn receiver_count(&self) -> usize

Returns the number of active receivers.

An active receiver is a Receiver handle returned from channel or subscribe. These are the handles that will receive values sent on this Sender.

§Note

It is not guaranteed that a sent message will reach this number of receivers. Active receivers may never call recv again before dropping.

§Examples
use tokio::sync::broadcast;

#[tokio::main]
async fn main() {
    let (tx, _rx1) = broadcast::channel(16);

    assert_eq!(1, tx.receiver_count());

    let mut _rx2 = tx.subscribe();

    assert_eq!(2, tx.receiver_count());

    tx.send(10).unwrap();
}
Source

pub fn same_channel(&self, other: &Self) -> bool

Returns true if senders belong to the same channel.

§Examples
use tokio::sync::broadcast;

#[tokio::main]
async fn main() {
    let (tx, _rx) = broadcast::channel::<()>(16);
    let tx2 = tx.clone();

    assert!(tx.same_channel(&tx2));

    let (tx3, _rx3) = broadcast::channel::<()>(16);

    assert!(!tx3.same_channel(&tx2));
}

Trait Implementations§

Source§

impl<T> Clone for Sender<T>

Source§

fn clone(&self) -> Sender<T>

Returns a copy of the value. Read more
1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<T> Debug for Sender<T>

Source§

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl<T> Drop for Sender<T>

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

impl<T: Send> Send for Sender<T>

Source§

impl<T: Send> Sync for Sender<T>

Auto Trait Implementations§

§

impl<T> Freeze for Sender<T>

§

impl<T> RefUnwindSafe for Sender<T>

§

impl<T> Unpin for Sender<T>

§

impl<T> UnwindSafe for Sender<T>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.