Futures

https://docs.rs/futures/latest/
Admin
The futures crate provides core abstractions for asynchronous programming in Rust, including...
Tokens:1,756,233
Snippets:13,476
Trust Score:9.7
Update:3 hours ago
Show doc for...
Tokens:
Raw
### always_ready usage example

Source: https://docs.rs/futures/latest/futures/future/fn.always_ready.html

Example showing how to use always_ready to create a future that is immediately ready with a value. The example checks that the future has zero size and can be awaited multiple times.

```rust
use std::mem::size_of_val;

use futures::future;

let a = future::always_ready(|| 1);
assert_eq!(size_of_val(&a), 0);
assert_eq!(a.await, 1);
assert_eq!(a.await, 1);

```

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

### Usage Example for compat() Method

Source: https://docs.rs/futures/latest/futures/compat/trait.AsyncRead01CompatExt.html

Converts a tokio-io AsyncRead into a futures-io 0.3 AsyncRead. The example reads from a Cursor and asserts the output matches the input.

```rust
use futures::io::AsyncReadExt;
use futures_util::compat::AsyncRead01CompatExt;

let input = b"Hello World!";
let reader /* : impl tokio_io::AsyncRead */ = std::io::Cursor::new(input);
let mut reader /* : impl futures::io::AsyncRead + Unpin */ = reader.compat();

let mut output = Vec::with_capacity(12);
reader.read_to_end(&mut output).await.unwrap();
assert_eq!(output, input);
```

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

### OptionFuture usage example

Source: https://docs.rs/futures/latest/futures/future/struct.OptionFuture.html

Shows how to create an OptionFuture from an Option using the From implementation and await it. The example demonstrates that awaiting Some yields the inner value, and awaiting None yields None.

```rust
use futures::future::OptionFuture;

let mut a: OptionFuture<_> = Some(async { 123 }).into();
assert_eq!(a.await, Some(123));

a = None.into();
assert_eq!(a.await, None);
```

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

### limit() Example

Source: https://docs.rs/futures/latest/futures/io/struct.Take.html

Example for the `limit` method, showing how to read from a `Take` instance and check the remaining limit. Uses `futures::io::{AsyncReadExt, Cursor}`.

```rust
use futures::io::{AsyncReadExt, Cursor};

let reader = Cursor::new(&b"12345678"[..]);
let mut buffer = [0; 2];

let mut take = reader.take(4);
let n = take.read(&mut buffer).await?;

assert_eq!(take.limit(), 2);
```

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

### Using noop_waker in an example

Source: https://docs.rs/futures/latest/futures/task/fn.noop_waker.html

Example usage: imports noop_waker, creates a waker, and calls wake() on it.

```rust
use futures::task::noop_waker;
let waker = noop_waker();
waker.wake();
```

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

### set_limit() Example

Source: https://docs.rs/futures/latest/futures/io/struct.Take.html

Example for the `set_limit` method, showing how to change the limit after reading. Uses `futures::io::{AsyncReadExt, Cursor}`.

```rust
use futures::io::{AsyncReadExt, Cursor};

let reader = Cursor::new(&b"12345678"[..]);
let mut buffer = [0; 4];

let mut take = reader.take(4);
let n = take.read(&mut buffer).await?;

assert_eq!(n, 4);
assert_eq!(take.limit(), 0);

take.set_limit(10);
let n = take.read(&mut buffer).await?;
assert_eq!(n, 4);
```

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

### select Usage Example with repeat Streams

Source: https://docs.rs/futures/latest/futures/prelude/self/fn.select.html

Example showing how to use select with two repeat streams. The output alternates between items from each stream, as verified by the assertions. Requires the futures crate and an async runtime for await.

```rust
use futures::stream::{ repeat, select, StreamExt };

let left = repeat(1);
let right = repeat(2);

let mut out = select(left, right);

for _ in 0..100 {
    // We should be alternating.
    assert_eq!(1, out.select_next_some().await);
    assert_eq!(2, out.select_next_some().await);
}

```

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

### Example: into_inner

Source: https://docs.rs/futures/latest/futures/lock/struct.Mutex.html

Shows how to create a Mutex and consume it to get the inner value.

```rust
use futures::lock::Mutex;

let mutex = Mutex::new(0);
assert_eq!(mutex.into_inner(), 0);
```

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

### Rust async task system example using futures::channel::mpsc and ThreadPool

Source: https://docs.rs/futures/latest/src/futures/lib.rs.html

Shows how to build and run an async task system: create a ThreadPool, an unbounded mpsc channel, spawn a sender future, collect doubled values, and block on the result. The example is from the crate-level documentation and assumes execution inside an async block. It prints the collected values after a short sleep to allow background threads to close.

