Struct DrivenAsyncIterator 

pub struct DrivenAsyncIterator<'a, Iter: AsyncIterator> { /* private fields */ }

The AsyncIterator wrapper type that drive_next provides to its closure.

Implementations

impl<Iter: AsyncIterator> DrivenAsyncIterator<'_, Iter>

pub async fn next(&self) -> Option<Iter::Item>

Get the next item from the async iterator.

Note that this method takes &self, and multiple futures are allowed to call it concurrently. However, if you manage to call next in parallel from multiple threads, it’s likely to panic.

Implementation details: DrivenAsyncIterator uses an AtomicRefCell internally, rather than a Mutex. This makes it more efficient and also no_std-compatible. The downside is panics when it’s accessed from parallel threads, but this should be extremely unlikely in practice. DrivenAsyncIterator has a local lifetime bound, so it can’t be given to task::spawn or thread::spawn. Scoped tasks also don’t currently exist. To trigger this panic, you’d have to use something like thread::scope in an async context, which would be unusual and potentially an executor-blocking bug in any case.

Note also that if this method is cancelled, drive_next will continue fetching the next item from the async iterator in the background. This is necessary to satisfy the AsyncIterator contract. Once you start fetching the next item, the only way to fully cancel the fetch is to return from the drive_next closure or cancel drive_next itself.

pub fn with_pin_mut<F, Ret>(&self, f: F) -> Ret

where F: FnOnce(Option<Pin<&mut Iter>>) -> Ret,

Get a temporary pinned reference to the driven async iterator, if it’s not yet done.

drive_next drops its iterator as soon as poll_next returns Done. If with_pin_mut is called after that, the closure will receive None.

The closure argument is not async, because this reference can’t be held across .await points. If you try to call this reentrantly, it will panic.

Whenever you call this method, drive_next will immediately re-poll the iterator, in case it’s something like FuturesUnordered and you just added more work to it. This is kind of a hack, and it would be better if collections like FuturesUnordered handled their own wakeups in these cases, but that’s not how things work today.

pub fn with_mut<F, Ret>(&self, f: F) -> Ret

where F: FnOnce(Option<&mut Iter>) -> Ret, Iter: Unpin,

Get a temporary mutable reference to the driven async iterator, if it’s not yet done.

This works like with_pin_mut, except that it requires the iterator to be Unpin.

Trait Implementations

impl<Iter: AsyncIterator> Debug for DrivenAsyncIterator<'_, Iter>

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

Formats the value using the given formatter.