Thingbuf

https://docs.rs/thingbuf/0.1.6/thingbuf/
Admin
Thingbuf is a lock-free array-based concurrent ring buffer and asynchronous/blocking bounded MPSC...
Tokens:22,018
Snippets:124
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### ThingBuf Capacity Example (Rust)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Illustrates how to check the total capacity of a ThingBuf. The capacity remains constant regardless of the number of elements pushed into the queue.

```rust
use thingbuf::ThingBuf;

let q = ThingBuf::<usize>::new(100);
assert_eq!(q.capacity(), 100);
```

```rust
let q = ThingBuf::<usize>::new(100);

*q.push_ref().unwrap() = 1;
*q.push_ref().unwrap() = 2;
*q.push_ref().unwrap() = 3;

assert_eq!(q.capacity(), 100);
```

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

### ThingBuf Usage Example (Rust)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Demonstrates the basic usage of `ThingBuf` by creating a queue with a capacity of 2, pushing elements, and showing the behavior when the queue is full. It utilizes the `push` method and checks for errors when capacity is reached.

```Rust
use thingbuf::ThingBuf;

let q = ThingBuf::new(2);

// Push some values to the queue.
q.push(1).unwrap();
q.push(2).unwrap();

// Now, the queue is at capacity.
assert!(q.push(3).is_err());
```

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

### StaticChannel Capacity Example - Rust

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/blocking/struct

Demonstrates how to get the total capacity of a StaticChannel using the capacity() method. The capacity remains constant regardless of the number of messages sent.

```rust
use thingbuf::mpsc::blocking::StaticChannel;

static CHANNEL: StaticChannel<usize, 100> = StaticChannel::new();

let (tx, _) = CHANNEL.split();
assert_eq!(tx.capacity(), 100);


let (tx, rx) = CHANNEL.split();
*tx.try_send_ref().unwrap() = 1;
*tx.try_send_ref().unwrap() = 2;
*tx.try_send_ref().unwrap() = 3;

assert_eq!(tx.capacity(), 100);
```

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

### thingbuf mpsc StaticSender send_ref example

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/struct

Demonstrates sending formatted strings by writing them directly to channel slots in place using `send_ref`. This method reserves a writable slot, returning a `SendRef` that allows in-place mutation, facilitating allocation reuse.

```Rust
use thingbuf::mpsc;
use std::fmt::Write;

static CHANNEL: mpsc::StaticChannel<String, 8> = mpsc::StaticChannel::new();

#[tokio::main]
async fn main() {
    let (tx, rx) = CHANNEL.split();

    // Spawn a task that prints each message received from the channel:
    tokio::spawn(async move {
        for _ in 0..10 {
            let msg = rx.recv_ref().await.unwrap();
            println!("{}", msg);
        }
    });

    // Until the channel closes, write formatted messages to the channel.
    let mut count = 1;
    while let Ok(mut value) = tx.send_ref().await {
        // Writing to the `SendRef` will reuse the *existing* string
        // allocation in place.
        write!(value, "hello from message {}", count)
            .expect("writing to a `String` should never fail");
        count += 1;
    }
}
```

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

### Get minimum capacity

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/recycling/struct

Shows how to retrieve the minimum initial capacity configured for a recycler. This is useful for understanding the allocation behavior of new elements.

```rust
use thingbuf::recycling::{Recycle, WithCapacity};

let recycle = WithCapacity::new();
assert_eq!(recycle.min_capacity(), 0);
```

```rust
use thingbuf::recycling::{Recycle, WithCapacity};

let recycle = WithCapacity::new().with_min_capacity(64);
assert_eq!(recycle.min_capacity(), 64);
```

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

### thingbuf::mpsc::blocking::StaticSender - Send example

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/blocking/struct

Demonstrates sending formatted strings by writing them directly to channel slots in place using `send_ref`. This allows for reusing existing string allocations.

```Rust
use thingbuf::mpsc::blocking::StaticChannel;
use std::{fmt::Write, thread};

static CHANNEL: StaticChannel<String, 8> = StaticChannel::new();

let (tx, rx) = CHANNEL.split();

// Spawn a thread that prints each message received from the channel:
thread::spawn(move || {
    for _ in 0..10 {
        let msg = rx.recv_ref().unwrap();
        println!("{}", msg);
    }
});

// Until the channel closes, write formatted messages to the channel.
let mut count = 1;
while let Ok(mut value) = tx.send_ref() {
    // Writing to the `SendRef` will reuse the *existing* string
    // allocation in place.
    write!(value, "hello from message {}", count)
        .expect("writing to a `String` should never fail");
    count += 1;
}
```

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

### ThingBuf Information Methods

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Methods to get the current status of the ThingBuf queue, such as its length and remaining capacity.