```rust
# use futures::channel::mpsc;
# use futures::executor; ///standard executors to provide a context for futures and streams
# use futures::executor::ThreadPool;
# use futures::StreamExt;
#
fn main() {
    # {
    let pool = ThreadPool::new().expect("Failed to build pool");
    let (tx, rx) = mpsc::unbounded::<i32>();

    // Create a future by an async block, where async is responsible for an
    // implementation of Future. At this point no executor has been provided
    // to this future, so it will not be running.
    let fut_values = async {
        // Create another async block, again where the Future implementation
        // is generated by async. Since this is inside of a parent async block,
        // it will be provided with the executor of the parent block when the parent
        // block is executed.
        //
        // This executor chaining is done by Future::poll whose second argument
        // is a std::task::Context. This represents our executor, and the Future
        // implemented by this async block can be polled using the parent async
        // block's executor.
        let fut_tx_result = async move {
            (0..100).for_each(|v| {
                tx.unbounded_send(v).expect("Failed to send");
            })
        };

        // Use the provided thread pool to spawn the generated future
        // responsible for transmission
        pool.spawn_ok(fut_tx_result);

        let fut_values = rx
            .map(|v| v * 2)
            .collect();

        // Use the executor provided to this async block to wait for the
        // future to complete.
        fut_values.await
    };

    // Actually execute the above future, which will invoke Future::poll and
    // subsequently chain appropriate Future::poll and methods needing executors
    // to drive all futures. Eventually fut_values will be driven to completion.
    let values: Vec<i32> = executor::block_on(fut_values);

    println!("Values={:?}", values);
    # }
    # std::thread::sleep(std::time::Duration::from_millis(500)); // wait for background threads closed: https://github.com/rust-lang/miri/issues/1371
}
```

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

### Example: Using future::ok to create an immediately ready future

Source: https://docs.rs/futures/latest/futures/future/fn.ok.html

Creates a future that is immediately ready with a success value. The example uses `future::ok::<i32, i32>(1)` and awaits it, asserting the result is `Ok(1)`.

```rust
use futures::future;

let a = future::ok::<i32, i32>(1);
assert_eq!(a.await, Ok(1));
```

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

### Example: Using future::ready to create an immediately ready future

Source: https://docs.rs/futures/latest/futures/future/fn.ready.html

Example usage of `futures::future::ready`. It creates a future that is immediately ready with the value `1` and awaits it, asserting the result equals `1`.

```rust
use futures::future;

let a = future::ready(1);
assert_eq!(a.await, 1);
```

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

### Example: Using future::err

Source: https://docs.rs/futures/latest/futures/future/fn.err.html

Example showing how to create a future that resolves to an error using `future::err` and await it.

```rust
use futures::future;

let a = future::err::<i32, i32>(1);
assert_eq!(a.await, Err(1));
```

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

### into_future example

Source: https://docs.rs/futures/latest/futures/future/trait.TryFutureExt.html

Demonstrates converting a `TryFuture` into a `Future` using `into_future`. The example shows a `make_try_future` function and a `take_future` function that accepts a `Future`.

```rust
use futures::future::{Future, TryFuture, TryFutureExt};

fn make_try_future() -> impl TryFuture<Ok = T, Error = E> { // ... }
fn take_future(future: impl Future<Output = Result<T, E>>) { /* ... */ }

take_future(make_try_future().into_future());
```

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

### Example: take_result usage

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.TakeUntil.html

Example showing how to use take_until and take_result to retrieve the stopping future's output after the stream stops.

```rust
use futures::future;
use futures::stream::{self, StreamExt};
use futures::task::Poll;

let stream = stream::iter(1..=10);

let mut i = 0;
let stop_fut = future::poll_fn(|_cx| {
    i += 1;
    if i <= 5 {
        Poll::Pending
    } else {
        Poll::Ready("reason")
    }
});

let mut stream = stream.take_until(stop_fut);
let _ = stream.by_ref().collect::<Vec<_>>().await;

let result = stream.take_result().unwrap();
assert_eq!(result, "reason");
```

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

### Example usage of try_join_all with success and error cases

Source: https://docs.rs/futures/latest/futures/future/fn.try_join_all.html

Shows how to use try_join_all with a vector of futures. The first example collects successful results into a Vec, while the second demonstrates that an error cancels all other futures and returns the error immediately.

```rust
use futures::future::{self, try_join_all};

let futures = vec![
    future::ok::<u32, u32>(1),
    future::ok::<u32, u32>(2),
    future::ok::<u32, u32>(3),
];

assert_eq!(try_join_all(futures).await, Ok(vec![1, 2, 3]));

let futures = vec![
    future::ok::<u32, u32>(1),
    future::err::<u32, u32>(2),
    future::ok::<u32, u32>(3),
];

assert_eq!(try_join_all(futures).await, Err(2));
```

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

### Example: Creating a stream of a single element

Source: https://docs.rs/futures/latest/futures/prelude/self/fn.once.html

Shows how to use `stream::once` to create a stream that yields a single value from an async block. The example collects the stream into a vector and asserts it equals `vec![17]`.

```rust
use futures::stream::{self, StreamExt};

let stream = stream::once(async { 17 });
let collected = stream.collect::<Vec<i32>>().await;
assert_eq!(collected, vec![17]);
```

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

### compat example: Wrapping a TryStream for futures 0.1 compatibility

Source: https://docs.rs/futures/latest/futures/prelude/self/trait.TryStreamExt.html

