Структура Trace

Разрешает и возвращает список обратных трассировок, связанных с опросами в этой трассировке.

Точный набор включённых сюда обратных трассировок не гарантирован и может измениться в будущем, но можно ожидать по одному элементу Backtrace для каждого вызова poll нижнеуровневой будущей задачи Tokio; поэтому, если используется что-то вроде join!, для каждой будущей задачи в объединении будет своя обратная трассировка.

Выполняет функцию f в режиме трассировки и возвращает её результат вместе с полученной Trace.

Обычно в качестве f передают функцию опроса будущей задачи; возвращённая обратная трассировка покажет, чем занимается эта будущая задача.

Используйте вместо этого Handle::dump, если хотите узнать, чем заняты все задачи вашей программы. Дополнительные сведения о дампах см. также в Handle::dump; однако, в отличие от Handle::dump, эта функция не должна быть намного медленнее прямого вызова f.

Из-за особенностей реализации трассировки конечные будущие задачи Tokio обычно вместо выполнения своей фактической работы возвращают Poll::Pending, не регистрируя пробуждатель задачи ни в одном драйвере. Это означает, что выполнение, вероятно, не будет продвигаться, если в итоге не вызвать будущую задачу вне capture или явно не запланировать задачу повторно (например, вызвав cx.waker().wake_by_ref()) после возврата capture.

Пример использования:

use std::future::Future;
use std::task::Poll;
use tokio::runtime::dump::Trace;

// some future
let mut test_future = std::pin::pin!(async move { tokio::task::yield_now().await; 0 });

// trace it once, see what it's doing
let (trace, res) = Trace::root(std::future::poll_fn(|cx| {
    let (res, trace) = Trace::capture(|| test_future.as_mut().poll(cx));
    Poll::Ready((trace, res))
})).await;

// await it to let it finish, outside of a `capture`
let output = match res {
   Poll::Ready(output) => output,
   Poll::Pending => test_future.await,
};

println!("{trace}");

Вложенные вызовы

Вложенные вызовы capture могут возвращать частичные трассировки, но не приведут к другому нежелательному поведению (например, не вызовут панику).

Создаёт корень для стековых трассировок, полученных с помощью Trace::capture. Кадры стека выше корня не будут захвачены.

Допускается вкладывать несколько будущих задач Root. Захват остановится на первом корне. Также допустимо не использовать Root, но в этом случае нет гарантии, где остановится захват.

Возвращает аргумент без изменений.

Вызывает U::from(self).

Иными словами, это преобразование выполняет то, что выберет реализация From<T> for U.