```APIDOC
## GET /thingbuf/remaining

### Description
Returns the unoccupied capacity of the queue (i.e., how many additional elements can be enqueued before the queue will be full). This is equivalent to subtracting the queue’s `len` from its `capacity`.

### Method
GET

### Endpoint
/thingbuf/remaining

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **remaining** (usize) - The number of unoccupied slots in the queue.

#### Response Example
```json
{
  "remaining": 97
}
```
```

```APIDOC
## GET /thingbuf/len

### Description
Returns the number of elements currently in the queue. To determine the queue’s remaining unoccupied capacity, use `remaining` instead.

### Method
GET

### Endpoint
/thingbuf/len

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **len** (usize) - The number of elements in the queue.

#### Response Example
```json
{
  "len": 3
}
```
```

```APIDOC
## GET /thingbuf/is_empty

### Description
Returns `true` if there are currently no elements in this `ThingBuf`.

### Method
GET

### Endpoint
/thingbuf/is_empty

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **is_empty** (boolean) - `true` if the queue is empty, `false` otherwise.

#### Response Example
```json
{
  "is_empty": true
}
```
```

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

### StaticChannel Length Example - Rust

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/blocking/struct

Illustrates how to get the current number of elements in a StaticChannel using the len() method. The length increases with sends and decreases with receives.

```rust
use thingbuf::mpsc::blocking::StaticChannel;

static CHANNEL: StaticChannel<usize, 100> = StaticChannel::new();

let (tx, rx) = CHANNEL.split();
assert_eq!(tx.len(), 0);

*tx.try_send_ref().unwrap() = 1;
*tx.try_send_ref().unwrap() = 2;
*tx.try_send_ref().unwrap() = 3;
assert_eq!(tx.len(), 3);

let _ = rx.try_recv_ref().unwrap();
assert_eq!(tx.len(), 2);
```

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

### Get ThingBuf Length and Check Emptiness (Rust)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Demonstrates how to get the current number of elements in a ThingBuf queue and how to check if the queue is empty. Uses the `len()` and `is_empty()` methods.

```Rust
use thingbuf::ThingBuf;

let q = ThingBuf::new(100);
assert_eq!(q.len(), 0);

*q.push_ref().unwrap() = 1;
*q.push_ref().unwrap() = 2;
*q.push_ref().unwrap() = 3;
assert_eq!(q.len(), 3);

let _ = q.pop_ref();
assert_eq!(q.len(), 2);

assert!(q.is_empty());

*q.push_ref().unwrap() = 1;
assert!(!q.is_empty());

let _ = q.pop_ref();
assert!(q.is_empty());
```

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

### Get total channel capacity

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/struct

Returns the total capacity of the channel for a StaticSender, including both occupied and unoccupied entries. This value remains constant regardless of the number of messages sent.

```rust
use thingbuf::mpsc::StaticChannel;

static CHANNEL: StaticChannel<usize, 100> = StaticChannel::new();

let (tx, _) = CHANNEL.split();
assert_eq!(tx.capacity(), 100);
```

```rust
let (tx, rx) = CHANNEL.split();
*tx.try_send_ref().unwrap() = 1;
*tx.try_send_ref().unwrap() = 2;
*tx.try_send_ref().unwrap() = 3;

assert_eq!(tx.capacity(), 100);
```

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

### Statically Allocated Channel Usage (Rust, no_std)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/index

Illustrates using a statically allocated channel in a no_std environment without heap allocation. The channel size is fixed at compile time (256 entries in this example). This is suitable for embedded systems.

```rust
// We are in a `no_std` context with no memory allocator!
#![no_std]
use thingbuf::mpsc;

// Create a channel backed by a static array with 256 entries.
static KERNEL_EVENTS: mpsc::StaticChannel<KernelEvent, 256> = mpsc::StaticChannel::new();

#[no_mangle]
pub fn kernel_main() {
    // Split the static channel into a sender/receiver pair.
    let (event_tx, event_rx) = KERNEL_EVENTS.split();
    let mut kernel_tasks = TaskExecutor::new();

    kernel_tasks.spawn(async move {
        // Process kernel events
        while let Some(event) = event_rx.recv().await {
            // ...
        }
    });

    // Some device driver that needs to emit events to the channel.
    kernel_tasks.spawn(some_device_driver(event_tx.clone()));

    loop {
        kernel_tasks.tick();
    }
}

async fn some_device_driver(event_tx: mpsc::StaticSender<KernelEvent>) {
    let mut device = SomeDevice::new(0x42);

    loop {
        // When the device has data, emit a kernel event.
        match device.poll_for_events().await {
            Ok(event) => event_tx.send(event).await.unwrap(),
            Err(err) => event_tx.send(KernelEvent::from(err)).await.unwrap(),
        }
    }
}
```

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