Shows how to use the compat method to wrap a TryStream into a stream compatible with futures 0.1. Requires the `compat` feature to be enabled. The example converts a future03 to a future01 using unit_error, boxed, and compat, then runs it with tokio::run.

```rust
use futures::future::{FutureExt, TryFutureExt};

let future03 = async {
    println!("Running on the pool");
    tx.send(42).unwrap();
};

let future01 = future03
    .unit_error() // Make it a TryFuture
    .boxed()  // Make it Unpin
    .compat();

tokio::run(future01);
```

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

### take() example: limiting reads to a maximum number of bytes

Source: https://docs.rs/futures/latest/futures/io/trait.AsyncReadExt.html

Creates a `Take` adapter that reads at most `limit` bytes from the underlying reader. The example reads 4 bytes from a cursor and verifies the buffer contents.

```rust
use futures::io::{AsyncReadExt, Cursor};

let reader = Cursor::new(&b"12345678"[..]);
let mut buffer = [0; 5];

let mut take = reader.take(4);
let n = take.read(&mut buffer).await?;

assert_eq!(n, 4);
assert_eq!(&buffer, b"1234\0");
```

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

### join_all usage example

Source: https://docs.rs/futures/latest/futures/future/fn.join_all.html

Example showing how to use join_all to await a vector of futures and collect their results into a Vec. The returned future drives all underlying futures and collects results in the same order as provided.

```rust
use futures::future::join_all;

async fn foo(i: u32) -> u32 { i }

let futures = vec![foo(1), foo(2), foo(3)];

assert_eq!(join_all(futures).await, [1, 2, 3]);
```

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

### compat

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.Take.html

Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled.

```APIDOC
## compat

### Description
Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled.

### Method
fn compat(self) -> Compat<Self>

### Constraints
- Self: Sized + Unpin

### Availability
Available on crate feature `compat` only.
```

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

### Example: get_mut

Source: https://docs.rs/futures/latest/futures/lock/struct.Mutex.html

Shows how to get a mutable reference to the underlying data without locking.

```rust
use futures::lock::Mutex;

let mut mutex = Mutex::new(0);
*mutex.get_mut() = 10;
assert_eq!(*mutex.lock().await, 10);
```

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

### Cursor::get_ref example

Source: https://docs.rs/futures/latest/futures/io/struct.Cursor.html

Gets an immutable reference to the underlying value in the cursor.

```rust
use futures::io::Cursor;

let buff = Cursor::new(Vec::new());

let reference = buff.get_ref();
```

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

### peek_mut example: modify next item

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.Peekable.html

Shows how to use `peek_mut` to get a mutable reference to the next item and modify it before it is consumed. The example creates a peekable stream, peeks and modifies the value 2 to 5, then collects the stream to verify the result.

```rust
use core::pin::pin;

use futures::stream;
use futures::stream::StreamExt;

let stream = stream::iter(vec![1, 2, 3]).peekable();
let mut stream = pin!(stream);

assert_eq!(stream.as_mut().peek_mut().await, Some(&mut 1));
assert_eq!(stream.as_mut().next().await, Some(1));

// Peek into the stream and modify the value which will be returned next
if let Some(p) = stream.as_mut().peek_mut().await {
    if *p == 2 {
        *p = 5;
    }
}

assert_eq!(stream.collect::<Vec<_>>().await, vec![5, 3]);
```

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

### Example: Using noop_waker_ref

Source: https://docs.rs/futures/latest/futures/task/fn.noop_waker_ref.html

Shows how to get a static no-op waker reference and call wake_by_ref() on it. The waker does nothing when woken.

```rust
use futures::task::noop_waker_ref;
let waker = noop_waker_ref();
waker.wake_by_ref();
```

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

### Cursor::get_mut example

Source: https://docs.rs/futures/latest/futures/io/struct.Cursor.html

Gets a mutable reference to the underlying value. Avoid modifying the internal I/O state as it may corrupt the cursor's position.

```rust
use futures::io::Cursor;

let mut buff = Cursor::new(Vec::new());

let reference = buff.get_mut();
```

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

### now_or_never example with ready and pending futures

Source: https://docs.rs/futures/latest/futures/future/trait.FutureExt.html

Shows how to use now_or_never() to get the output of a future if it is ready, or None if it is pending. Uses futures::future::ready and futures::future::pending.

```rust
use futures::{future::ready, future::pending};
let future_ready = ready("foobar");
let future_pending = pending::<&'static str>();

assert_eq!(future_ready.now_or_never(), Some("foobar"));
assert_eq!(future_pending.now_or_never(), None);
```

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

### StreamExt::next - Get next item from stream

Source: https://docs.rs/futures/latest/futures/prelude/self/trait.StreamExt.html

Creates a future that resolves to the next item in the stream. Requires the stream to be Unpin; for !Unpin streams, pin it first using Box::pin or pin_mut!. The example iterates over 1..=3 and asserts each next() result, ending with None.

