orx-concurrent-iter 3.3.0

A thread-safe and ergonomic concurrent iterator trait and efficient lock-free implementations.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

use crate::{concurrent_iterable::ConcurrentIterable, into_concurrent_iter::IntoConcurrentIter};

/// A type implementing [`ConcurrentCollection`] is a collection owning the elements such that
///
/// * if the elements are of type `T`,
/// * then, non-consuming [`con_iter`] method can be called **multiple times** to create concurrent
///   iterators; i.e., [`ConcurrentIter`], yielding references to the elements `&T`.
///
/// This trait can be considered as the *concurrent counterpart* of the [`Collection`] trait.
///
/// [`con_iter`]: crate::ConcurrentCollection::con_iter
/// [`Collection`]: orx_iterable::Collection
/// [`ConcurrentIter`]: crate::ConcurrentIter
///
/// # Examples
///
/// ```
/// use orx_concurrent_iter::*;
///
/// let data = vec![1, 2];
///
/// let con_iter = data.con_iter();
/// assert_eq!(con_iter.next(), Some(&1));
/// assert_eq!(con_iter.next(), Some(&2));
/// assert_eq!(con_iter.next(), None);
/// ```
pub trait ConcurrentCollection {
    /// Type of the element that the concurrent iterator yields.
    type Item;

    /// Type of the ConcurrentIterable that reference of this type implements.
    type Iterable<'i>: ConcurrentIterable<Item = &'i Self::Item>
    where
        Self: 'i;

    /// Returns the ConcurrentIterable that a reference of this type can create.
    fn as_concurrent_iterable(&self) -> Self::Iterable<'_>;

    /// A type implementing [`ConcurrentCollection`] is a collection owning the elements such that
    ///
    /// * if the elements are of type `T`,
    /// * then, non-consuming [`con_iter`] method can be called **multiple times** to create concurrent
    ///   iterators; i.e., [`ConcurrentIter`], yielding references to the elements `&T`.
    ///
    /// This trait can be considered as the *concurrent counterpart* of the [`Collection`] trait.
    ///
    /// [`con_iter`]: crate::ConcurrentCollection::con_iter
    /// [`Collection`]: orx_iterable::Collection
    /// [`ConcurrentIter`]: crate::ConcurrentIter
    ///
    /// # Examples
    ///
    /// ```
    /// use orx_concurrent_iter::*;
    ///
    /// let data = vec![1, 2];
    ///
    /// let con_iter = data.con_iter();
    /// assert_eq!(con_iter.next(), Some(&1));
    /// assert_eq!(con_iter.next(), Some(&2));
    /// assert_eq!(con_iter.next(), None);
    /// ```
    fn con_iter(&self) -> <Self::Iterable<'_> as ConcurrentIterable>::Iter {
        self.as_concurrent_iterable().con_iter()
    }
}

impl<X> ConcurrentCollection for X
where
    X: IntoConcurrentIter,
    for<'a> &'a X: IntoConcurrentIter<Item = &'a <X as IntoConcurrentIter>::Item>,
{
    type Item = <X as IntoConcurrentIter>::Item;

    type Iterable<'i>
        = &'i X
    where
        Self: 'i;

    fn as_concurrent_iterable(&self) -> Self::Iterable<'_> {
        self
    }
}