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
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

use crate::ops::DerefMut;
use crate::pin::Pin;
use crate::task::{Context, Poll};

/// 用于处理异步迭代器的 trait。
///
/// 这是主要的异步迭代器 trait。
/// 更多关于异步迭代器的概念，请参见 [模块级文档][module-level documentation]。
/// 特别是，您可能想知道如何 [实现 `AsyncIterator`][impl]。
///
/// [module-level documentation]: index.html
/// [impl]: index.html#implementing-async-iterator
#[unstable(feature = "async_iterator", issue = "79024")]
#[must_use = "async iterators do nothing unless polled"]
#[doc(alias = "Stream")]
pub trait AsyncIterator {
    /// 异步迭代器产生的项的类型。
    type Item;

    /// 尝试提取此异步迭代器的下一个值，如果该值尚不可用，则注册当前任务以进行唤醒，如果异步迭代器耗尽，则返回 `None`。
    ///
    /// # 返回值
    ///
    /// 有几个可能的返回值，每个表示不同的异步迭代器状态:
    ///
    /// - `Poll::Pending` 表示这个异步迭代器的下一个值还没有准备好。实现将确保在准备好下一个值时将通知当前任务。
    ///
    /// - `Poll::Ready(Some(val))` 表示异步迭代器已成功生成值 `val`，并且可能会在后续 `poll_next` 调用中生成更多值。
    ///
    /// - `Poll::Ready(None)` 表示异步迭代器已终止，不应再次调用 `poll_next`。
    ///
    /// # Panics
    ///
    /// 一旦异步迭代器完成 (从 `poll_next` 返回 `Ready(None)`)，再次调用它的 `poll_next` 方法可能会出现 panic、永久阻塞或导致其他类型的问题; `AsyncIterator` trait 对调用的效果没有要求。
    ///
    /// 然而，由于 `poll_next` 方法没有标记为 `unsafe`，所以 Rust 的通常规则适用：无论异步迭代器的状态如何，调用都不能导致未定义的行为 (内存损坏、错误使用 `unsafe` 函数等)。
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>;

    /// 返回异步迭代器剩余长度的界限。
    ///
    /// 具体来说，`size_hint()` 返回一个元组，其中第一个元素是下界，第二个元素是上界。
    ///
    /// 返回的元组的后半部分是 <code>[Option]<[usize]></code>。
    /// 这里的 [`None`] 表示没有已知的上限，或者该上限大于 [`usize`]。
    ///
    /// # 实现说明
    ///
    /// 异步迭代器实现产生声明的元素数量并不是强制性的。
    /// 有缺陷的异步迭代器产生的结果可能小于元素的下限或大于元素的上限。
    ///
    /// `size_hint()` 主要用于优化，例如为异步迭代器的元素保留空间，但不能信任它，例如在不安全的代码中省略边界检查。
    ///
    /// `size_hint()` 的不正确实现不应导致违反内存安全性。
    ///
    /// 也就是说，该实现应提供正确的估计，因为否则将违反 trait 的协议。
    ///
    /// 默认实现返回 <code>(0, [None])</code>，这对于任何异步迭代器都是正确的。
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[inline]
    fn size_hint(&self) -> (usize, Option<usize>) {
        (0, None)
    }
}

#[unstable(feature = "async_iterator", issue = "79024")]
impl<S: ?Sized + AsyncIterator + Unpin> AsyncIterator for &mut S {
    type Item = S::Item;

    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
        S::poll_next(Pin::new(&mut **self), cx)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        (**self).size_hint()
    }
}

#[unstable(feature = "async_iterator", issue = "79024")]
impl<P> AsyncIterator for Pin<P>
where
    P: DerefMut,
    P::Target: AsyncIterator,
{
    type Item = <P::Target as AsyncIterator>::Item;

    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
        <P::Target as AsyncIterator>::poll_next(self.as_deref_mut(), cx)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        (**self).size_hint()
    }
}