```rust
use futures::stream::{self, StreamExt};

let mut stream = stream::iter(1..=3);

assert_eq!(stream.next().await, Some(1));
assert_eq!(stream.next().await, Some(2));
assert_eq!(stream.next().await, Some(3));
assert_eq!(stream.next().await, None);
```

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

### Example: Using try_unfold to create a stream

Source: https://docs.rs/futures/latest/futures/prelude/self/fn.try_unfold.html

Demonstrates creating a TryStream with try_unfold, starting from seed 0 and yielding values until state exceeds 2. The closure returns an error for negative states and stops with Ok(None) when done. The stream is collected into a Vec<i32> and asserted to equal [0, 2, 4].

```rust
use futures::stream::{self, TryStreamExt};

let stream = stream::try_unfold(0, |state| async move {
    if state < 0 {
        return Err(SomeError);
    }

    if state <= 2 {
        let next_state = state + 1;
        let yielded = state * 2;
        Ok(Some((yielded, next_state)))
    } else {
        Ok(None)
    }
});

let result: Result<Vec<i32>, _> = stream.try_collect().await;
assert_eq!(result, Ok(vec![0, 2, 4]));
```

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

### compat(self) -> Compat<Self>

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.Empty.html

Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the 'compat' feature to be enabled.

```APIDOC
## compat(self) -> Compat<Self>

### Description
Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`.

### Method
Function call

### Signature
```rust
fn compat(self) -> Compat<Self>
where
    Self: Sized + Unpin,
```

### Availability
- Crate feature `compat` only.

### Returns
- **Compat<Self>** - A stream compatible with futures 0.1.
```

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

### try_join5 usage example

Source: https://docs.rs/futures/latest/futures/future/fn.try_join5.html

Example of using try_join5 with five ready futures that all succeed, producing a tuple of results. The example asserts that awaiting the combined future yields Ok((1, 2, 3, 4, 5)).

```rust
use futures::future;

let a = future::ready(Ok::<i32, i32>(1));
let b = future::ready(Ok::<i32, i32>(2));
let c = future::ready(Ok::<i32, i32>(3));
let d = future::ready(Ok::<i32, i32>(4));
let e = future::ready(Ok::<i32, i32>(5));
let tuple = future::try_join5(a, b, c, d, e);

assert_eq!(tuple.await, Ok((1, 2, 3, 4, 5)));
```

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

### take

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.SelectWithStrategy.html

Creates a new stream of at most `n` items of the underlying stream.

```APIDOC
## take

### Description
Creates a new stream of at most `n` items of the underlying stream.

### Method
take

### Signature
fn take(self, n: usize) -> Take<Self>
where Self: Sized

### Parameters
- **n** (usize) - Required - The maximum number of items to take.

### Returns
- **Take<Self>** - A stream that yields at most `n` items.
```

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

### take(self, n: usize) -> Take<Self>

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.Select.html

Creates a new stream of at most n items of the underlying stream.

```APIDOC
## take(self, n: usize) -> Take<Self>

### Description
Creates a new stream of at most `n` items of the underlying stream.

### Method
take

### Signature
```rust
fn take(self, n: usize) -> Take<Self>
where
    Self: Sized,
```

### Parameters
- **n** (usize) - Required - Maximum number of items to take.

### Returns
- **Take<Self>** - A stream that yields at most `n` items.
```

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

### compat

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.Ready.html

Wraps a TryFuture into a future compatible with libraries using futures 0.1 future definitions. Requires the compat feature to enable.

```APIDOC
## compat

### Description
Wraps a `TryFuture` into a future compatible with libraries using futures 0.1 future definitions. Requires the `compat` feature to enable.

### Method
`fn compat(self) -> Compat<Self>`

### Constraints
- `Self: Sized + Unpin`
- Available on **crate feature `compat`** only.

### Returns
- `Compat<Self>` - A future compatible with futures 0.1.
```

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

### try_join3 usage example

Source: https://docs.rs/futures/latest/futures/future/fn.try_join3.html

Example of using try_join3 with three ready futures, awaiting the tuple result.

```rust
use futures::future;

let a = future::ready(Ok::<i32, i32>(1));
let b = future::ready(Ok::<i32, i32>(2));
let c = future::ready(Ok::<i32, i32>(3));
let tuple = future::try_join3(a, b, c);

assert_eq!(tuple.await, Ok((1, 2, 3)));
```

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

### compat(self) -> Compat<Self>

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.Select.html

Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. This method requires the `compat` feature to be enabled.

```APIDOC
## compat(self) -> Compat<Self>

### Description
Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. This method requires the `compat` feature to be enabled.

### Method
Function

### Signature
```rust
fn compat(self) -> Compat<Self>
where
    Self: Sized + Unpin,
```

### Availability
- crate feature `compat`

### Returns
- `Compat<Self>` - A stream compatible with futures 0.1.
```

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

### join5 usage example

Source: https://docs.rs/futures/latest/futures/future/fn.join5.html

Example of using future::join5 to await five async blocks and assert the resulting tuple. The example creates five async futures and joins them, expecting the tuple (1, 2, 3, 4, 5).

```rust
use futures::future;

