Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Подробнее о трейтах для async

На протяжении всей главы мы использовали трейты Future, Stream и StreamExt различными способами. До сих пор, однако, мы избегали слишком глубокого погружения в детали того, как они работают или как они сочетаются друг с другом, что в большинстве случаев нормально для повседневной работы с Rust. Иногда, однако, вы столкнётесь с ситуациями, где вам потребуется понять ещё несколько деталей этих трейтов, вместе с типом Pin и трейтом Unpin. В этом разделе мы углубимся ровно настолько, чтобы помочь в таких сценариях, оставив по-настоящему глубокое погружение для другой документации.

Трейт Future

Начнём с более подробного рассмотрения того, как работает трейт Future. Вот как Rust определяет его:

#![allow(unused)]
fn main() {
use std::pin::Pin;
use std::task::{Context, Poll};

pub trait Future {
    type Output;

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}
}

Это определение трейта включает кучу новых типов, а также некоторый синтаксис, который мы не видели раньше, поэтому давайте разберём определение по частям.

Во-первых, ассоциированный тип Output у Future говорит, во что разрешается фьючерс. Это аналогично ассоциированному типу Item для трейта Iterator. Во-вторых, Future имеет метод poll, который принимает специальную ссылку Pin для своего параметра self и изменяемую ссылку на тип Context, и возвращает Poll<Self::Output>. Мы поговорим подробнее о Pin и Context чуть позже. Пока сосредоточимся на том, что возвращает метод — тип Poll:

#![allow(unused)]
fn main() {
pub enum Poll<T> {
    Ready(T),
    Pending,
}
}

Этот тип Poll похож на Option. У него есть один вариант со значением, Ready(T), и один без, Pending. Однако Poll означает нечто совершенно иное, чем Option! Вариант Pending указывает, что у фьючерса ещё есть работа, поэтому вызывающей стороне нужно будет проверить снова позже. Вариант Ready указывает, что Future завершил свою работу и значение T доступно.

Примечание: редко возникает необходимость вызывать poll напрямую, но если вам всё же нужно, имейте в виду, что с большинством фьючерсов вызывающая сторона не должна снова вызывать poll после того, как фьючерс вернул Ready. Многие фьючерсы запаникуют, если их опросят снова после того, как они стали готовы. Фьючерсы, которые безопасно опрашивать повторно, явно скажут об этом в своей документации. Это похоже на то, как ведёт себя Iterator::next.

Когда вы видите код, использующий await, Rust под капотом компилирует его в код, который вызывает poll. Если вы вернётесь к листингу 17-4, где мы напечатали заголовок страницы для одного URL после его разрешения, Rust компилирует его во что-то вроде (хотя и не точно) такого:

match page_title(url).poll() {
    Ready(page_title) => match page_title {
        Some(title) => println!("The title for {url} was {title}"),
        None => println!("{url} had no title"),
    }
    Pending => {
        // Но что здесь должно быть?
    }
}

Что мы должны делать, когда фьючерс всё ещё Pending? Нам нужен какой-то способ попробовать снова, и снова, и снова, пока фьючерс наконец не станет готов. Иными словами, нам нужен цикл:

let mut page_title_fut = page_title(url);
loop {
    match page_title_fut.poll() {
        Ready(value) => match page_title {
            Some(title) => println!("The title for {url} was {title}"),
            None => println!("{url} had no title"),
        }
        Pending => {
            // continue
        }
    }
}

Если бы Rust компилировал это ровно в такой код, то каждый await был бы блокирующим — прямо противоположным тому, к чему мы стремились! Вместо этого Rust гарантирует, что цикл может передать управление чему-то, что может приостановить работу над этим фьючерсом, чтобы поработать над другими фьючерсами, а затем проверить этот снова позже. Как мы видели, это что-то — асинхронная среда выполнения, и эта работа по планированию и координации является одной из её главных задач.