### thingbuf mpsc StaticSender send example

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/struct

Illustrates sending messages by value using the `send` method. This method takes the message by value and replaces any previous value in the slot, not functioning as an object pool during sending. It's suitable for messages without reusable heap allocations or when the receiver must take ownership by value.

```Rust
use thingbuf::mpsc;

static CHANNEL: mpsc::StaticChannel<i32, 8> = mpsc::StaticChannel::new();

#[tokio::main]
async fn main() {
    let (tx, rx) = CHANNEL.split();

    // Spawn a task that prints each message received from the channel:
    tokio::spawn(async move {
        for _ in 0..10 {
            let msg = rx.recv().await.unwrap();
            println!("received message {}", msg);
        }
    });

    // Until the channel closes, write the current iteration to the channel.
    let mut count = 1;
    while tx.send(count).await.is_ok() {
        count += 1;
    }
}
```

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

### Try Sending Value Immediately with ThingBuf

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/blocking/struct

This example covers `try_send`, which attempts to send a message by value immediately without blocking. It returns `TrySendError::Full` if the buffer is full or `TrySendError::Closed` if the receiver is dropped, and does not block.

```rust
pub fn try_send(&self, val: T) -> Result<(), TrySendError<T>>
Attempts to send a message by value immediately, without blocking until capacity is available.
This method differs from `send` by returning immediately if the channel’s buffer is full or no `StaticReceiver` exists. Compared with `send`, this method has two failure cases instead of one (one for disconnection, one for a full buffer), and this method will never block.

```

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

### Get remaining unoccupied channel capacity

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/struct

Returns the number of additional elements that can be sent before the channel becomes full. This is calculated as the channel's capacity minus its current length.

```rust
use thingbuf::mpsc::StaticChannel;

static CHANNEL: StaticChannel<usize, 100> = StaticChannel::new();

let (tx, rx) = CHANNEL.split();
assert_eq!(tx.remaining(), 100);

*tx.try_send_ref().unwrap() = 1;
*tx.try_send_ref().unwrap() = 2;
*tx.try_send_ref().unwrap() = 3;
assert_eq!(tx.remaining(), 97);

let _ = rx.try_recv_ref().unwrap();
assert_eq!(tx.remaining(), 98)
```

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

### StaticChannel IsEmpty Check Example - Rust

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/blocking/struct

Demonstrates checking if a StaticChannel is empty using the is_empty() method. It returns true if the channel contains no elements, and false otherwise.

```rust
use thingbuf::mpsc::blocking::StaticChannel;

static CHANNEL: StaticChannel<usize, 100> = StaticChannel::new();

let (tx, rx) = CHANNEL.split();
assert!(tx.is_empty());

*tx.try_send_ref().unwrap() = 1;

assert!(!tx.is_empty());
```

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

### Send Formatted Strings In-Place with ThingBuf

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/blocking/struct

This example shows how to send formatted strings by writing directly to channel slots using `send_ref_timeout`. It utilizes `StaticChannel` and demonstrates multithreaded communication, highlighting allocation reuse for `String` types.

```rust
use thingbuf::mpsc::{blocking::StaticChannel, errors::SendTimeoutError};
use std::{fmt::Write, time::Duration, thread};

static CHANNEL: StaticChannel<String, 1> = StaticChannel::new();
let (tx, rx) = CHANNEL.split();

thread::spawn(move || {
    thread::sleep(Duration::from_millis(500));
    let msg = rx.recv_ref().unwrap();
    println!("{}", msg);
    thread::sleep(Duration::from_millis(500));
});

thread::spawn(move || {
    let mut value = tx.send_ref_timeout(Duration::from_millis(200)).unwrap();
    write!(value, "hello").expect("writing to a `String` should never fail");
    thread::sleep(Duration::from_millis(400));

    let mut value = tx.send_ref_timeout(Duration::from_millis(200)).unwrap();
    write!(value, "world").expect("writing to a `String` should never fail");
    thread::sleep(Duration::from_millis(400));

    assert_eq!(
        Err(&SendTimeoutError::Timeout(())),
        tx.send_ref_timeout(Duration::from_millis(200)).as_deref().map(String::as_str)
    );
});
```

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

### Try Sending Reference In-Place with ThingBuf

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/blocking/struct

This example demonstrates `try_send_ref`, which attempts to reserve a slot for in-place mutation without blocking. It handles `TrySendError::Full` if the buffer is full and `TrySendError::Closed` if the receiver half is dropped, returning a `SendRef` for mutation.

