Crate seekable_iterator

Crate seekable_iterator 

Source
Expand description

Seekable Iterator

github Latest version Documentation Apache 2.0 or MIT license.

§Traits

Provides:

Adapters to lender::Lender and lending_iterator::LendingIterator are provided for CursorLendingIterator and PooledIterator when the corresponding features are enabled.

Depending on features, MergingIter, PooledIter, and ThreadsafePooledIter iterator adapters are provided.

§Semantics

The PooledIterator trait makes roughly the same semantic assumptions about the iterator as a normal iterator.

However, the Cursor*Iterator and Seekable*Iterator traits assume that an implementor is a circular iterator over some ordered collection; the iterator is made circular by adding a phantom element before the first element and after the last element of the ordered collection. The iterator is thus not a FusedIterator, as after iteration over the collection is completed, the iterator wraps back around to the start.

The PooledIterator and Cursor*Iterator traits do not expose any comparator that the ordered collection and iterator might be using, but the Seekable and Seekable*Iterator traits do expose it via a Comparator generic. An OrdComparator struct is provided that can compare keys that implement Ord, using their Ord implementation.

§Features

  • clone-behavior (enabled by default): Implements clone-behavior traits for OrdComparator.
  • generic-container (enabled by default): Implements Comparator for containers of dyn Comparator, and for GenericContainer whenever GenericContainer wraps a container of a Comparator implementation.
  • lender: provide adapters to lender::Lender.
  • lending-iterator: provide adapters to lending_iterator::LendingIterator.
  • alloc: provide MergingIter, which merges together several SeekableLendingIterators into one SeekableLendingIterator that iterates over all their items in order. Similar to adapters like itertools’ kmerge, though somewhat more complicated in order to support switching the direction of iteration. Note: alloc isn’t truly crucial for MergingIter; open an issue if you want it on no-alloc.
  • std: doesn’t do much alone. Enables alloc, as well as the std feature of a dependency.
  • anchored-pool: provide PooledIter and ThreadsafePooledIter. PooledIter is an adapter from CursorLendingIterator to CursorPooledIterator, and ThreadsafePooledIter is a Send + Sync version. This feature enables std, though std isn’t truly crucial for PooledIter; open an issue if you want it on no-std with alloc.
  • anchored-pool-default: same as above, and enable the default feature flags of anchored-pool. The anchored-pool crate requires that either its kanal or crossbeam-channel feature is enabled; using the anchored-pool feature flag alone will result in a compile-time error unless you enable the kanal or crossbeam-channel flag yourself.

§License

Licensed under either of

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Structs§

LenderAdapterlender
An adapter for CursorLendingIterator which implements lender::Lender.
LendingIteratorAdapterlending-iterator
An adapter for CursorLendingIterator which implements lending_iterator::LendingIterator.
MergingIteralloc
A MergingIter takes several SeekableLendingIterators as input, and iterates over the sorted union of their entries.
OrdComparator
A Comparator which uses keys’ Ord implementations.
OutOfBuffers
An error that may be returned if no buffer pools were available in a PooledIterator, instead of waiting for a buffer to become available.
PoolItemanchored-pool
The type of an item returned by PooledIter.
PooledIteranchored-pool
Convert a CursorLendingIterator into a CursorPooledIterator by storing recently accessed items in reusable buffers.
PooledLenderAdapterlender
An adapter for PooledIterator which implements lender::Lender.
PooledLendingIteratorAdapterlending-iterator
An adapter for PooledIterator which implements lending_iterator::LendingIterator.
ThreadsafePoolItemanchored-pool
The type of an item returned by ThreadsafePooledIter.
ThreadsafePooledIteranchored-pool
Convert a CursorLendingIterator into a CursorPooledIterator by storing recently accessed items in reusable buffers.

Traits§

Comparator
Interface for comparing keys (or entries) of a sorted collection.
CursorIterator
A CursorIterator provides access to the entries of some sorted collection, and can move its current position in either direction.
CursorLendingIterator
A CursorLendingIterator provides access to the entries of some sorted collection, and can move its current position in either direction.
CursorPooledIterator
A CursorPooledIterator provides access to the entries of some sorted collection, and can move its current position in either direction.
ItemToKey
Convert one of the items of an iterator into a Key reference, intended for use with a SeekableLendingIterator.
LendItem
Trait for getting the item of a lending iterator.
PooledIterator
A PooledIterator 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.
Seekable
A trait adding seek functionality to one of the cursor iterator traits.
SeekableIterator
An Iterator with cursor methods from CursorIterator and the ability to seek from Seekable.
SeekableLendingIterator
A lending iterator with cursor methods from CursorLendingIterator and the ability to seek from Seekable.
SeekablePooledIterator
A PooledIterator with cursor methods from CursorPooledIterator and the ability to seek from Seekable.

Type Aliases§

LentItem
The item of a lending iterator, with a particular lifetime.