В разделе «Отправка данных между двумя задачами с помощью передачи сообщений» мы описали ожидание на rx.recv. Вызов recv возвращает фьючерс, и ожидание фьючерса опрашивает его. Мы отметили, что среда выполнения приостановит фьючерс, пока он не станет готов с либо Some(message), либо None, когда канал закроется. С нашим более глубоким пониманием трейта Future, и конкретно Future::poll, мы можем увидеть, как это работает. Среда выполнения знает, что фьючерс не готов, когда он возвращает Poll::Pending. И наоборот, среда выполнения знает, что фьючерс готов и продвигает его, когда poll возвращает Poll::Ready(Some(message)) или Poll::Ready(None).

Точные детали того, как среда выполнения делает это, выходят за рамки этой книги, но ключ в том, чтобы увидеть базовую механику фьючерсов: среда выполнения опрашивает каждый фьючерс, за который она отвечает, отправляя фьючерс обратно спать, когда он ещё не готов.

Тип Pin и трейт Unpin

Ранее в листинге 17-13 мы использовали макрос trpl::join! для ожидания трёх фьючерсов. Однако часто встречается коллекция, такая как вектор, содержащая некоторое количество фьючерсов, которое не будет известно до времени выполнения. Давайте изменим листинг 17-13 на код в листинге 17-23, который помещает три фьючерса в вектор и вызывает функцию trpl::join_all, которая пока не скомпилируется.

Имя файла: src/main.rs
extern crate trpl; // required for mdbook test

use std::time::Duration;

fn main() {
    trpl::block_on(async {
        let (tx, mut rx) = trpl::channel();

        let tx1 = tx.clone();
        let tx1_fut = async move {
            let vals = vec![
                String::from("hi"),
                String::from("from"),
                String::from("the"),
                String::from("future"),
            ];

            for val in vals {
                tx1.send(val).unwrap();
                trpl::sleep(Duration::from_secs(1)).await;
            }
        };

        let rx_fut = async {
            while let Some(value) = rx.recv().await {
                println!("received '{value}'");
            }
        };

        let tx_fut = async move {
            // --snip--
            let vals = vec![
                String::from("more"),
                String::from("messages"),
                String::from("for"),
                String::from("you"),
            ];

            for val in vals {
                tx.send(val).unwrap();
                trpl::sleep(Duration::from_secs(1)).await;
            }
        };

        let futures: Vec<Box<dyn Future<Output = ()>>> =
            vec![Box::new(tx1_fut), Box::new(rx_fut), Box::new(tx_fut)];

        trpl::join_all(futures).await;
    });
}
Листинг 17-23: Ожидание фьючерсов в коллекции

Мы помещаем каждый фьючерс внутрь Box, чтобы превратить их в трейт-объекты, точно так же, как мы делали в разделе «Возврат ошибок из run» в главе 12. (Мы рассмотрим трейт-объекты подробно в главе 18.) Использование трейт-объектов позволяет нам трактовать каждый из анонимных фьючерсов, созданных этими типами, как один и тот же тип, потому что все они реализуют трейт Future.

Это может удивить. В конце концов, ни один из async-блоков ничего не возвращает, поэтому каждый из них создаёт Future<Output = ()>. Помните, что Future — это трейт, однако, и что компилятор создаёт уникальное перечисление для каждого async-блока, даже когда они имеют идентичные типы вывода. Точно так же, как вы не можете поместить два разных написанных вручную struct в Vec, вы не можете смешивать сгенерированные компилятором перечисления.

Затем мы передаём коллекцию фьючерсов в функцию trpl::join_all и ожидаем результат. Однако это не компилируется; вот соответствующая часть сообщений об ошибках.

error[E0277]: `dyn Future<Output = ()>` cannot be unpinned
  --> src/main.rs:48:33
   |
48 |         trpl::join_all(futures).await;
   |                                 ^^^^^ the trait `Unpin` is not implemented for `dyn Future<Output = ()>`
   |
   = note: consider using the `pin!` macro
           consider using `Box::pin` if you need to access the pinned value outside of the current scope
   = note: required for `Box<dyn Future<Output = ()>>` to implement `Future`