```rust
pub fn try_send_ref(&self) -> Result<SendRef<'_, T>, TrySendError>
Attempts to reserve a slot in the channel to mutate in place, without blocking until capacity is available.
This method differs from `send_ref` by returning immediately if the channel’s buffer is full or no `StaticReceiver` exists. Compared with `send_ref`, this method has two failure cases instead of one (one for disconnection, one for a full buffer), and this method will never block.
Like `send_ref`, this method returns a `SendRef` that may be used to mutate a slot in the channel’s buffer in place. Dropping the `SendRef` completes the send operation and makes the mutated value available to the `StaticReceiver`.
##### §Errors
If the channel capacity has been reached (i.e., the channel has `n` buffered values where `n` is the `usize` const generic parameter of the `StaticChannel`), then `TrySendError::Full` is returned. In this case, a future call to `try_send` may succeed if additional capacity becomes available.
If the receive half of the channel is closed (i.e., the `StaticReceiver` handle was dropped), the function returns `TrySendError::Closed`. Once the channel has closed, subsequent calls to `try_send_ref` will never succeed.
Source
```

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

### thingbuf::mpsc::blocking::StaticSender - Send by value example

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/blocking/struct

Demonstrates sending messages by value using the `send` method. This method takes the message by value and replaces any previous value in the slot, not enabling object pooling.

```Rust
use thingbuf::mpsc::blocking::StaticChannel;
use std::{fmt::Write, thread};

static CHANNEL: StaticChannel<i32, 8> = StaticChannel::new();
let (tx, rx) = CHANNEL.split();

// Spawn a thread that prints each message received from the channel:
thread::spawn(move || {
    for _ in 0..10 {
        let msg = rx.recv().unwrap();
        println!("received message {}", msg);
    }
});

// Until the channel closes, write the current iteration to the channel.
let mut count = 1;
while tx.send(count).is_ok() {
    count += 1;
}
```

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

### Send Values with Timeout using ThingBuf

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/blocking/struct

This example demonstrates sending integer values through a `StaticChannel` with a specified timeout using `send_timeout`. It illustrates blocking behavior until a slot is free or the timeout occurs, and error handling for timeouts and closed channels.

```rust
use thingbuf::mpsc::{blocking::StaticChannel, errors::SendTimeoutError};
use std::{time::Duration, thread};

static CHANNEL: StaticChannel<i32, 1> = StaticChannel::new();
let (tx, rx) = CHANNEL.split();

thread::spawn(move || {
    thread::sleep(Duration::from_millis(500));
    let msg = rx.recv().unwrap();
    println!("{}", msg);
    thread::sleep(Duration::from_millis(500));
});

thread::spawn(move || {
    tx.send_timeout(1, Duration::from_millis(200)).unwrap();
    thread::sleep(Duration::from_millis(400));

    tx.send_timeout(2, Duration::from_millis(200)).unwrap();
    thread::sleep(Duration::from_millis(400));

    assert_eq!(
        Err(SendTimeoutError::Timeout(3)),
        tx.send_timeout(3, Duration::from_millis(200))
    );
});
```

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

### Get the number of elements currently in the channel

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/struct

Returns the current number of elements present in the channel for a StaticSender. This count decreases when messages are received and increases when messages are sent.

```rust
use thingbuf::mpsc::StaticChannel;

static CHANNEL: StaticChannel<usize, 100> = StaticChannel::new();

let (tx, rx) = CHANNEL.split();
assert_eq!(tx.len(), 0);

*tx.try_send_ref().unwrap() = 1;
*tx.try_send_ref().unwrap() = 2;
*tx.try_send_ref().unwrap() = 3;
assert_eq!(tx.len(), 3);

let _ = rx.try_recv_ref().unwrap();
assert_eq!(tx.len(), 2);
```

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

### StaticChannel Remaining Capacity Example - Rust

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/blocking/struct

Shows how to check the unoccupied capacity of a StaticChannel using the remaining() method. This value decreases as messages are sent and increases as they are received.

```rust
use thingbuf::mpsc::blocking::StaticChannel;

static CHANNEL: StaticChannel<usize, 100> = StaticChannel::new();

let (tx, rx) = CHANNEL.split();
assert_eq!(tx.remaining(), 100);

*tx.try_send_ref().unwrap() = 1;
*tx.try_send_ref().unwrap() = 2;
*tx.try_send_ref().unwrap() = 3;
assert_eq!(tx.remaining(), 97);

let _ = rx.try_recv_ref().unwrap();
assert_eq!(tx.remaining(), 98)
```

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

### ThingBuf Initialization

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Methods for creating a new ThingBuf instance.