let a = async { 1 };
let b = async { 2 };
let c = async { 3 };
let d = async { 4 };
let e = async { 5 };
let tuple = future::join5(a, b, c, d, e);

assert_eq!(tuple.await, (1, 2, 3, 4, 5));
```

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

### Cursor::set_position example

Source: https://docs.rs/futures/latest/futures/io/struct.Cursor.html

Sets the position of the cursor directly. The example asserts the position after setting it to 2 and then to 4.

```rust
use futures::io::Cursor;

let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]);

assert_eq!(buff.position(), 0);

buff.set_position(2);
assert_eq!(buff.position(), 2);

buff.set_position(4);
assert_eq!(buff.position(), 4);
```

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

### into_async_read

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.Take.html

Adapter that converts this stream into an `AsyncBufRead`.

```APIDOC
## into_async_read

### Description
Adapter that converts this stream into an `AsyncBufRead`.

### Method
fn into_async_read(self) -> IntoAsyncRead<Self>

### Constraints
- Self: Sized + TryStreamExt<Error = Error>
- Self::Ok: AsRef<[u8]>

### Availability
Available on crate features `io` and `std` only.
```

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

### compat

Source: https://docs.rs/futures/latest/futures/io/struct.WriteAll.html

Wraps a `TryFuture` into a future compatible with libraries using futures 0.1 future definitions. Requires the `compat` feature to enable.

```APIDOC
## compat

### Description
Wraps a `TryFuture` into a future compatible with libraries using futures 0.1 future definitions. Requires the `compat` feature to enable.

### Method
fn compat(self) -> Compat<Self>

### Constraints
- `Self: Sized + Unpin`

### Returns
- `Compat<Self>` - The compatible future.
```

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

### TryFutureExt::compat

Source: https://docs.rs/futures/latest/futures/future/struct.AndThen.html

Wraps a `TryFuture` into a future compatible with libraries using futures 0.1 future definitions. Requires the `compat` feature to enable.

```APIDOC
## [METHOD] compat

### Description
Wraps a `TryFuture` into a future compatible with libraries using futures 0.1 future definitions. Requires the `compat` feature to enable.

### Method
compat

### Return Value
Returns a `Compat` future that implements the futures 0.1 `Future` trait.
```

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

### take

Source: https://docs.rs/futures/latest/futures/io/struct.AllowStdIo.html

Creates an adapter which will read at most `limit` bytes from it.

```APIDOC
## take

### Description
Creates an adapter which will read at most `limit` bytes from it.

### Method
take

### Parameters
- `limit` (`u64`) - Required - The maximum number of bytes to read.

### Returns
- `Take<Self>` - The adapter.
```

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

### join4 Usage Example

Source: https://docs.rs/futures/latest/futures/future/fn.join4.html

Example of using future::join4 to await four async blocks and assert the resulting tuple. The example creates four async blocks returning 1, 2, 3, and 4, then joins them and asserts the tuple equals (1, 2, 3, 4).

```rust
use futures::future;

let a = async { 1 };
let b = async { 2 };
let c = async { 3 };
let d = async { 4 };
let tuple = future::join4(a, b, c, d);

assert_eq!(tuple.await, (1, 2, 3, 4));
```

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

### inspect

Source: https://docs.rs/futures/latest/futures/stream/select_all/struct.SelectAll.html

Do something with each item of this stream, afterwards passing it on.

```APIDOC
## inspect

### Description
Do something with each item of this stream, afterwards passing it on.

### Method
inspect

### Signature
fn inspect<F>(self, f: F) -> Inspect<Self, F>

### Parameters
- **f** (F) - Required - A closure that takes a reference to each item.

### Return
Inspect<Self, F>
```

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

### Example: copying bytes with copy_buf

Source: https://docs.rs/futures/latest/futures/io/fn.copy_buf.html

Example usage of io::copy_buf to copy all bytes from a Cursor reader to a Cursor writer. The future completes when the reader hits EOF and all bytes are written and flushed. On success, the number of bytes copied is returned. The example asserts the byte count and final writer contents.

```rust
use futures::io::{self, AsyncWriteExt, Cursor};

let reader = Cursor::new([1, 2, 3, 4]);
let mut writer = Cursor::new(vec![0u8; 5]);

let bytes = io::copy_buf(reader, &mut writer).await?;
writer.close().await?;

assert_eq!(bytes, 4);
assert_eq!(writer.into_inner(), [1, 2, 3, 4, 0]);
```

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

### compat

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.BufferUnordered.html

Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled.

```APIDOC
## compat

### Description
Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled.

### Availability
Available on crate feature `compat` only.

### Method
fn compat(self) -> Compat<Self>

### Type Constraints
- Self: Sized + Unpin

### Returns
Compat<Self>
```

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

### compat(self) -> Compat<Self>

Source: https://docs.rs/futures/latest/futures/future/struct.Ready.html

Wraps a `TryFuture` into a future compatible with libraries using futures 0.1 future definitions. Requires the `compat` feature to enable.

```APIDOC
## compat(self) -> Compat<Self>

### Description
Wraps a `TryFuture` into a future compatible with libraries using futures 0.1 future definitions. Requires the `compat` feature to enable.