note: required by a bound in `futures_util::future::join_all::JoinAll`
  --> file:///home/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/futures-util-0.3.30/src/future/join_all.rs:29:8
   |
27 | pub struct JoinAll<F>
   |            ------- required by a bound in this struct
28 | where
29 |     F: Future,
   |        ^^^^^^ required by this bound in `JoinAll`

Примечание в этом сообщении об ошибке говорит нам, что мы должны использовать макрос pin!, чтобы закрепить значения, что означает помещение их внутрь типа Pin, который гарантирует, что значения не будут перемещены в памяти. Сообщение об ошибке говорит, что закрепление требуется, потому что dyn Future<Output = ()> должен реализовывать трейт Unpin, а в настоящее время не реализует.

Функция trpl::join_all возвращает struct с именем JoinAll. Эта структура является обобщённой по типу F, который ограничен реализацией трейта Future. Прямое ожидание фьючерса с await неявно закрепляет фьючерс. Вот почему нам не нужно использовать pin! везде, где мы хотим ожидать фьючерс.

Однако здесь мы не ожидаем фьючерс напрямую. Вместо этого мы конструируем новый фьючерс, JoinAll, передавая коллекцию фьючерсов в функцию join_all. Сигнатура join_all требует, чтобы типы элементов в коллекции все реализовывали трейт Future, а Box<T> реализует Future только если T, который он оборачивает, является фьючерсом, реализующим трейт Unpin.

Это много, чтобы усвоить! Чтобы действительно понять это, давайте углубимся немного дальше в то, как на самом деле работает трейт Future, в частности вокруг закрепления. Взгляните снова на определение трейта Future:

#![allow(unused)]
fn main() {
use std::pin::Pin;
use std::task::{Context, Poll};

pub trait Future {
    type Output;

    // Обязательный метод
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}
}

Параметр cx и его тип Context — ключ к тому, как среда выполнения на самом деле знает, когда проверять любой данный фьючерс, оставаясь при этом ленивой. Опять же, детали того, как это работает, выходят за рамки этой главы, и вам обычно нужно думать об этом только при написании собственной реализации Future. Вместо этого мы сосредоточимся на типе для self, поскольку это первый раз, когда мы видим метод, где self имеет аннотацию типа. Аннотация типа для self работает как аннотации типов для других параметров функции, но с двумя ключевыми отличиями:

  • Она говорит Rust, каким типом должен быть self, чтобы метод можно было вызвать.
  • Он не может быть просто любым типом. Он ограничен типом, для которого реализован метод, ссылкой или умным указателем на этот тип, или Pin, оборачивающим ссылку на этот тип.

Мы увидим больше об этом синтаксисе в главе 18. Пока достаточно знать, что если мы хотим опросить фьючерс, чтобы проверить, является ли он Pending или Ready(Output), нам нужна обёрнутая в Pin изменяемая ссылка на тип.

Pin — это обёртка для pointer-подобных типов, таких как &, &mut, Box и Rc. (Технически Pin работает с типами, которые реализуют трейты Deref или DerefMut, но это фактически эквивалентно работе только со ссылками и умными указателями.) Pin сам по себе не является указателем и не имеет никакого поведения сам по себе, как Rc и Arc с подсчётом ссылок; это чисто инструмент, который компилятор может использовать для обеспечения ограничений на использование указателей.

Вспомнив, что await реализован в терминах вызовов poll, начинает объяснять сообщение об ошибке, которое мы видели ранее, но оно было в терминах Unpin, а не Pin. Так как именно Pin связан с Unpin, и почему Future нужен self в типе Pin для вызова poll?

Помните из ранее в этой главе, что серия точек await в фьючерсе компилируется в конечный автомат, и компилятор гарантирует, что этот конечный автомат следует всем обычным правилам Rust относительно безопасности, включая заимствование и владение. Чтобы это работало, Rust смотрит, какие данные нужны между одной точкой await и либо следующей точкой await, либо концом async-блока. Затем он создаёт соответствующий вариант в скомпилированном конечном автомате. Каждый вариант получает доступ, который ему нужен к данным, которые будут использоваться в этом разделе исходного кода, будь то путём взятия владения этими данными или путём получения изменяемой или неизменяемой ссылки на них.

