Deadqueue

https://docs.rs/deadqueue/0.2.5/deadqueue/
Admin
Deadqueue is a dead simple async queue library for Rust with back pressure support and three...
Tokens:5,331
Snippets:76
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Borrow Deadlock Example

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/type.Receiver.html

Demonstrates a potential deadlock scenario when holding a borrow across tasks.

```rust
// Task 1 (on thread A)    |  // Task 2 (on thread B)
let _ref1 = rx.borrow();   |
                           |  // will block
                           |  let _ = tx.send(());
// may deadlock            |
let _ref2 = rx.borrow();   |
```

--------------------------------

### Borrow and Update Deadlock Example

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/type.Receiver.html

Demonstrates a potential deadlock scenario when using borrow_and_update across tasks.

```rust
// Task 1 (on thread A)                |  // Task 2 (on thread B)
let _ref1 = rx1.borrow_and_update();   |
                                       |  // will block
                                       |  let _ = tx.send(());
// may deadlock                        |
let _ref2 = rx2.borrow_and_update();   |
```

--------------------------------

### Check for Changes Example

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/type.Receiver.html

Checks if the channel contains a message that has not been seen yet.

```rust
use tokio::sync::watch;

#[tokio::main]
async fn main() {
    let (tx, mut rx) = watch::channel("hello");

    tx.send("goodbye").unwrap();

    assert!(rx.has_changed().unwrap());
    assert_eq!(*rx.borrow_and_update(), "goodbye");

    // The value has been marked as seen
    assert!(!rx.has_changed().unwrap());

    drop(tx);
    // The `tx` handle has been dropped
    assert!(rx.has_changed().is_err());
}
```

--------------------------------

### Get the Capacity of the Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Returns the maximum number of items the queue can store.

```rust
pub fn capacity(&self) -> usize
```

--------------------------------

### Get Available Slots in the Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Returns the number of available slots in the queue. A negative value indicates the number of futures currently waiting to push an item.

```rust
pub fn available(&self) -> isize
```

--------------------------------

### Borrow Value Example

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/type.Receiver.html

Retrieves the most recently sent value from the channel.

```rust
use tokio::sync::watch;

let (_, rx) = watch::channel("hello");
assert_eq!(*rx.borrow(), "hello");
```

--------------------------------

### Get the Current Length of the Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Returns the number of items currently stored in the queue.

```rust
pub fn len(&self) -> usize
```

--------------------------------

### Create New Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/limited/struct.Queue.html

Instantiates a new, empty queue with a specified maximum size. This is the primary way to initialize the queue.

```rust
pub fn new(max_size: usize) -> Self
```

--------------------------------

### Create a New Resizable Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Creates a new, empty queue with a specified maximum capacity. Use this to initialize a bounded queue.

```rust
pub async fn new(max_size: usize) -> Self
```

--------------------------------

### Queue Methods

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/limited/struct.Queue.html

Provides methods for creating, manipulating, and querying the state of the `Queue`.

```APIDOC
## Queue Methods

### `new(max_size: usize) -> Self`

Create a new empty queue with a specified maximum size.

### `pop(&self) -> T`

Get an item from the queue. If the queue is currently empty, this method blocks until an item is available.

### `try_pop(&self) -> Option<T>`

Try to get an item from the queue. If the queue is currently empty, return `None`.

### `push(&self, item: T)`

Push an item into the queue. This is an asynchronous operation that may block if the queue is full.

### `try_push(&self, item: T) -> Result<(), T>`

Try to push an item into the queue. If the queue is full, the item is returned as `Err(T)`.

### `capacity(&self) -> usize`

Get the capacity of the queue (maximum number of items it can store).

### `len(&self) -> usize`

Get the current number of items stored in the queue.

### `is_empty(&self) -> bool`

Returns `true` if the queue is empty, `false` otherwise.

### `is_full(&self) -> bool`

Returns `true` if the queue is full, `false` otherwise.

### `available(&self) -> isize`

The number of available items in the queue. If there are no items, this number can be negative, indicating the number of futures waiting for an item.

### `wait_full(&self)`

Asynchronously await until the queue is full.

### `subscribe_full(&self) -> Receiver`

Get a `Receiver` object that can be used to repeatedly await queue-full notifications.

### `wait_empty(&self)`

Asynchronously await until the queue is empty.

### `subscribe_empty(&self) -> Receiver`

Get a `Receiver` object that can be used to repeatedly await queue-empty notifications.
```

--------------------------------

### Queue Initialization from Iterator

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/limited/struct.Queue.html

Allows creating a `Queue` from an iterator that provides an exact size.

```APIDOC
## From Iterator

### `impl<T, I> From<I> for Queue<T>` where `I: IntoIterator<Item = T>`, `<I as IntoIterator>::IntoIter: ExactSizeIterator`

### `from(iter: I) -> Self`

Create a new queue from the given exact size iterator of objects.
```