```APIDOC
## POST /thingbuf/with_recycle

### Description
Returns a new `ThingBuf` with space for `capacity` elements and the provided recycling policy.

### Method
POST

### Endpoint
/thingbuf/with_recycle

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **capacity** (usize) - The number of elements the queue can hold.
- **recycle** (object) - The recycling policy for the queue. The specific structure depends on the implementation of the `Recycle` trait.

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the ThingBuf was created.

#### Response Example
```json
{
  "message": "ThingBuf created successfully"
}
```

### Panics
Panics if the capacity exceeds `usize::MAX & !(1 << (usize::BITS - 1))`.
```

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

### Get TypeId using Any trait

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/recycling/struct

Demonstrates how to get the TypeId of a type using the Any trait's type_id method. This is a fundamental operation for runtime type introspection in Rust.

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

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

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

### ThingBuf Initialization

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Creates a new ThingBuf with a specified capacity.

```APIDOC
## POST /new

### Description
Returns a new `ThingBuf` with space for `capacity` elements.

### Method
POST

### Endpoint
/new

### Parameters
#### Query Parameters
- **capacity** (usize) - Required - The total number of elements the queue can hold.

### Request Example
```json
{
  "capacity": 1024
}
```

### Response
#### Success Response (200)
- **ThingBuf<T>** (ThingBuf) - A new, empty ThingBuf.

#### Response Example
```json
{
  "queue": []
}
```
```

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

### Type Identification (Any Trait)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Provides a method to get the `TypeId` of a type. This is part of the `Any` trait implementation, which allows for runtime type introspection.

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

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

### Create ThingBuf with Custom Recycling Policy (Rust)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Shows how to create a new ThingBuf instance with a specified capacity and a custom recycling policy.

```Rust
use thingbuf::ThingBuf;

struct MyRecycle;
impl thingbuf::Recycle<i32> for MyRecycle {
    // Implementation details for Recycle trait
    fn recycle(&self, _data: i32) -> i32 {
        // Example recycling logic
        0
    }
}

let recycle_policy = MyRecycle;
let q = ThingBuf::with_recycle(100, recycle_policy);
// Further operations on q...
```

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

### Dynamically Allocated Channel Creation (Rust)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/index

Demonstrates creating a dynamically allocated blocking channel where the capacity is determined at runtime from command-line arguments. Requires the 'alloc' feature.

```rust
use thingbuf::mpsc::blocking;
use std::env;

fn main() {
    // Determine the channel capacity from the first command-line line
    // argument, if one is present.
    let channel_capacity = env::args()
        .nth(1)
        .and_then(|cap| cap.parse::<usize>().ok())
        .unwrap_or(16);

    // Construct a dynamically-sized blocking channel.
    let (tx, rx) = blocking::channel(channel_capacity);

    tx.send("hello world").unwrap();

    // ...
}
```

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

### Get maximum capacity

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/recycling/struct

Demonstrates retrieving the maximum retained capacity for recycling elements. If no upper bound is set, it returns usize::MAX.

```rust
use thingbuf::recycling::{Recycle, WithCapacity};

let recycle = WithCapacity::new();
assert_eq!(recycle.max_capacity(), usize::MAX);
```

```rust
use thingbuf::recycling::{Recycle, WithCapacity};

let recycle = WithCapacity::new().with_max_capacity(64);
assert_eq!(recycle.max_capacity(), 64);
```

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

### Optimized String Logging with ThingBuf References (Rust)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Demonstrates an optimized approach using ThingBuf's push_ref and pop_ref to reuse String allocations. This avoids repeated heap allocations by clearing and writing directly into existing String buffers within the queue.

```rust
use thingbuf::ThingBuf;
use std::{sync::Arc, fmt, thread, fs::File, error::Error};

// Called by application threads to log a message.
fn log_event(q: &Arc<ThingBuf<String>>, message: &dyn fmt::Debug) {
    use std::fmt::Write;

    // Reserve a slot in the queue to write to.
    if let Ok(mut slot) = q.push_ref() {
        // Clear the string in place, retaining the allocated capacity.
        slot.clear();
        // Write the log message to the string.
        write!(&mut *slot, "{:?}\n", message);
    }
    // Otherwise, if `push_ref` returns an error, the queue is full;
    // ignore this log line.
}

fn main() -> Result<(), Box<dyn Error>> {
    let log_queue = Arc::new(ThingBuf::<String>::new(1024));

    // Spawn the background worker thread.
    let q = log_queue.clone();
    let mut file = File::create("myapp.log")?;
    thread::spawn(move || {
        use std::io::Write;
        loop {
            // Pop from the queue, and write each log line to the file.
            while let Some(line) = q.pop_ref() {
                file.write_all(line.as_bytes()).unwrap();
            }

            // No more messages in the queue!
            file.flush().unwrap();
            thread::yield_now();
        }
    });

    // ...
    Ok(())
}
```

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