Пока всё хорошо: если мы сделаем что-то не так с владением или ссылками в данном async-блоке, проверка заимствований скажет нам об этом. Когда мы хотим переместить фьючерс, который соответствует этому блоку — например, переместить его в Vec, чтобы передать в join_all, — всё становится сложнее.

Когда мы перемещаем фьючерс — будь то путём помещения его в структуру данных для использования в качестве итератора с join_all или путём возврата его из функции — это на самом деле означает перемещение конечного автомата, который Rust создаёт для нас. И в отличие от большинства других типов в Rust, фьючерсы, которые Rust создаёт для async-блоков, могут в конечном итоге иметь ссылки на самих себя в полях любого данного варианта, как показано на упрощённой иллюстрации на рисунке 17-4.

Таблица из одного столбца и трёх строк, представляющая фьючерс fut1: в первых двух строках лежат значения 0 и 1, а стрелка из третьей строки указывает обратно на вторую строку — это внутренняя ссылка внутри фьючерса.
Рисунок 17-4: Самоссылающийся тип данных

Однако по умолчанию любой объект, который имеет ссылку на себя, небезопасно перемещать, потому что ссылки всегда указывают на фактический адрес памяти того, на что они ссылаются (см. рисунок 17-5). Если вы переместите саму структуру данных, эти внутренние ссылки останутся указывающими на старое место. Однако это место в памяти теперь недействительно. Во-первых, его значение не будет обновлено при внесении изменений в структуру данных. Во-вторых — что более важно — компьютер теперь может свободно использовать эту память для других целей! Вы можете в конечном итоге прочитать совершенно не связанные данные позже.

Две таблицы, изображающие два фьючерса, fut1 и fut2; у каждой один столбец и три строки. Они показывают результат перемещения фьючерса из fut1 в fut2. Первая таблица, fut1, закрашена серым, в каждой ячейке стоит вопросительный знак — это неизвестная память. Во второй таблице, fut2, в первой и второй строках стоят 0 и 1, а стрелка из её третьей строки указывает на вторую строку fut1: это указатель на старое расположение фьючерса в памяти до его перемещения.
Рисунок 17-5: Небезопасный результат перемещения самоссылающегося типа данных

Теоретически компилятор Rust мог бы попытаться обновить каждую ссылку на объект всякий раз, когда он перемещается, но это может добавить много накладных расходов на производительность, особенно если целая сеть ссылок нуждается в обновлении. Если бы мы могли вместо этого убедиться, что рассматриваемая структура данных не перемещается в памяти, нам не пришлось бы обновлять какие-либо ссылки. Именно для этого и нужна проверка заимствований Rust: в безопасном коде она предотвращает перемещение любого элемента с активной ссылкой на него.

Pin строится на этом, чтобы дать нам именно ту гарантию, которая нам нужна. Когда мы закрепляем значение, оборачивая указатель на это значение в Pin, оно больше не может перемещаться. Таким образом, если у вас есть Pin<Box<SomeType>>, вы фактически закрепляете значение SomeType, а не указатель Box. Рисунок 17-6 иллюстрирует этот процесс.

Три прямоугольника рядом: первый с меткой «Pin», второй «b1», третий «pinned». Внутри «pinned» находится таблица «fut» из одного столбца — это фьючерс, у которого по ячейке на каждую часть структуры данных. В первой ячейке значение «0», из второй выходит стрелка к четвёртой, последней ячейке со значением «1», а третья ячейка нарисована пунктиром с многоточием: у структуры данных могут быть и другие части. Вместе таблица «fut» представляет самоссылающийся фьючерс. Стрелка выходит из прямоугольника «Pin», проходит через «b1» и заканчивается внутри «pinned» на таблице «fut».
Рисунок 17-6: Закрепление Box, который указывает на самоссылающийся тип фьючерса