### Method
compat

### Signature
fn compat(self) -> Compat<Self>
where Self: Sized + Unpin,

### Availability
crate feature `compat` only.
```

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

### MappedMutexGuard::map example

Source: https://docs.rs/futures/latest/futures/lock/struct.MappedMutexGuard.html

Shows how to map a MappedMutexGuard to a subfield. The example locks a Mutex<Option<String>>, maps to the inner String, then maps to a substring, and asserts the value.

```rust
use futures::lock::{MappedMutexGuard, Mutex, MutexGuard};

let data = Mutex::new(Some("value".to_string()));
{
    let locked_str = MutexGuard::map(data.lock().await, |opt| opt.as_mut().unwrap());
    let locked_char = MappedMutexGuard::map(locked_str, |s| s.get_mut(0..1).unwrap());
    assert_eq!(&*locked_char, "v");
}
```

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

### compat

Source: https://docs.rs/futures/latest/futures/prelude/self/futures_unordered/struct.FuturesUnordered.html

Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled.

```APIDOC
## compat

### Description
Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`.

### Method
fn

### Signature
fn compat(self) -> Compat<Self>

### Constraints
- Self: Sized + Unpin

### Availability
- crate feature `compat` only.
```

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

### compat

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.Then.html

Wraps a TryStream into a stream compatible with libraries using futures 0.1 Stream. Requires the compat feature to be enabled.

```APIDOC
## compat

### Description
Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled.

### Method
fn compat(self) -> Compat<Self>

### Type Constraints
- Self: Sized + Unpin

### Availability
Available on crate feature `compat` only.

### Returns
Compat<Self>
```

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

### try_flatten_stream example

Source: https://docs.rs/futures/latest/futures/future/trait.TryFutureExt.html

Flattens a future that resolves to a stream into a single stream. Useful when stream initialization is deferred. The example collects the stream items into a Vec and asserts the result.

```rust
use futures::future::TryFutureExt;
use futures::stream::{self, TryStreamExt};

let stream_items = vec![17, 18, 19].into_iter().map(Ok);
let future_of_a_stream = async { Ok::<_, ()>(stream::iter(stream_items)) };

let stream = future_of_a_stream.try_flatten_stream();
let list = stream.try_collect::<Vec<_>>().await;
assert_eq!(list, Ok(vec![17, 18, 19]));
```

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

### join3 usage example

Source: https://docs.rs/futures/latest/futures/future/fn.join3.html

Example of using join3 with three async blocks. The resulting tuple is awaited and asserted to equal (1, 2, 3).

```rust
use futures::future;

let a = async { 1 };
let b = async { 2 };
let c = async { 3 };
let tuple = future::join3(a, b, c);

assert_eq!(tuple.await, (1, 2, 3));
```

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

### inspect

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.WithFlatMap.html

Do something with each item of this stream, afterwards passing it on.

```APIDOC
## inspect

### Description
Do something with each item of this stream, afterwards passing it on.

### Method
fn inspect<F>(self, f: F) -> Inspect<Self, F>

### Parameters
- `f` (F) - Required - The closure to call with each item.

### Constraints
- `F: FnMut(&Self::Item)`
- `Self: Sized`

### Returns
- `Inspect<Self, F>` - A stream that yields the same items after calling `f` on each.
```

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

### MutexGuard::map example

Source: https://docs.rs/futures/latest/futures/lock/struct.MutexGuard.html

Returns a locked view over a portion of the locked data. The example locks a `Mutex<Option<String>>` and maps the guard to the inner `String` value.

```rust
use futures::lock::{Mutex, MutexGuard};

let data = Mutex::new(Some("value".to_string()));
{
    let locked_str = MutexGuard::map(data.lock().await, |opt| opt.as_mut().unwrap());
    assert_eq!(&*locked_str, "value");
}
```

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

### TryFutureExt::compat

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.Send.html

Wraps a `TryFuture` into a future compatible with libraries using futures 0.1 future definitions. Requires the `compat` feature to enable.

```APIDOC
## [METHOD] compat

### Description
Wraps a `TryFuture` into a future compatible with libraries using futures 0.1 future definitions. Requires the `compat` feature to enable.

### Method
compat

### Signature
fn compat(self) -> Compat<Self>
where Self: Sized + Unpin,

### Feature
Requires the `compat` feature.

### Return Type
Compat<Self>
```

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

### Flag example using AtomicWaker

Source: https://docs.rs/futures/latest/futures/task/struct.AtomicWaker.html

A complete example showing a Flag future that can be signalled manually. It uses AtomicWaker to coordinate wakeups and demonstrates the register-before-check pattern to avoid lost notifications.