### Constructing a ThingBuf MPSC Channel

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/index

Demonstrates how to create a new MPSC channel with a specified capacity. The function returns a Sender and a Receiver pair.

```Rust
let (tx, rx) = thingbuf::mpsc::channel::<String>(10);
```

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

### ThingBuf Push Operations

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Methods for adding elements to the ThingBuf queue.

```APIDOC
## POST /thingbuf/push_ref

### Description
Reserves a slot to push an element into the queue, returning a `Ref` that can be used to write to that slot. This can be used to reuse allocations for queue elements in place. If values are expensive to produce, `push_ref` can also be used to avoid producing a value if there is no capacity for it in the queue.

### Method
POST

### Endpoint
/thingbuf/push_ref

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (The operation reserves a slot, the actual value is written to the returned `Ref`)

### Response
#### Success Response (200)
- **ref** (Ref<'_, T>) - A reference to the reserved slot, allowing writing of the element.

#### Error Response (400)
- **error** (string) - Indicates that the queue is full (`Full`).

#### Response Example (Success)
```json
{
  "ref": "<ref_data>"
}
```

#### Response Example (Error)
```json
{
  "error": "Full"
}
```
```

```APIDOC
## POST /thingbuf/push

### Description
Attempt to enqueue an element by value. If the queue is full, the element is returned in the `Full` error. This method does not enable the reuse of previously allocated elements.

### Method
POST

### Endpoint
/thingbuf/push

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **value** (T) - The element to enqueue.

### Response
#### Success Response (200)
- **status** (string) - Indicates the element was enqueued successfully (`Ok`).

#### Error Response (400)
- **error** (string) - Indicates the queue is full (`Full`), containing the value.

#### Response Example (Success)
```json
{
  "status": "Ok"
}
```

#### Response Example (Error)
```json
{
  "error": "Full(value)"
}
```
```

```APIDOC
## POST /thingbuf/push_with

### Description
Reserves a slot to push an element into the queue, and invokes the provided function `f` with a mutable reference to that element. The function `f` should return the value `U` to be associated with this push operation.

### Method
POST

### Endpoint
/thingbuf/push_with

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **function** (function) - A function that takes a mutable reference to the element slot and returns a value of type `U`.

### Response
#### Success Response (200)
- **result** (U) - The return value of the provided function `f`.

#### Error Response (400)
- **error** (string) - Indicates that the queue is full (`Full`).

#### Response Example (Success)
```json
{
  "result": "<return_value_of_f>"
}
```

#### Response Example (Error)
```json
{
  "error": "Full"
}
```
```

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

### Add thingbuf to Cargo.toml (No std, Alloc)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/index

Illustrates enabling the 'alloc' feature for #![no_std] projects when a memory allocator is available. This allows the use of queues and asynchronous channels whose sizes are determined at runtime.

```toml
[dependencies]
thingbuf = { version = "0.1", default-features = false, features = ["alloc"] }
```

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

### Using Asynchronous MPSC Channels with Tokio

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/index

Illustrates the usage of asynchronous ThingBuf MPSC channels within an async runtime like Tokio. It shows spawning tasks to send messages and receiving them asynchronously.

```Rust
use thingbuf::mpsc;

#[tokio::main]
async fn main() {
    let (tx, rx) = mpsc::channel(8);

    // Spawn some tasks that write to the channel:
    for i in 0..10 {
        let tx = tx.clone();
        tokio::spawn(async move {
            tx.send(i).await.unwrap();
        });
    }

    // Print out every message recieved from the channel:
    for _ in 0..10 {
        let j = rx.recv().await.unwrap();

        println!("received {}", j);
        assert!(0 <= j && j < 10);
    }
}
```

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

### Thingbuf TrySendError Display Trait Implementation

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/errors/enum

Shows the implementation of the Display trait for TrySendError, enabling formatted output of the error in the thingbuf crate.

```rust
impl<T> Display for TrySendError<T>
Source
#### fn fmt(&self, f: &mut Formatter<'_>) -> Result
```

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

### Naive String Logging with ThingBuf (Rust)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Shows a basic implementation of logging messages to a worker thread using ThingBuf, where new String allocations occur for each log message. This can lead to performance issues due to frequent heap allocations and deallocations.