Фактически, указатель Box всё ещё может свободно перемещаться. Помните: мы заботимся о том, чтобы данные, на которые в конечном итоге ссылаются, оставались на месте. Если указатель перемещается, но данные, на которые он указывает, находятся в том же месте, как на рисунке 17-7, нет потенциальной проблемы. (В качестве самостоятельного упражнения посмотрите на документацию для типов, а также модуль std::pin и попробуйте разобраться, как вы могли бы сделать это с Pin, оборачивающим Box.) Ключ в том, что самоссылающийся тип не может перемещаться, потому что он всё ещё закреплён.

Четыре прямоугольника в трёх приблизительных столбцах, как на предыдущей диаграмме, но с изменением во втором столбце. Теперь там два прямоугольника, «b1» и «b2»; «b1» закрашен серым, а стрелка из «Pin» идёт через «b2» вместо «b1»: указатель переместился с «b1» на «b2», а данные в «pinned» не сдвинулись.
Рисунок 17-7: Перемещение Box, который указывает на самоссылающийся тип фьючерса

Однако большинство типов совершенно безопасно перемещать, даже если они оказываются за указателем Pin. Нам нужно думать о закреплении только тогда, когда элементы имеют внутренние ссылки. Примитивные значения, такие как числа и булевы значения, безопасны, потому что у них очевидно нет внутренних ссылок. Также как и большинство типов, с которыми вы обычно работаете в Rust. Вы можете перемещать Vec, например, без беспокойства. Учитывая то, что мы видели до сих пор, если у вас есть Pin<Vec<String>>, вам придётся делать всё через безопасные, но ограничительные API, предоставляемые Pin, хотя Vec<String> всегда безопасно перемещать, если нет других ссылок на него. Нам нужен способ сообщить компилятору, что в таких случаях можно безопасно перемещать элементы — и вот тут-то и вступает в игру Unpin.

Unpin — это маркерный трейт, похожий на трейты Send и Sync, которые мы видели в главе 16, и, таким образом, не имеет собственной функциональности. Маркерные трейты существуют только чтобы сообщить компилятору, что безопасно использовать тип, реализующий данный трейт, в определённом контексте. Unpin сообщает компилятору, что данный тип не должен соблюдать какие-либо гарантии относительно того, можно ли безопасно перемещать рассматриваемое значение.

Так же, как с Send и Sync, компилятор автоматически реализует Unpin для всех типов, где он может доказать, что это безопасно. Особый случай, снова аналогичный Send и Sync, — это когда Unpin не реализован для типа. Нотация для этого — impl !Unpin for SomeType, где SomeType — имя типа, который действительно должен соблюдать эти гарантии, чтобы быть безопасным всякий раз, когда указатель на этот тип используется в Pin.

Иными словами, есть две вещи, которые нужно иметь в виду о связи между Pin и Unpin. Во-первых, Unpin — это «нормальный» случай, а !Unpin — особый случай. Во-вторых, реализует ли тип Unpin или !Unpin, только имеет значение, когда вы используете закреплённый указатель на этот тип, например Pin<&mut SomeType>.

Чтобы сделать это конкретным, подумайте о String: у неё есть длина и символы Unicode, которые её составляют. Мы можем обернуть String в Pin, как показано на рисунке 17-8. Однако String автоматически реализует Unpin, как и большинство других типов в Rust.

Слева прямоугольник «Pin» со стрелкой к прямоугольнику «String» справа. В «String» лежат данные 5usize — длина строки — и буквы «h», «e», «l», «l», «o» — символы строки «hello», хранящейся в этом экземпляре String. Пунктирный прямоугольник охватывает «String» и его метку, но не «Pin».
Рисунок 17-8: Закрепление String; пунктирная линия указывает, что String реализует трейт Unpin и, следовательно, не закреплена