```rust
use futures::future::Future;
use futures::task::{Context, Poll, AtomicWaker};
use std::sync::Arc;
use std::sync::atomic::AtomicBool;
use std::sync::atomic::Ordering::Relaxed;
use std::pin::Pin;

struct Inner {
    waker: AtomicWaker,
    set: AtomicBool,
}

#[derive(Clone)]
struct Flag(Arc<Inner>);

impl Flag {
    pub fn new() -> Self {
        Self(Arc::new(Inner {
            waker: AtomicWaker::new(),
            set: AtomicBool::new(false),
        }))
    }

    pub fn signal(&self) {
        self.0.set.store(true, Relaxed);
        self.0.waker.wake();
    }
}

impl Future for Flag {
    type Output = ();

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
        // quick check to avoid registration if already done.
        if self.0.set.load(Relaxed) {
            return Poll::Ready(());
        }

        self.0.waker.register(cx.waker());

        // Need to check condition **after** `register` to avoid a race
        // condition that would result in lost notifications.
        if self.0.set.load(Relaxed) {
            Poll::Ready(())
        } else {
            Poll::Pending
        }
    }
}
```

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

### into_async_read example: Converting a stream into an AsyncBufRead

Source: https://docs.rs/futures/latest/futures/prelude/self/trait.TryStreamExt.html

Demonstrates how to use into_async_read to convert a stream of byte vectors into an AsyncBufRead. The example reads all bytes into a Vec and asserts the result.

```rust
use futures::stream::{self, TryStreamExt};
use futures::io::AsyncReadExt;

let stream = stream::iter([Ok(vec![1, 2, 3]), Ok(vec![4, 5])]);
let mut reader = stream.into_async_read();

let mut buf = Vec::new();
reader.read_to_end(&mut buf).await.unwrap();
assert_eq!(buf, [1, 2, 3, 4, 5]);
```

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

### boxed

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.SelectWithStrategy.html

Wrap the stream in a Box, pinning it.

```APIDOC
## boxed

### Description
Wrap the stream in a Box, pinning it.

### Method
boxed

### Signature
fn boxed<'a>(self) -> Pin<Box<dyn Stream<Item = Self::Item> + Send + 'a>>
where Self: Sized + Send + 'a

### Returns
- **Pin<Box<dyn Stream<Item = Self::Item> + Send + 'a>>** - A pinned boxed stream that is Send.
```

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

### compat(self) -> Compat<Self>

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.Repeat.html

Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled.

```APIDOC
## compat(self) -> Compat<Self>

### Description
Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled.

### Method
Function

### Signature
`fn compat(self) -> Compat<Self>`

### Parameters
- `self` - The stream to wrap.

### Return Value
- `Compat<Self>` - A stream compatible with futures 0.1.

### Availability
- Crate feature `compat`
```

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

### Example: Not reading anything into a buffer

Source: https://docs.rs/futures/latest/futures/io/fn.empty.html

A slightly sad example of not reading anything into a buffer. Uses io::empty() and AsyncReadExt to read to a string, asserting the buffer is empty.

```rust
use futures::io::{self, AsyncReadExt};

let mut buffer = String::new();
let mut reader = io::empty();
reader.read_to_string(&mut buffer).await?;
assert!(buffer.is_empty());
```

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

### Example usage of stream::unfold

Source: https://docs.rs/futures/latest/futures/prelude/self/fn.unfold.html

Example demonstrating unfold with an async closure that yields values until state exceeds 2. The stream produces [0, 2, 4] and then stops.

```rust
use futures::stream::{self, StreamExt};

let stream = stream::unfold(0, |state| async move {
    if state <= 2 {
        let next_state = state + 1;
        let yielded = state * 2;
        Some((yielded, next_state))
    } else {
        None
    }
});

let result = stream.collect::<Vec<i32>>().await;
assert_eq!(result, vec![0, 2, 4]);
```

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

### compat

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.Skip.html

Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled. Available on crate feature `compat` only.

```APIDOC
## compat

### Description
Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled.

### Method
fn compat(self) -> Compat<Self>

### Constraints
- Self: Sized + Unpin

### Availability
- crate feature `compat` only.
```

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

### take

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.WithFlatMap.html

Creates a new stream of at most `n` items of the underlying stream.

```APIDOC
## take

### Description
Creates a new stream of at most `n` items of the underlying stream.

### Method
fn take(self, n: usize) -> Take<Self>

### Parameters
- `n` (usize) - Required - The maximum number of items to take.

### Constraints
- `Self: Sized`

### Returns
- `Take<Self>` - A new stream that yields at most `n` items.
```

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

### Example usage of futures::sink::unfold

Source: https://docs.rs/futures/latest/futures/sink/fn.unfold.html

Example demonstrating how to create a sink with unfold, pin it, and send a value. The function accumulates a sum and prints each item. Requires the 'sink' feature.

```rust
use core::pin::pin;

use futures::sink;
use futures::sink::SinkExt;

let unfold = sink::unfold(0, |mut sum, i: i32| {
    async move {
        sum += i;
        eprintln!("{}", i);
        Ok::<_, futures::never::Never>(sum)
    }
});
let mut unfold = pin!(unfold);
unfold.send(5).await?;
```

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

### fn any<Fut, F>(self, f: F) -> Any<Self, Fut, F>

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.Take.html

Execute predicate over asynchronous stream, and return `true` if any element in stream satisfied a predicate.