--------------------------------

### Implement a limited async queue with workers

Source: https://docs.rs/deadqueue

Demonstrates using a limited queue to distribute tasks among multiple tokio workers. Requires the limited feature enabled in Cargo.toml.

```rust
use std::sync::Arc;
use tokio::time::{sleep, Duration};

const TASK_COUNT: usize = 1000;
const WORKER_COUNT: usize = 10;

type TaskQueue = deadqueue::limited::Queue<usize>;

#[tokio::main]
async fn main() {
    let queue = Arc::new(TaskQueue::new(TASK_COUNT));
    for i in 0..TASK_COUNT {
        queue.try_push(i).unwrap();
    }
    for worker in 0..WORKER_COUNT {
        let queue = queue.clone();
        tokio::spawn(async move {
            loop {
                let task = queue.pop().await;
                println!("worker[{}] processing task[{}] ...", worker, task);
            }
        });
    }
    println!("Waiting for workers to finish...");
    queue.wait_empty().await;
    println!("All tasks done. :-)");
}
```

--------------------------------

### Queue Operations

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Methods for interacting with the resizable queue, including pushing, popping, and resizing.

```APIDOC
## Queue Methods

### new(max_size: usize) -> Self
Creates a new empty queue with a specified maximum capacity.

### pop() -> T
Asynchronously retrieves an item from the queue. Blocks if the queue is empty.

### try_pop() -> Option<T>
Attempts to retrieve an item from the queue without blocking. Returns None if empty.

### push(item: T)
Asynchronously pushes an item into the queue.

### try_push(item: T) -> Result<(), T>
Attempts to push an item into the queue. Returns Err(item) if the queue is full.

### resize(target_capacity: usize)
Asynchronously resizes the queue to the target capacity. Increasing capacity is non-blocking; decreasing may block if there are pending push operations.
```

--------------------------------

### Try to Push an Item to the Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Attempts to add an item to the queue without blocking. Returns `Ok(())` on success, or `Err(item)` if the queue is full, returning the item.

```rust
pub fn try_push(&self, item: T) -> Result<(), T>
```

--------------------------------

### Create Queue from Iterator

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/limited/struct.Queue.html

Constructs a new queue from an `ExactSizeIterator`. This is a convenient way to initialize the queue with pre-existing data.

```rust
fn from(iter: I) -> Self
```

--------------------------------

### Queue Status and Monitoring

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Methods for inspecting the state of the queue and subscribing to capacity events.

```APIDOC
## Monitoring Methods

### capacity() -> usize
Returns the maximum number of items the queue can store.

### len() -> usize
Returns the current number of items in the queue.

### is_empty() -> bool
Returns true if the queue contains no items.

### is_full() -> bool
Returns true if the queue is at maximum capacity.

### subscribe_full() -> Receiver
Returns a receiver for notifications when the queue becomes full.

### subscribe_empty() -> Receiver
Returns a receiver for notifications when the queue becomes empty.
```

--------------------------------

### Deadqueue Structs

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/all.html

Overview of the available queue implementations within the deadqueue crate.

```APIDOC
## Structs

### `limited::Queue`

Represents a queue with a fixed capacity.

### `resizable::Queue`

Represents a queue that can dynamically resize its capacity.

### `unlimited::Queue`

Represents a queue with no capacity limit.
```

--------------------------------

### Struct: unlimited::Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/unlimited/index.html

Documentation for the unlimited Queue struct provided by the deadqueue crate.

```APIDOC
## Struct unlimited::Queue

### Description
A queue implementation that is unlimited in size.

### Details
- **Module**: unlimited
- **Type**: Struct
```

--------------------------------

### Subscribe to Queue Full Notifications

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Obtains a `Receiver` that can be used to repeatedly await notifications when the queue becomes full.

```rust
pub fn subscribe_full(&self) -> Receiver
```

--------------------------------

### Struct: Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/index.html

The Queue struct provides a resizable queue implementation that is limited in size.

```APIDOC
## Struct: Queue

### Description
Queue that is limited in size and supports resizing.

### Fields

This struct does not have explicitly documented fields in the provided text. However, based on its description, it likely contains internal data structures to manage the queue's elements and size.
```

--------------------------------

### Try Convert into Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Implements `TryFrom<U>` for `T`, allowing fallible conversion from type `U` to type `T`.

```rust
type Error = Infallible;
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

--------------------------------

### Create Queue from Iterator

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Implements `FromIterator` for `Queue`, enabling the creation of a queue directly from any iterator.

```rust
fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self
```

--------------------------------

### Queue Operations

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/unlimited/struct.Queue.html

Methods for interacting with the unlimited queue, including pushing, popping, and status checks.

```APIDOC
## Queue Operations

### Description
Methods to manage items within the unlimited queue.

