Trait CursorPooledIterator 

pub trait CursorPooledIterator: PooledIterator {
    // Required methods
    fn valid(&self) -> bool;
    fn current(&self) -> Option<Self::Item>;
    fn prev(&mut self) -> Option<Self::Item>;
    fn try_current(&self) -> Result<Option<Self::Item>, OutOfBuffers>;
    fn try_prev(&mut self) -> Result<Option<Self::Item>, OutOfBuffers>;
}

A CursorPooledIterator provides access to the entries of some sorted collection, and can move its current position in either direction.

The iterator is similar to a lending iterator (which can lend one item at a time), but can make use of a buffer pool to lend out multiple items at a time.

Conceptually, it is circular, and its initial position is before the first entry and after the last entry. As such, it is not a FusedIterator, as continuing to call next() at the end of iteration wraps around to the start. (Note that if the collection is empty, then the iterator will remain at that phantom position.)

Implementations may or may not be threadsafe. Even if an implementation is threadsafe, newly-added entries may or may not be seen immediately by other threads.

Forwards iteration should be preferred over backwards iteration.

Required Methods

fn valid(&self) -> bool

Determine whether the iterator is currently at any value in the collection. If the iterator is invalid, then it is conceptually one position before the first entry and one position after the last entry. (Or, there may be no entries.)

current() will be Some if and only if the iterator is valid.

fn current(&self) -> Option<Self::Item>

Get the current value the iterator is at, if the iterator is valid.

May need to wait for a buffer to become available.

Potential Panics or Deadlocks

If self.buffer_pool_size() == 0, then this method is permitted to panic or deadlock. This method may also panic or cause a deadlock if no buffers are currently available, and the current thread needs to make progress in order to release a buffer.

If it is possible for a different thread to make progress and make a buffer available, this method should not panic or deadlock.

fn prev(&mut self) -> Option<Self::Item>

Move the iterator one position back, and return the entry at that position. Returns None if the iterator was at the first entry.

May need to wait for a buffer to become available.

Some implementations may have worse performance for backwards iteration than forwards iteration, so prefer to not use prev.

Potential Panics or Deadlocks

If self.buffer_pool_size() == 0, then this method is permitted to panic or deadlock. This method may also panic or cause a deadlock if no buffers are currently available, and the current thread needs to make progress in order to release a buffer.

If it is possible for a different thread to make progress and make a buffer available, this method should not panic or deadlock.

fn try_current(&self) -> Result<Option<Self::Item>, OutOfBuffers>

If a buffer is available, get the current value the iterator is at, if the iterator is valid.

Errors

Returns an error if no buffers were available.

fn try_prev(&mut self) -> Result<Option<Self::Item>, OutOfBuffers>

If a buffer is available, move the iterator one position back, and return the entry at that position. Returns Ok(None) if the iterator was at the first entry.

Some implementations may have worse performance for backwards iteration than forwards iteration, so prefer to not use try_prev.

Errors

Returns an error if no buffers were available.

Implementors

impl<I, BorrowedItem> CursorPooledIterator for PooledIter<I, BorrowedItem>

where I: CursorLendingIterator, BorrowedItem: ToOwned, for<'lend> LentItem<'lend, I>: Borrow<BorrowedItem>,

Available on crate feature anchored-pool only.

impl<I, BorrowedItem> CursorPooledIterator for ThreadsafePooledIter<I, BorrowedItem>

where I: CursorLendingIterator, BorrowedItem: ToOwned, for<'lend> LentItem<'lend, I>: Borrow<BorrowedItem>,

Available on crate feature anchored-pool only.