```rust
use thingbuf::ThingBuf;
use std::{sync::Arc, fmt, thread, fs::File, error::Error, io::Write};

// Called by application threads to log a message.
fn log_event(q: &Arc<ThingBuf<String>>, message: &dyn fmt::Debug) {
    // Format the log line to a `String`.
    let line = format!("{:?}\n", message);
    // Send the string to the worker thread.
    let _ = q.push(line);
    // If the queue was full, ignore the error and drop the log line.
}

fn main() -> Result<(), Box<dyn Error>> {
    let log_queue = Arc::new(ThingBuf::<String>::new(1024));

    // Spawn the background worker thread.
    let q = log_queue.clone();
    let mut file = File::create("myapp.log")?;
    thread::spawn(move || {
        use std::io::Write;
        loop {
            // Pop from the queue, and write each log line to the file.
            while let Some(line) = q.pop() {
                file.write_all(line.as_bytes()).unwrap();
            }

            // No more messages in the queue!
            file.flush().unwrap();
            thread::yield_now();
        }
    });

    // ...
    Ok(())
}
```

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

### Push Element Using a Closure in ThingBuf (Rust)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Demonstrates reserving a slot and then invoking a provided closure to populate the element in the ThingBuf. Returns the closure's result.

```Rust
use thingbuf::ThingBuf;

let q = ThingBuf::new(1);

// Reserve a slot and initialize the element using a closure
let result = q.push_with(|slot| {
    *slot = 100;
    "initialized"
});

match result {
    Ok(msg) => println!("Enqueued and closure returned: {}", msg),
    Err(_) => println!("Queue was full"),
}

// Example of failure when queue is full
let _ = q.push_ref().unwrap(); // Fill the queue
let failed_result = q.push_with(|slot| {
    *slot = 200;
    "this won't be returned"
});

assert!(failed_result.is_err());
```

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

### Thingbuf TrySendError PartialEq Trait Implementation

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/errors/enum

Details the implementation of the PartialEq trait for TrySendError, enabling equality comparisons between error instances in the thingbuf crate.

```rust
impl<T: PartialEq> PartialEq for TrySendError<T>
Source
#### fn eq(&self, other: &TrySendError<T>) -> bool
```

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

### Push Element to ThingBuf Using a Reference (Rust)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Demonstrates reserving a slot in the ThingBuf for an element and writing to it via a `Ref`. This method is useful for reusing allocations in place.

```Rust
use thingbuf::ThingBuf;

let q = ThingBuf::new(1);

// Reserve a `Ref` and enqueue an element.
*q.push_ref().expect("queue should have capacity") = 10;

// Now that the queue has one element in it, a subsequent `push_ref`
// call will fail.
assert!(q.push_ref().is_err());
```

```Rust
use thingbuf::ThingBuf;

#[derive(Clone, Default)]
struct Message {
    // ...
}

fn make_expensive_message() -> Message {
    // Imagine this function performs some costly operation, or acquires
    // a limited resource...
    Message::default()
}

fn enqueue_message(q: &ThingBuf<Message>) {
    loop {
        match q.push_ref() {
            // the queue for our message, so it's okay to generate
            // the expensive message.
            Ok(mut slot) => {
                *slot = make_expensive_message();
                return;
            },

            // If there's no space in the queue, avoid generating
            // an expensive message that won't be sent.
            Err(_) => {
                // Wait until the queue has capacity...
                std::thread::yield_now();
            }
        }
    }
}
```

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

### Cloning to uninitialized memory with CloneToUninit

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/recycling/struct

Demonstrates the experimental nightly-only API clone_to_uninit from the CloneToUninit trait. This allows cloning data directly into uninitialized memory, offering performance benefits.

```rust
impl<T> CloneToUninit for T
where T: Clone
```

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

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

### Create and use WithCapacity with min capacity

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/recycling/struct

Illustrates setting a minimum capacity for new elements created by a recycler. New elements will always be allocated with at least the specified minimum capacity.

```rust
use thingbuf::recycling::{Recycle, WithCapacity};

// A recycler without a minimum capacity.
let no_min = WithCapacity::new();

// A new element created by this recycler will not
// allocate any capacity until it is used.
let s: String = no_min.new_element();
assert_eq!(s.capacity(), 0);

// Now, configure a minimum capacity.
let with_min = WithCapacity::new().with_min_capacity(8);

// New elements created by this recycler will always be allocated
// with at least the specified capacity.
let s: String = with_min.new_element();
assert!(s.capacity() >= 8);
```

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

### Push Element by Value to ThingBuf (Rust)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Shows how to attempt to enqueue an element directly by value into the ThingBuf. If the queue is full, the element is returned in a `Full` error.

```Rust
use thingbuf::ThingBuf;
use thingbuf::Full;

let q = ThingBuf::new(1);

match q.push(10) {
    Ok(_) => println!("Enqueued successfully"),
    Err(Full(val)) => println!("Queue is full, failed to enqueue: {}", val),
}

// Example of failure when queue is full
let _ = q.push_ref().unwrap(); // Fill the queue
match q.push(20) {
    Ok(_) => unreachable!(),
    Err(Full(val)) => {
        assert_eq!(val, 20);
        println!("Queue correctly reported as full");
    },
}
```

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

