Relax Default requirement from ChunkPuller::Chunk. This is required in order to implement ConcurrentDynamicIter over a concurrent queue.

Enables chaining of two or more concurrent iterators.

One critical aspect in chaining concurrent iterators is whether or not the length of the first iterator known with certainty. This is required for being able to provide the index of elements pulled from the second iterator. The implementation is much simpler and more efficient when the first iterator is an ExactSizeConcurrentIter.

Therefore, two separate implementations are provided rather than a single generic but slower implementaton.

• chain method on ExactSizeConcurrentIter creates chained iterator with known length of the first iterator.
• chain_inexact method on ConcurrentIter creates the chained iterator with unknown length.

Changes

Mutable Concurrent Iterators

Mutable concurrent iterators and implementation for mut slice

• ConcurrentCollectionMut trait is defined. It requires the IterMut<'a> associated type and con_iter_mut method to create a concurrent mutable iterator.
• ConIterSliceMut is implemented. It is constructed from &'a mut [T] and concurrently yields elements &mut T.
• &'a mut Vec<T> implements IntoConcurrentIter<Item = &'a mut T``> which creates ConIterSliceMut`.
• Therefore, Vec<T> automatically implements ConcurrentCollectionMut providing con_iter_mut method.

Send and Sync bounds revised and relaxed.

In the prior implementation; however, ConIterSlice<'a, T> requires T: Send + Sync. Here, Send is an unnecessary requirement since the iterator will yield items of &'a T which automatically implements Send when T implements Sync.

Due to this unnecessary bound, the following code would not compile in the prior version:

fn fun<T: Sync>(slice: &[T]) {
    let con_iter = slice.into_con_iter();
}

with the error:

  |
7 |     let con_iter = slice.into_con_iter();
  |                          ^^^^^^^^^^^^^
  |
  = note: the following trait bounds were not satisfied:
          `T: Send`
          which is required by `&[T]: orx_concurrent_iter::IntoConcurrentIter`
help: consider restricting the type parameter to satisfy the trait bound
  |
6 | fn fun<T: Sync>(slice: &[T]) where T: Send {
  |                              +++++++++++++

With the fix, the function fun now compiles, as it should.

This is the downstream fix related to the "orx-parallel" issues:

• orxfun/orx-parallel#58
• orxfun/orx-parallel#59

Concurrent draining iterator

• ConcurrentDrainableOverSlice trait is defined. It is implemented for Vec.
• This trait auto implements con_drain(range) method which returns a concurrent draining iterator over the slice of the collection.
• Concurrent draining iterator ConIterVecDrain is implemented, and set as the concurrent draining iterator of Vec.
• Code is refactored so that both consuming concurrent iterators and draining concurrent iterators, as well as their chunk pullers, use the same iterator over a slice.

implementations::jagged_arrays module

A module is created and exposed for jagged array implementations. Two main concurrent iterator implementations are provided in the module.

ConIterJaggedRef is a concurrent iterator over references of flattened elements of a collection of slices. Slices are defined as generic as possible to allow for different nested collections.

ConIterJaggedOwned is a concurrent iterator over owned values of flattened elements of a collection of arrays or vectors (any raw vector).

The types required to create both iterators are made publicly available to support extensions in other crates, such as the SplitVec.

VecDeque implementation

Although it is a single contagious memory under the hood, elements of the VecDeque can be represented as flat of two sequential slices. The slices can be achieved by using its public method as_slices. Since two slices form a jagged array, VecDeques concurrent iterator is implemented directly using efficient jagged array concurrent iterators. Parallelization over both references and owned values of a VecDeque seems to be very efficient as (will soon be) reported in the tests in orx_parallel crate.

Fixes #59

Changes, v2

This release contains major redesign and breaking changes in the api.

Redesigning Concurrent Iterator Traits

As in v1, we continue to have ConcurrentIter trait which defines the core functionality of concurrent iterators.

Additionally, we have:

• IntoConcurrentIter trait which represents types that can be consumed and converted into a concurrent iterator using its into_con_iter method. This is the concurrent counterpart of the standard IntoIterator trait.
• In addition there exists a special "into" trait. IterIntoConcurrentIter trait allows to convert any generic sequential Iterator into a concurrent iterator. Unlike the case with concrete types, concurrent iterators created from a generic iterator serialize the process of yielding elements. In order to make the distinction explicit, this conversion is through iter_into_con_iter method with a different name.

Finally, we have the following auto-implemented traits based on IntoConcurrentIter implementations:

• ConcurrentIterable trait is defined. This represents types from which a concurrent iterator can be created multiple times without consuming the instance using its con_iter method. This is the concurrent counter part of orx_iterable::Iterable.
• ConcurrentCollection trait is defined. This represents types from which we can create a concurrent iterator yielding references of the elements stored in the collection using its con_iter method. Additionally, we can use its into_con_iter method to consume the collection and create a concurrent iterator that yields the stored elements directly, rather then references. This is the concurrent counterpart of the orx_iterable::Collection trait.

Pullers are redesigned

Item and chunk pullers are made more explicit. They are regular sequential iterators which are created from, connected to and pulls their elements from a concurrent iterator.

Migration to 2024edition

Also

Documentation, tests and benchmarks are significantly revised.

CI is added to the repo.

Fixes #42 (introduces the size_hint method).

• Upgraded pinned vector dependencies.
• Fixed updated clippy warnings.
• Minor revision in documentation.