Struct OverwriteSender 

pub struct OverwriteSender<T> { /* private fields */ }

A sender that can overwrite old messages when the channel reaches capacity.

OverwriteSender<T> wraps a flume Sender<T> and provides additional functionality to automatically remove old messages when sending would block due to a full channel.

This struct implements Deref to Sender<T>, so all standard sender methods are available. Additionally, it provides send_overwrite and send_overwrite_async methods that will never block due to a full channel.

Examples

use flume_overwrite::bounded;

let (sender, receiver) = bounded(1);

// First message goes through normally
sender.send_overwrite("first").unwrap();

// Second message overwrites the first
let overwritten = sender.send_overwrite("second").unwrap();
assert_eq!(overwritten, Some(vec!["first"]));

Implementations

impl<T> OverwriteSender<T>

pub fn send_overwrite(&self, value: T) -> Result<Option<Vec<T>>, SendError<T>>

Sends a value, overwriting old messages if the channel is at capacity.

This method will never block. If the channel is at capacity, it will remove old messages from the front of the queue until there’s space for the new message.

Arguments

• value - The value to send through the channel

Returns

• Ok(None) - The message was sent without overwriting any existing messages
• Ok(Some(Vec<T>)) - The message was sent and the returned vector contains the messages that were overwritten (removed from the channel)
• Err(SendError<T>) - The channel is disconnected

Examples

use flume_overwrite::bounded;

let (sender, receiver) = bounded(2);

// Send without overwriting
assert_eq!(sender.send_overwrite(1).unwrap(), None);
assert_eq!(sender.send_overwrite(2).unwrap(), None);

// This will overwrite the first message
let overwritten = sender.send_overwrite(3).unwrap();
assert_eq!(overwritten, Some(vec![1]));

pub async fn send_overwrite_async( &self, value: T, ) -> Result<Option<Vec<T>>, SendError<T>>

Asynchronously sends a value, overwriting old messages if the channel is at capacity.

This is the async version of send_overwrite. Like its synchronous counterpart, this method will never block due to a full channel - it will instead remove old messages to make space.

Arguments

• value - The value to send through the channel

Returns

A future that resolves to:

• Ok(None) - The message was sent without overwriting any existing messages
• Ok(Some(Vec<T>)) - The message was sent and the returned vector contains the messages that were overwritten (removed from the channel)
• Err(SendError<T>) - The channel is disconnected

Examples

use flume_overwrite::bounded;
use futures::executor::block_on;

let (sender, receiver) = bounded(1);

block_on(async {
    // Send without overwriting
    assert_eq!(sender.send_overwrite_async(1).await.unwrap(), None);
     
    // This will overwrite the first message
    let overwritten = sender.send_overwrite_async(2).await.unwrap();
    assert_eq!(overwritten, Some(vec![1]));
});

Methods from Deref<Target = Sender<T>>

pub fn send_async(&self, item: T) -> SendFut<'_, T>

Asynchronously send a value into the channel, returning an error if all receivers have been dropped. If the channel is bounded and is full, the returned future will yield to the async runtime.

In the current implementation, the returned future will not yield to the async runtime if the channel is unbounded. This may change in later versions.

pub fn sink(&self) -> SendSink<'_, T>

Create an asynchronous sink that uses this sender to asynchronously send messages into the channel. The sender will continue to be usable after the sink has been dropped.

In the current implementation, the returned sink will not yield to the async runtime if the channel is unbounded. This may change in later versions.

pub fn try_send(&self, msg: T) -> Result<(), TrySendError<T>>

Attempt to send a value into the channel. If the channel is bounded and full, or all receivers have been dropped, an error is returned. If the channel associated with this sender is unbounded, this method has the same behaviour as Sender::send.

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

Send a value into the channel, returning an error if all receivers have been dropped. If the channel is bounded and is full, this method will block until space is available or all receivers have been dropped. If the channel is unbounded, this method will not block.

pub fn send_deadline( &self, msg: T, deadline: Instant, ) -> Result<(), SendTimeoutError<T>>

Send a value into the channel, returning an error if all receivers have been dropped or the deadline has passed. If the channel is bounded and is full, this method will block until space is available, the deadline is reached, or all receivers have been dropped.

pub fn send_timeout( &self, msg: T, dur: Duration, ) -> Result<(), SendTimeoutError<T>>

Send a value into the channel, returning an error if all receivers have been dropped or the timeout has expired. If the channel is bounded and is full, this method will block until space is available, the timeout has expired, or all receivers have been dropped.

pub fn is_disconnected(&self) -> bool

Returns true if all receivers for this channel have been dropped.

pub fn is_empty(&self) -> bool

Returns true if the channel is empty. Note: Zero-capacity channels are always empty.

pub fn is_full(&self) -> bool

Returns true if the channel is full. Note: Zero-capacity channels are always full.

pub fn len(&self) -> usize

Returns the number of messages in the channel

pub fn capacity(&self) -> Option<usize>

If the channel is bounded, returns its capacity.

pub fn sender_count(&self) -> usize

Get the number of senders that currently exist, including this one.

pub fn receiver_count(&self) -> usize

Get the number of receivers that currently exist.

Note that this method makes no guarantees that a subsequent send will succeed; it’s possible that between receiver_count() being called and a send(), all open receivers could drop.

pub fn downgrade(&self) -> WeakSender<T>

Creates a WeakSender that does not keep the channel open.

The channel is closed once all Senders are dropped, even if there are still active WeakSenders.

pub fn same_channel(&self, other: &Sender<T>) -> bool

Returns whether the senders are belong to the same channel.

Trait Implementations

impl<T: Clone> Clone for OverwriteSender<T>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for OverwriteSender<T>

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

Formats the value using the given formatter.

impl<T> Deref for OverwriteSender<T>

type Target = Sender<T>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.