### Methods
- **new()**: Create a new empty queue.
- **push(item: T)**: Push an item into the queue.
- **pop() -> T**: Get an item from the queue, blocking if empty.
- **try_pop() -> Option<T>**: Attempt to get an item, returning None if empty.
- **len() -> usize**: Get the current number of items in the queue.
- **is_empty() -> bool**: Check if the queue is empty.
- **available() -> isize**: Get the difference between queue length and waiting tasks.
- **wait_empty()**: Await until the queue is empty.
- **subscribe_empty() -> Receiver**: Get a receiver for queue-empty notifications.
```

--------------------------------

### Asynchronously Push an Item into the Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Adds an item to the queue. If the queue is full, this operation will block asynchronously until space becomes available.

```rust
pub async fn push(&self, item: T)
```

--------------------------------

### Try Convert Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Implements `TryInto<U>` for `T`, enabling fallible conversion from type `T` to type `U` if `U` implements `TryFrom<T>`.

```rust
type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

--------------------------------

### Define Queue struct

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/unlimited/struct.Queue.html

The definition of the unlimited Queue structure.

```rust
pub struct Queue<T> { /* private fields */ }
```

--------------------------------

### Try to Pop an Item from the Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Attempts to retrieve an item from the queue without blocking. Returns `Some(item)` if an item is available, otherwise returns `None`.

```rust
pub fn try_pop(&self) -> Option<T>
```

--------------------------------

### Subscribe to Queue Empty Notifications

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Obtains a `Receiver` that can be used to repeatedly await notifications when the queue becomes empty.

```rust
pub fn subscribe_empty(&self) -> Receiver
```

--------------------------------

### Convert to Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Implements the `From<T>` trait, allowing a value of type `T` to be converted into a `Queue<T>` (though this specific implementation returns the argument unchanged, implying it's a placeholder or part of a larger trait context).

```rust
fn from(t: T) -> T
```

--------------------------------

### async fn wait_for()

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/type.Receiver.html

Waits for a value that satisfies a provided condition.

```APIDOC
## async fn wait_for()

### Description
Waits for a value that satisfies the provided condition. It calls the closure on the current value and subsequent updates until the closure returns true.

### Parameters
- **f** (impl FnMut(&T) -> bool) - Required - A closure that returns true when the desired value is found.

### Response
- **Result<Ref<'_, T>, RecvError>** - Returns a reference to the value that satisfied the condition, or a RecvError if the channel is closed.
```

--------------------------------

### Await Until the Queue is Full

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Asynchronously waits until the queue reaches its maximum capacity. Useful for back pressure scenarios.

```rust
pub async fn wait_full(&self)
```

--------------------------------

### async fn changed()

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/type.Receiver.html

Waits for a change notification in the channel and marks the newest value as seen.

```APIDOC
## async fn changed()

### Description
Waits for a change notification, then marks the newest value as seen. If the newest value has not been marked seen, it returns immediately. Otherwise, it sleeps until a new message is sent or the sender is dropped.

### Parameters
- **&mut self** - The receiver instance.

### Response
- **Result<(), RecvError>** - Returns Ok(()) if a change was detected, or an error if the sender has been dropped.
```

--------------------------------

### Deadqueue Type Aliases

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/all.html

Information about type aliases provided by the deadqueue crate.

```APIDOC
## Type Aliases

### `Receiver`

An alias for a type used for receiving elements from a queue.
```

--------------------------------

### fn same_channel()

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/type.Receiver.html

Checks if two receivers belong to the same channel.

```APIDOC
## fn same_channel()

### Description
Returns true if the provided receiver belongs to the same channel as the current receiver.

### Parameters
- **other** (&Receiver<T>) - Required - The other receiver to compare against.

### Response
- **bool** - True if they share the same channel, false otherwise.
```

--------------------------------

### Queue Struct

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/limited/struct.Queue.html

The `Queue` struct represents a limited-size queue that does not support resizing. It is based on `crossbeam_queue::ArrayQueue` and provides back pressure on push operations. This feature is enabled via the `limited` feature in `Cargo.toml`.

```APIDOC
## Struct Queue

### Description
Queue that is limited in size and does not support resizing.
This queue implementation has the following characteristics:
  * Based on `crossbeam_queue::ArrayQueue`
  * Has limit capacity with back pressure on push
  * Does not support resizing
  * Enabled via the `limited` feature in your `Cargo.toml`

### Fields
(Private fields, not exposed for direct manipulation)
```

--------------------------------

### Await Until the Queue is Empty

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Asynchronously waits until all items have been removed from the queue.

```rust
pub async fn wait_empty(&self)
```

--------------------------------

### Convert into Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Implements the `Into<U>` trait, enabling conversion of a type `T` into another type `U` if `U` implements `From<T>`.

```rust
fn into(self) -> U
```

--------------------------------