В результате мы можем делать вещи, которые были бы незаконны, если бы String реализовывал !Unpin, например заменять одну строку другой в точно том же месте в памяти, как на рисунке 17-9. Это не нарушает контракт Pin, потому что String не имеет внутренних ссылок, которые делают его небезопасным для перемещения. Именно поэтому он реализует Unpin, а не !Unpin.

Те же данные строки «hello» из предыдущего примера, теперь с меткой «s1» и закрашенные серым. Прямоугольник «Pin» из предыдущего примера теперь указывает на другой экземпляр String с меткой «s2»: он действителен, имеет длину 7usize и содержит символы строки «goodbye». s2 обведён пунктирным прямоугольником, потому что тоже реализует трейт Unpin.
Рисунок 17-9: Замена String совершенно другой String в памяти

Теперь мы знаем достаточно, чтобы понять ошибки, о которых сообщалось для вызова join_all из листинга 17-23. Изначально мы пытались переместить фьючерсы, созданные async-блоками, в Vec<Box<dyn Future<Output = ()>>>, но, как мы видели, эти фьючерсы могут иметь внутренние ссылки, поэтому они не автоматически реализуют Unpin. Как только мы закрепим их, мы можем передать получившийся тип Pin в Vec, будучи уверенными, что базовые данные в фьючерсе не будут перемещены. Листинг 17-24 показывает, как исправить код, вызывая макрос pin! там, где определяется каждый из трёх фьючерсов, и корректируя тип трейт-объекта.

extern crate trpl; // required for mdbook test

use std::pin::{Pin, pin};

// --snip--

use std::time::Duration;

fn main() {
    trpl::block_on(async {
        let (tx, mut rx) = trpl::channel();

        let tx1 = tx.clone();
        let tx1_fut = pin!(async move {
            // --snip--
            let vals = vec![
                String::from("hi"),
                String::from("from"),
                String::from("the"),
                String::from("future"),
            ];

            for val in vals {
                tx1.send(val).unwrap();
                trpl::sleep(Duration::from_secs(1)).await;
            }
        });

        let rx_fut = pin!(async {
            // --snip--
            while let Some(value) = rx.recv().await {
                println!("received '{value}'");
            }
        });

        let tx_fut = pin!(async move {
            // --snip--
            let vals = vec![
                String::from("more"),
                String::from("messages"),
                String::from("for"),
                String::from("you"),
            ];

            for val in vals {
                tx.send(val).unwrap();
                trpl::sleep(Duration::from_secs(1)).await;
            }
        });

        let futures: Vec<Pin<&mut dyn Future<Output = ()>>> =
            vec![tx1_fut, rx_fut, tx_fut];

        trpl::join_all(futures).await;
    });
}
Листинг 17-24: Закрепление фьючерсов, чтобы можно было переместить их в вектор

Этот пример теперь компилируется и выполняется, и мы могли бы добавлять или удалять фьючерсы из вектора во время выполнения и объединять их все.

Pin и Unpin в основном важны для создания низкоуровневых библиотек или при создании самой среды выполнения, а не для повседневного кода на Rust. Однако когда вы видите эти трейты в сообщениях об ошибках, теперь у вас будет лучшее представление о том, как исправить ваш код!

Примечание: эта комбинация Pin и Unpin позволяет безопасно реализовывать целый класс сложных типов в Rust, которые иначе оказались бы сложными, потому что они самоссылающиеся. Типы, требующие Pin, чаще всего появляются в асинхронном Rust сегодня, но время от времени вы можете увидеть их и в других контекстах.

Конкретные детали того, как работают Pin и Unpin, и правила, которые они должны соблюдать, подробно описаны в документации API для std::pin, поэтому если вам интересно узнать больше, это отличное место для начала.

Если вы хотите понять, как всё работает под капотом, ещё более подробно, см. главы 2 и 4 из Asynchronous Programming in Rust.

Трейт Stream

Теперь, когда у вас есть более глубокое понимание трейтов Future, Pin и Unpin, мы можем обратить наше внимание на трейт Stream. Как вы узнали ранее в главе, стримы (streams) похожи на асинхронные итераторы. В отличие от Iterator и Future, однако, Stream на момент написания не имеет определения в стандартной библиотеке, но есть очень распространённое определение из крейта futures, используемое во всей экосистеме.