### Add thingbuf to Cargo.toml (Default)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/index

Specifies how to add the thingbuf crate as a dependency in a Rust project's Cargo.toml file for standard usage.

```toml
[dependencies]
thingbuf = "0.1"
```

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

### Try Send Ref

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/blocking/struct

Attempts to reserve a slot for in-place mutation without blocking. Returns an error if the channel is full or closed.

```APIDOC
## POST /try_send_ref

### Description
Attempts to reserve a slot in the channel for in-place mutation without blocking. This method returns immediately if the channel buffer is full or if no `StaticReceiver` exists. It provides a `SendRef` for mutating the slot; dropping this `SendRef` completes the send.

### Method
POST

### Endpoint
`/try_send_ref`

### Parameters
No parameters required.

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **SendRef<T>** - A mutable reference to a reserved slot in the channel, allowing in-place modification.

#### Response Example
```json
{
  "message": "slot reserved for mutation"
}
```

##### Errors
- `Err(TrySendError::Full)`: If the channel's buffer capacity is currently reached.
- `Err(TrySendError::Closed)`: If the receiving half of the channel has been dropped.
```

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

### Push Reference (Allocation Reuse)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/struct

Reserves a slot in the queue for in-place mutation, allowing for allocation reuse.

```APIDOC
## POST /push_ref

### Description
Reserves a slot in the queue to write to, allowing the caller to mutate a slot in place, returning a `Ref`. This method is useful for reusing existing allocations, such as `String`s.

### Method
POST

### Endpoint
/push_ref

### Parameters
#### Request Body
- **element** (T) - The element to be placed in the queue. This will be cleared and potentially overwritten if the slot is reused.

### Request Example
```json
{
  "element": "Initial Log Message"
}
```

### Response
#### Success Response (200)
- **Ref<T>** (Ref) - A mutable reference to a slot in the queue that can be written to.

#### Response Example
```json
{
  "slot_ref": "<mutable reference to slot>"
}
```

### Error Handling
- **Err(TryReserveError)**: Returned if the queue is full and no slots are available.

### Usage Example
```rust
use thingbuf::ThingBuf;
use std::fmt::Write;

// Called by application threads to log a message.
fn log_event(q: &ThingBuf<String>, message: &dyn std::fmt::Debug) {
    // Reserve a slot in the queue to write to.
    if let Ok(mut slot) = q.push_ref() {
        // Clear the string in place, retaining the allocated capacity.
        slot.clear();
        // Write the log message to the string.
        write!(&mut *slot, "{:?}\n", message).unwrap();
    }
    // Otherwise, if `push_ref` returns an error, the queue is full;
    // ignore this log line.
}

let log_queue = ThingBuf::<String>::new(1024);
log_event(&log_queue, &"Hello, World!");
```
```

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

### StaticSender - send_ref

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/struct

Reserves a slot in the channel to mutate in place, waiting until there is a free slot to write to. Allows for in-place mutation of channel slots, enabling allocation reuse when used with `StaticReceiver::recv_ref`.

```APIDOC
## POST /websites/rs_thingbuf_0_1_6_thingbuf/mpsc/StaticSender/send_ref

### Description
Reserves a slot in the channel to mutate in place, waiting until there is a free slot to write to. This method allows for in-place mutation of channel slots, enabling allocation reuse when used with `StaticReceiver::recv_ref`.

### Method
POST

### Endpoint
`/websites/rs_thingbuf_0_1_6_thingbuf/mpsc/StaticSender/send_ref`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **SendRef<'_, T>** - A reference that allows mutating the slot in place.

#### Response Example
```json
{
  "message": "Slot reserved successfully"
}
```

### Errors
- **Closed**: Returned if the `StaticReceiver` end of the channel has been dropped.
```

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

### Create Synchronous MPSC Channel with Recycling (Rust)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/blocking/index

Creates a new synchronous MPSC channel with a specific recycling policy. This allows for efficient reuse of channel components.

```Rust
pub fn with_recycle<T, F>(capacity: usize, recycle: F) -> (Sender<T>, Receiver<T>)
```

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

### Create MPSC Channel with Recycle (Rust)

Source: https://docs.rs/thingbuf/0.1.6/thingbuf/mpsc/fn

Creates a new asynchronous multi-producer, single-consumer (MPSC) channel with a specified capacity and recycling policy. This function is available only when the `alloc` crate feature is enabled. It may panic if the provided capacity exceeds a certain limit.

```rust
pub fn with_recycle<T, R: Recycle<T>>(
    capacity: usize,
    recycle: R,
) -> (Sender<T, R>, Receiver<T, R>)

```
Tokens:
Raw