```APIDOC
## fn any<Fut, F>(self, f: F) -> Any<Self, Fut, F>

### Description
Execute predicate over asynchronous stream, and return `true` if any element in stream satisfied a predicate.

### Method
any

### Signature
fn any<Fut, F>(self, f: F) -> Any<Self, Fut, F>

### Type Parameters
- F: FnMut(Self::Item) -> Fut
- Fut: Future<Output = bool>
- Self: Sized

### Parameters
- f: F - The predicate function.

### Returns
Any<Self, Fut, F> - A future that resolves to a boolean indicating if any element satisfied the predicate.
```

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

### read_to_string Example: Read All Bytes into a String

Source: https://docs.rs/futures/latest/futures/io/trait.AsyncReadExt.html

Reads all bytes from the AsyncRead into a String, returning the total number of bytes read. The example reads 4 bytes and asserts the resulting string.

```rust
use futures::io::{AsyncReadExt, Cursor};

let mut reader = Cursor::new(&b"1234"[..]);
let mut buffer = String::with_capacity(4);

let bytes = reader.read_to_string(&mut buffer).await?;

assert_eq!(bytes, 4);
assert_eq!(buffer, String::from("1234"));
```

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

### compat

Source: https://docs.rs/futures/latest/futures/prelude/self/struct.Buffered.html

Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled.

```APIDOC
## compat

### Description
Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled.

### Method
Method: `compat(self) -> Compat<Self>`

### Type Constraints
- `Self: Sized + Unpin`

### Availability
- Available on crate feature `compat` only.

### Returns
- `Compat<Self>` - A stream compatible with futures 0.1.
```

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

### read_to_end Example: Read All Bytes into a Vec

Source: https://docs.rs/futures/latest/futures/io/trait.AsyncReadExt.html

Reads all bytes from the AsyncRead into a Vec, returning the total number of bytes read. The example reads 4 bytes and asserts the output vector.

```rust
use futures::io::{AsyncReadExt, Cursor};

let mut reader = Cursor::new([1, 2, 3, 4]);
let mut output = Vec::with_capacity(4);

let bytes = reader.read_to_end(&mut output).await?;

assert_eq!(bytes, 4);
assert_eq!(output, vec![1, 2, 3, 4]);
```

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

### inspect_err example

Source: https://docs.rs/futures/latest/futures/future/trait.TryFutureExt.html

Inspects the error value of a future without consuming it. The closure receives a reference to the Error value and can be used for logging or debugging. The example prints the error and still returns Err(1).

```rust
use futures::future::TryFutureExt;

let future = async { Err::<(), _>(1) };
let new_future = future.inspect_err(|&x| println!("about to error: {}", x));
assert_eq!(new_future.await, Err(1));
```

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

### compat

Source: https://docs.rs/futures/latest/futures/prelude/self/select_all/struct.SelectAll.html

Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled.

```APIDOC
## compat

### Description
Wraps a `TryStream` into a stream compatible with libraries using futures 0.1 `Stream`. Requires the `compat` feature to be enabled.

### Method
`compat`

### Signature
```rust
fn compat(self) -> Compat<Self>
where Self: Sized + Unpin
```

### Availability
- **crate feature `compat`** only.

### Return Value
- `Compat<Self>` - A stream compatible with futures 0.1.
```

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

### inspect_ok example

Source: https://docs.rs/futures/latest/futures/future/trait.TryFutureExt.html

Inspects the success value of a future without consuming it. The closure receives a reference to the Ok value and can be used for logging or debugging. The example prints the value and still returns Ok(1).

```rust
use futures::future::TryFutureExt;

let future = async { Ok::<_, ()>(1) };
let new_future = future.inspect_ok(|&x| println!("about to resolve: {}", x));
assert_eq!(new_future.await, Ok(1));
```

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

### Using stream::iter with Vec

Source: https://docs.rs/futures/latest/futures/prelude/self/fn.iter.html

Example showing how to create a stream from a Vec using stream::iter and collect the results. The stream is always ready to yield the next value by calling iter.next() internally.

```rust
use futures::stream::{self, StreamExt};

let stream = stream::iter(vec![17, 19]);
assert_eq!(vec![17, 19], stream.collect::<Vec<i32>>().await);

```

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

### PollImmediate Stream implementation example

Source: https://docs.rs/futures/latest/futures/future/struct.PollImmediate.html

Example showing how to use poll_immediate as a stream. It yields Poll::Ready for completed futures and Poll::Pending for pending ones, and terminates after the future completes.

```rust
use core::pin::pin;

use futures::task::Poll;
use futures::{StreamExt, future};
use future::FusedFuture;

let f = async { 1_u32 };
let f = pin!(f);
let mut r = future::poll_immediate(f);
assert_eq!(r.next().await, Some(Poll::Ready(1)));

let f = async {futures::pending!(); 42_u8};
let f = pin!(f);
let mut p = future::poll_immediate(f);
assert_eq!(p.next().await, Some(Poll::Pending));
assert!(!p.is_terminated());
assert_eq!(p.next().await, Some(Poll::Ready(42)));
assert!(p.is_terminated());
assert_eq!(p.next().await, None);
```
Tokens:
Raw