### Format Queue for Debugging

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Implements the `Debug` trait for the `Queue` struct, allowing it to be formatted for debugging purposes.

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

--------------------------------

### TryFrom Conversion

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/limited/struct.Queue.html

Attempts to convert a value into the queue type. The `Error` type is `Infallible`, indicating success is always possible if the input type is compatible.

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

--------------------------------

### Check if the Queue is Empty

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Returns `true` if the queue contains no items, `false` otherwise.

```rust
pub fn is_empty(&self) -> bool
```

--------------------------------

### Asynchronously Pop an Item from the Queue

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Retrieves an item from the queue. If the queue is empty, this method will block asynchronously until an item becomes available.

```rust
pub async fn pop(&self) -> T
```

--------------------------------

### TryInto Conversion

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/limited/struct.Queue.html

Attempts to convert the queue into another type `U`. The `Error` type depends on the `TryFrom<Queue<T>>` implementation for `U`.

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

--------------------------------

### Resize the Queue Capacity

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Adjusts the queue's capacity to a new target size. Decreasing capacity may block if items are waiting to be pushed.

```rust
pub async fn resize(&self, target_capacity: usize)
```

--------------------------------

### Check if the Queue is Full

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Returns `true` if the queue has reached its maximum capacity. Note: This can be inaccurate during concurrent push/pop operations; `try_push` is recommended for safety.

```rust
pub fn is_full(&self) -> bool
```

--------------------------------

### Receiver Type Alias

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/type.Receiver.html

The public type alias for subscribe_full and subscribe_empty.

```rust
pub type Receiver = Receiver<()>();
```

--------------------------------

### Receiver Methods

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/type.Receiver.html

Methods available for the Receiver type to interact with channel values and state.

```APIDOC
## Receiver Methods

### borrow()
Returns a reference to the most recently sent value without marking it as seen.

### borrow_and_update()
Returns a reference to the most recently sent value and marks that value as seen.

### has_changed()
Checks if this channel contains a message that this receiver has not yet seen. Returns a Result<bool, RecvError>.

### mark_changed()
Marks the state as changed, causing has_changed() to return true.

### mark_unchanged()
Marks the state as unchanged, considering the current value as seen.
```

--------------------------------

### Wait for Condition Satisfaction

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/type.Receiver.html

Waits for a value that satisfies a provided condition. The closure is called on the current value before waiting. If the channel is closed, returns `RecvError`. This method is cancel safe.

```rust
use tokio::sync::watch;
use tokio::time::{sleep, Duration};

#[tokio::main(flavor = "current_thread", start_paused = true)]
async fn main() {
    let (tx, mut rx) = watch::channel("hello");

    tokio::spawn(async move {
        sleep(Duration::from_secs(1)).await;
        tx.send("goodbye").unwrap();
    });

    assert!(rx.wait_for(|val| *val == "goodbye").await.is_ok());
    assert_eq!(*rx.borrow(), "goodbye");
}
```

--------------------------------

### Queue TypeId

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Provides the `TypeId` for the `Queue` type, used in dynamic trait object handling.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Receiver Struct Definition

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/type.Receiver.html

The internal structure of the Receiver type.

```rust
pub struct Receiver { /* private fields */ }
```

--------------------------------

### Borrow Queue Item

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Implements the `Borrow` trait, allowing immutable access to the underlying item type `T`.

```rust
fn borrow(&self) -> &T
```

--------------------------------

### Wait for Change Notification

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/type.Receiver.html

Waits for a change notification and marks the newest value as seen. Returns an error if the sender is dropped. This method is cancel safe.

```rust
use tokio::sync::watch;

#[tokio::main]
async fn main() {
    let (tx, mut rx) = watch::channel("hello");

    tokio::spawn(async move {
        tx.send("goodbye").unwrap();
    });

    assert!(rx.changed().await.is_ok());
    assert_eq!(*rx.borrow_and_update(), "goodbye");

    // The `tx` handle has been dropped
    assert!(rx.changed().await.is_err());
}
```

--------------------------------

### Check if Receivers Belong to the Same Channel

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/type.Receiver.html

Returns `true` if the two `Receiver` instances belong to the same watch channel. This is useful for verifying channel associations.

```rust
let (tx, rx) = tokio::sync::watch::channel(true);
let rx2 = rx.clone();
assert!(rx.same_channel(&rx2));

let (tx3, rx3) = tokio::sync::watch::channel(true);
assert!(!rx3.same_channel(&rx2));
```

--------------------------------

### Borrow Mutably Queue Item

Source: https://docs.rs/deadqueue/0.2.5/deadqueue/resizable/struct.Queue.html

Implements the `BorrowMut` trait, allowing mutable access to the underlying item type `T`.

```rust
fn borrow_mut(&mut self) -> &mut T
```
Tokens:
Raw