Давайте рассмотрим определения трейтов Iterator и Future перед тем, как посмотреть, как трейт Stream мог бы объединить их вместе. Из Iterator у нас есть идея последовательности: его метод next предоставляет Option<Self::Item>. Из Future у нас есть идея готовности с течением времени: его метод poll предоставляет Poll<Self::Output>. Чтобы представить последовательность элементов, которые становятся готовыми с течением времени, мы определяем трейт Stream, который объединяет эти функции вместе:

#![allow(unused)]
fn main() {
use std::pin::Pin;
use std::task::{Context, Poll};

trait Stream {
    type Item;

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

Трейт Stream определяет ассоциированный тип с именем Item для типа элементов, производимых стримом. Это похоже на Iterator, где может быть от нуля до многих элементов, и не похоже на Future, где всегда один Output, даже если это единичный тип ().

Stream также определяет метод для получения этих элементов. Мы называем его poll_next, чтобы было ясно, что он опрашивает так же, как Future::poll, и производит последовательность элементов так же, как Iterator::next. Его тип возвращаемого значения объединяет Poll с Option. Внешний тип — Poll, потому что его нужно проверять на готовность, так же как фьючерс. Внутренний тип — Option, потому что нужно сигнализировать, есть ли ещё сообщения, так же как итератор делает.

Нечто очень похожее на это определение, вероятно, в конечном итоге станет частью стандартной библиотеки Rust. Тем временем оно является частью инструментария большинства сред выполнения, так что вы можете на него полагаться, и всё, что мы рассмотрим далее, должно в целом применяться!

В примерах, которые мы видели в разделе «Стримы: фьючерсы в последовательности», однако мы не использовали poll_next или Stream, а вместо этого использовали next и StreamExt. Мы могли бы работать напрямую в терминах API poll_next, вручную написав собственные конечные автоматы Stream, конечно, точно так же, как мы могли бы работать с фьючерсом напрямую через их метод poll. Использование await гораздо приятнее, однако, и трейт StreamExt предоставляет метод next, чтобы мы могли делать именно это:

#![allow(unused)]
fn main() {
use std::pin::Pin;
use std::task::{Context, Poll};

trait Stream {
    type Item;
    fn poll_next(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
    ) -> Poll<Option<Self::Item>>;
}

trait StreamExt: Stream {
    async fn next(&mut self) -> Option<Self::Item>
    where
        Self: Unpin;

    // другие методы...
}
}

Примечание: фактическое определение, которое мы использовали ранее в главе, выглядит немного иначе, потому что оно поддерживает версии Rust, которые ещё не поддерживали использование асинхронных функций в трейтах. В результате оно выглядит так:

fn next(&mut self) -> Next<'_, Self> where Self: Unpin;

Тип Next — это struct, который реализует Future и позволяет нам называть время жизни ссылки на self через Next<'_, Self>, чтобы await мог работать с этим методом.

Трейт StreamExt также является домом для всех интересных методов, доступных для использования со стримами. StreamExt автоматически реализуется для каждого типа, который реализует Stream, но эти трейты определены отдельно, чтобы позволить сообществу итерировать по удобным API, не влияя на фундаментальный трейт.

В версии StreamExt, используемой в крейте trpl, трейт не только определяет метод next, но также предоставляет реализацию next по умолчанию, которая правильно обрабатывает детали вызова Stream::poll_next. Это означает, что даже когда вам нужно написать свой собственный тип стрима, вам нужно реализовать только Stream, и тогда любой, кто использует ваш тип данных, может использовать StreamExt и его методы с ним автоматически.

Это всё, что мы собираемся рассмотреть о низкоуровневых деталях этих трейтов. Чтобы завершить, давайте рассмотрим, как фьючерсы (включая стримы), задачи и потоки выполнения все сочетаются друг с другом!