Структура Builder

pub struct Builder { /* private fields */ }

Доступно только при включённой возможности crate rt.

Создаёт среду выполнения Tokio с пользовательскими значениями конфигурации.

Методы можно объединять в цепочки для задания значений конфигурации. Среда выполнения создаётся вызовом build.

Новые экземпляры Builder можно получить с помощью Builder::new_multi_thread или Builder::new_current_thread.

Подробные сведения о различных параметрах конфигурации см. в документации к соответствующим функциям.

Примеры

use tokio::runtime::Builder;

fn main() {
    // build runtime
    let runtime = Builder::new_multi_thread()
        .worker_threads(4)
        .thread_name("my-custom-name")
        .thread_stack_size(3 * 1024 * 1024)
        .build()
        .unwrap();

    // use runtime ...
}

Реализации

impl Builder

pub fn new_current_thread() -> Builder

Возвращает новый builder с выбранным планировщиком для текущего потока.

Методы конфигурации можно вызывать цепочкой для возвращаемого значения.

Чтобы создавать задачи, не являющиеся Send, в полученной среде выполнения, объедините её с LocalSet или вызовите build_local, чтобы создать LocalRuntime.

pub fn new_multi_thread() -> Builder

Доступно только при включённой функции crate rt-multi-thread.

Возвращает новый builder с выбранным многопоточным планировщиком.

Методы конфигурации можно вызывать цепочкой для возвращаемого значения.

pub fn enable_all(&mut self) -> &mut Self

Включает драйверы ввода-вывода и времени.

Это краткая форма отдельных вызовов enable_io и enable_time. Если в будущем в Tokio будут добавлены другие компоненты, enable_all будет включать и эти новые компоненты.

Примеры

use tokio::runtime;

let rt = runtime::Builder::new_multi_thread()
    .enable_all()
    .build()
    .unwrap();

pub fn enable_alt_timer(&mut self) -> &mut Self

Доступно только при tokio_unstable и включённых функциях crate rt-multi-thread и time.

Включает альтернативную реализацию таймера, отключённую по умолчанию.

Альтернативная реализация таймера — это нестабильная функция, которая может повысить производительность многопоточных сред выполнения с большим количеством рабочих потоков.

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

Нажмите здесь, чтобы поделиться впечатлениями об альтернативном таймере

Примеры

use tokio::runtime;

let rt = runtime::Builder::new_multi_thread()
  .enable_alt_timer()
  .build()
  .unwrap();

pub fn enable_eager_driver_handoff(&mut self) -> &mut Self

Доступно только при tokio_unstable и включённой функции crate rt-multi-thread.

Включает упреждающую передачу драйверов ввода-вывода и времени в многопоточных средах выполнения; по умолчанию она отключена.

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

По умолчанию этот параметр отключён, поскольку его включение может увеличить конкуренцию из-за дополнительной синхронизации при междрайверном пробуждении.

Примечание: это нестабильный API. Упреждающая передача драйверов — экспериментальная функция, поведение которой может быть изменено или удалено в выпусках 1.x. Подробнее см. в документации по нестабильным функциям.

pub fn worker_threads(&mut self, val: usize) -> &mut Self

Задаёт число рабочих потоков, которые будет использовать Runtime.

Можно указать любое число больше 0, однако рекомендуется выбирать небольшое значение.

Это переопределит значение, полученное из переменной среды TOKIO_WORKER_THREADS.

По умолчанию

По умолчанию используется число ядер, доступных системе.

При использовании среды выполнения current_thread этот метод не действует.

Примеры

Многопоточная среда выполнения с 4 потоками

use tokio::runtime;

// This will spawn a work-stealing runtime with 4 worker threads.
let rt = runtime::Builder::new_multi_thread()
    .worker_threads(4)
    .build()
    .unwrap();

rt.spawn(async move {});

Среда выполнения для текущего потока (будет работать только в текущем потоке через `Runtime::block_on`)

use tokio::runtime;

// Create a runtime that _must_ be driven from a call
// to `Runtime::block_on`.
let rt = runtime::Builder::new_current_thread()
    .build()
    .unwrap();

// This will run the runtime and future on the current thread
rt.block_on(async move {});

Паника

Это приведёт к панике, если val не больше 0.

pub fn max_blocking_threads(&mut self, val: usize) -> &mut Self

Задаёт ограничение на количество дополнительных потоков, создаваемых средой выполнения.

Эти потоки используются для блокирующих операций, например задач, запущенных через spawn_blocking. К ним относятся, в частности:

операции fs
разрешение DNS-имён через ToSocketAddrs
запись в Stdout или Stderr
чтение из Stdin

В отличие от worker_threads, они не всегда активны и завершают работу, если простаивают слишком долго. Длительность этого ожидания можно изменить с помощью thread_keep_alive.

Рекомендуется не задавать слишком низкое ограничение, чтобы избежать зависания при выполнении операций, требующих spawn_blocking.

Значение по умолчанию — 512.

Поведение очереди

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

Паника

Произойдёт паника, если val не больше 0.

Переход с версии 0.x

В старых версиях max_threads ограничивал как блокирующие потоки, так и рабочие потоки, однако текущий max_blocking_threads не учитывает асинхронные рабочие потоки.

pub fn thread_name(&mut self, val: impl Into<String>) -> &mut Self

Задаёт имя потоков, создаваемых пулом потоков Runtime.

Имя по умолчанию — “tokio-rt-worker”.

Примеры


let rt = runtime::Builder::new_multi_thread()
    .thread_name("my-pool")
    .build();

pub fn name(&mut self, val: impl Into<String>) -> &mut Self

Задаёт имя среды выполнения.

Примеры


let rt = runtime::Builder::new_multi_thread()
    .name("my-runtime")
    .build();

Паника

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

pub fn thread_name_fn<F>(&mut self, f: F) -> &mut Self
where F: Fn() -> String + Send + Sync + 'static,

Задаёт функцию для формирования имён потоков, создаваемых пулом потоков Runtime.

По умолчанию используется функция имени || "tokio-rt-worker".into().

Примеры

let rt = runtime::Builder::new_multi_thread()
    .thread_name_fn(|| {
       static ATOMIC_ID: AtomicUsize = AtomicUsize::new(0);
       let id = ATOMIC_ID.fetch_add(1, Ordering::SeqCst);
       format!("my-pool-{}", id)
    })
    .build();

pub fn thread_stack_size(&mut self, val: usize) -> &mut Self

Задаёт размер стека (в байтах) для рабочих потоков.

Фактический размер стека может превышать это значение, если платформа устанавливает минимальный размер стека.

Размер стека по умолчанию для создаваемых потоков составляет 2 МиБ, однако в будущем это конкретное значение может измениться.

Примеры


let rt = runtime::Builder::new_multi_thread()
    .thread_stack_size(32 * 1024)
    .build();

pub fn on_thread_start<F>(&mut self, f: F) -> &mut Self
where F: Fn() + Send + Sync + 'static,

Выполняет функцию f после запуска каждого потока, но до начала его работы.

Предназначено для задач учёта и мониторинга.

Примеры

let runtime = runtime::Builder::new_multi_thread()
    .on_thread_start(|| {
        println!("thread started");
    })
    .build();

pub fn on_thread_stop<F>(&mut self, f: F) -> &mut Self
where F: Fn() + Send + Sync + 'static,

Выполняет функцию f перед остановкой каждого потока.

Предназначено для учета и мониторинга.

Примеры

{
let runtime = runtime::Builder::new_multi_thread()
    .on_thread_stop(|| {
        println!("thread stopping");
    })
    .build();

pub fn on_thread_park<F>(&mut self, f: F) -> &mut Self
where F: Fn() + Send + Sync + 'static,

Выполняет функцию f непосредственно перед тем, как поток будет приостановлен (перейдет в состояние ожидания). f вызывается в контексте Tokio, поэтому можно вызывать такие функции, как tokio::spawn, что может привести к немедленному возобновлению работы этого потока.

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

Примечание: для среды выполнения может быть задан только один callback приостановки; повторный вызов этой функции заменяет последний заданный callback, а не добавляет новый.

Примеры

Многопоточный исполнитель

let once = AtomicBool::new(true);
let barrier = Arc::new(Barrier::new(2));

let runtime = runtime::Builder::new_multi_thread()
    .worker_threads(1)
    .on_thread_park({
        let barrier = barrier.clone();
        move || {
            let barrier = barrier.clone();
            if once.swap(false, Ordering::Relaxed) {
                tokio::spawn(async move { barrier.wait().await; });
           }
        }
    })
    .build()
    .unwrap();

runtime.block_on(async {
   barrier.wait().await;
})

Исполнитель в текущем потоке

let once = AtomicBool::new(true);
let barrier = Arc::new(Barrier::new(2));

let runtime = runtime::Builder::new_current_thread()
    .on_thread_park({
        let barrier = barrier.clone();
        move || {
            let barrier = barrier.clone();
            if once.swap(false, Ordering::Relaxed) {
                tokio::spawn(async move { barrier.wait().await; });
           }
        }
    })
    .build()
    .unwrap();

runtime.block_on(async {
   barrier.wait().await;
})

pub fn on_thread_unpark<F>(&mut self, f: F) -> &mut Self
where F: Fn() + Send + Sync + 'static,

Выполняет функцию f сразу после возобновления работы потока (начала выполнения задач).

Предназначено для учета и мониторинга; обратите внимание, что выполнение этого callback увеличит задержки, если приложение позволило одному или нескольким потокам среды выполнения перейти в состояние ожидания.

Примечание: для среды выполнения может быть задан только один callback возобновления; повторный вызов этой функции заменяет последний заданный callback, а не добавляет новый.

Примеры

let runtime = runtime::Builder::new_multi_thread()
    .on_thread_unpark(|| {
        println!("thread unparking");
    })
    .build();

runtime.unwrap().block_on(async {
   tokio::task::yield_now().await;
   println!("Hello from Tokio!");
})

pub fn on_task_spawn<F>(&mut self, f: F) -> &mut Self
where F: Fn(&TaskMeta<'_>) + Send + Sync + 'static,

Доступно только на tokio_unstable.

Выполняет функцию f непосредственно перед запуском задачи.

f вызывается в контексте Tokio, поэтому можно вызывать такие функции, как tokio::spawn, что может привести к немедленному вызову этого callback.

Это можно использовать для учета или мониторинга.

Примечание: для среды выполнения может быть задан только один callback запуска; повторный вызов этой функции заменяет последний заданный callback, а не добавляет новый.

В настоящее время эта функция не поддерживает LocalSet.

Примечание: это нестабильный API. Публичный API этого типа может измениться в выпусках 1.x. Подробности см. в документации по нестабильным функциям.

Примеры

let runtime = runtime::Builder::new_current_thread()
    .on_task_spawn(|_| {
        println!("spawning task");
    })
    .build()
    .unwrap();

runtime.block_on(async {
    tokio::task::spawn(std::future::ready(()));

    for _ in 0..64 {
        tokio::task::yield_now().await;
    }
})

pub fn on_before_task_poll<F>(&mut self, f: F) -> &mut Self
where F: Fn(&TaskMeta<'_>) + Send + Sync + 'static,

Доступно только на tokio_unstable.

Выполняет функцию f непосредственно перед опросом задачи.

Примеры

let poll_start_counter = Arc::new(AtomicUsize::new(0));
let poll_start = poll_start_counter.clone();
let rt = tokio::runtime::Builder::new_multi_thread()
    .enable_all()
    .on_before_task_poll(move |meta| {
        println!("task {} is about to be polled", meta.id())
    })
    .build()
    .unwrap();
let task = rt.spawn(async {
    yield_now().await;
});
let _ = rt.block_on(task);

pub fn on_after_task_poll<F>(&mut self, f: F) -> &mut Self
where F: Fn(&TaskMeta<'_>) + Send + Sync + 'static,

Доступно только на tokio_unstable.

Вызывает функцию f сразу после опроса задачи

f вызывается в контексте Tokio, поэтому можно вызывать такие функции, как tokio::spawn, что может привести к немедленному вызову этого обратного вызова.

Примечание: это нестабильный API. Публичный API этого типа может измениться в выпусках 1.x. Подробнее см. в документации по нестабильным функциям.

Примеры

let poll_stop_counter = Arc::new(AtomicUsize::new(0));
let poll_stop = poll_stop_counter.clone();
let rt = tokio::runtime::Builder::new_multi_thread()
    .enable_all()
    .on_after_task_poll(move |meta| {
        println!("task {} completed polling", meta.id());
    })
    .build()
    .unwrap();
let task = rt.spawn(async {
    yield_now().await;
});
let _ = rt.block_on(task);

pub fn on_task_terminate<F>(&mut self, f: F) -> &mut Self
where F: Fn(&TaskMeta<'_>) + Send + Sync + 'static,

Доступно только на tokio_unstable.

Вызывает функцию f сразу после завершения задачи.

f вызывается в контексте Tokio, поэтому можно вызывать такие функции, как tokio::spawn.

Это можно использовать для учёта или мониторинга.

Примечание: для среды выполнения может быть задан только один обратный вызов при завершении задачи; повторный вызов этой функции заменяет ранее заданный обратный вызов, а не добавляет новый.

В настоящее время это не поддерживает LocalSet.

Примеры

let runtime = runtime::Builder::new_current_thread()
    .on_task_terminate(|_| {
        println!("killing task");
    })
    .build()
    .unwrap();

runtime.block_on(async {
    tokio::task::spawn(std::future::ready(()));

    for _ in 0..64 {
        tokio::task::yield_now().await;
    }
})

pub fn build(&mut self) -> Result<Runtime>

Создаёт настроенную Runtime.

Возвращённый экземпляр Runtime готов к запуску задач.

Примеры

use tokio::runtime::Builder;

let rt  = Builder::new_multi_thread().build().unwrap();

rt.block_on(async {
    println!("Hello from the Tokio runtime");
});

pub fn build_local(&mut self, options: LocalOptions) -> Result<LocalRuntime>

Создаёт настроенную LocalRuntime.

Возвращённый экземпляр LocalRuntime готов к запуску задач.

Паника

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

Примеры

use tokio::runtime::{Builder, LocalOptions};

let rt = Builder::new_current_thread()
    .build_local(LocalOptions::default())
    .unwrap();

rt.spawn_local(async {
    println!("Hello from the Tokio runtime");
});

pub fn thread_keep_alive(&mut self, duration: Duration) -> &mut Self

Задаёт пользовательский тайм-аут для потока в пуле блокирующих операций.

По умолчанию тайм-аут потока составляет 10 секунд. Его можно изменить с помощью .thread_keep_alive().

Пример

let rt = runtime::Builder::new_multi_thread()
    .thread_keep_alive(Duration::from_millis(100))
    .build();

pub fn global_queue_interval(&mut self, val: u32) -> &mut Self

Задает количество тактов планировщика, после которого планировщик будет опрашивать глобальную очередь задач.

«Такт» планировщика примерно соответствует одному вызову poll для задачи.

По умолчанию интервал глобальной очереди для планировщика с одним потоком равен 31. Поведение планировщика с несколькими потоками по умолчанию описано в документации модуля.

У планировщиков есть локальная очередь уже выбранных задач и глобальная очередь поступающих задач. Уменьшение интервала повышает справедливость планировщика ценой увеличения накладных расходов на синхронизацию. Это может быть полезно для приоритизации начала выполнения новых задач, особенно если задачи часто уступают управление, а не завершаются или не ожидают дальнейшего ввода-вывода. Значение интервала 1 дает приоритет глобальной очереди, и задачи из локальной очереди будут выполняться только тогда, когда глобальная очередь пуста. И наоборот, большее значение отдает приоритет уже выполняющейся работе и хорошо подходит, если большинство задач быстро завершают опрос.

Панические сбои

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

Примеры

let rt = runtime::Builder::new_multi_thread()
    .global_queue_interval(31)
    .build();

pub fn event_interval(&mut self, val: u32) -> &mut Self

Задает количество тактов планировщика, после которого планировщик будет опрашивать внешние события (таймеры, ввод-вывод и т. д.).

«Такт» планировщика примерно соответствует одному вызову poll для задачи.

По умолчанию интервал событий равен 61 для всех типов планировщика.

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

Панические сбои

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

Примеры

let rt = runtime::Builder::new_multi_thread()
    .event_interval(31)
    .build();

pub fn unhandled_panic(&mut self, behavior: UnhandledPanic) -> &mut Self

Доступно только на tokio_unstable.

Настраивает реакцию среды выполнения на необработанную панику в запущенной задаче.

По умолчанию необработанная паника (то есть паника, не перехваченная с помощью std::panic::catch_unwind) не влияет на выполнение среды выполнения. Значение ошибки паники передается в JoinHandle задачи, а все остальные запущенные задачи продолжают выполняться.

Параметр unhandled_panic позволяет настроить это поведение.

UnhandledPanic::Ignore — поведение по умолчанию. Паники в запущенных задачах не влияют на выполнение среды выполнения.
UnhandledPanic::ShutdownRuntime заставляет среду выполнения немедленно завершиться, когда в запущенной задаче возникает паника, даже если JoinHandle этой задачи еще не был отброшен. Все остальные запущенные задачи немедленно завершатся, а последующие вызовы Runtime::block_on вызовут панику.

Панические сбои

Этот метод вызовет панику, если передать UnhandledPanic::ShutdownRuntime среде выполнения, отличной от среды выполнения с одним потоком.

Нестабильный API

В настоящее время этот параметр нестабилен, а его реализация не завершена. API может измениться или быть удален в будущем. Подробнее см. в задаче tokio-rs/tokio#4516.

Примеры

В следующем примере показана среда выполнения, настроенная на завершение при панике. Первая запущенная задача вызывает панику, в результате чего среда выполнения завершается. Вторая запущенная задача так и не получает возможности выполниться. Вызов block_on вызовет панику, поскольку среда выполнения была принудительно завершена.

use tokio::runtime::{self, UnhandledPanic};

let rt = runtime::Builder::new_current_thread()
    .unhandled_panic(UnhandledPanic::ShutdownRuntime)
    .build()
    .unwrap();

rt.spawn(async { panic!("boom"); });
rt.spawn(async {
    // This task never completes.
});

rt.block_on(async {
    // Do some work
})

pub fn disable_lifo_slot(&mut self) -> &mut Self

Доступно только на tokio_unstable.

Отключает эвристику планировщика задач LIFO.

Планировщик с несколькими потоками использует эвристику для оптимизации шаблонов обмена сообщениями. Благодаря этой эвристике последняя запланированная задача опрашивается первой.

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

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

Попробуйте использовать этот параметр, если время «запланированного» состояния задачи велико, но среда выполнения недогружена. Для сбора этих данных используйте tokio-rs/tokio-metrics.

Нестабильный API

Этот параметр считается обходным решением проблемы с тем, что задачи нельзя забирать из слота LIFO. Когда задачи из слота можно будет забирать, мы пересмотрим необходимость этого параметра. См. задачу tokio-rs/tokio#4941.

Примеры

use tokio::runtime;

let rt = runtime::Builder::new_multi_thread()
    .disable_lifo_slot()
    .build()
    .unwrap();

pub fn rng_seed(&mut self, seed: RngSeed) -> &mut Self

Доступно только на tokio_unstable.

Задаёт начальное значение генератора случайных чисел, используемое во всех потоках, связанных с создаваемой средой выполнения.

Эта настройка предназначена для обеспечения детерминированного поведения некоторых частей среды выполнения (например, макроса tokio::select!). В случае с tokio::select! она гарантирует, что порядок опроса ветвей будет детерминированным.

Помимо кода, задающего rng_seed и взаимодействующего со средой выполнения, на последовательности случайных чисел могут влиять внутренние механизмы Tokio и компилятор Rust. Чтобы обеспечить воспроизводимость результатов, версии Tokio, всех остальных зависимостей, взаимодействующих с Tokio, и компилятора Rust также должны оставаться неизменными.

Примеры

let seed = RngSeed::from_bytes(b"place your seed here");
let rt = runtime::Builder::new_current_thread()
    .rng_seed(seed)
    .build();

pub fn enable_metrics_poll_time_histogram(&mut self) -> &mut Self

Доступно только на tokio_unstable.

Включает сбор данных о распределении времени опроса задач.

По умолчанию время опроса задач не измеряется, поскольку для этого требуется дважды вызывать Instant::now() при каждом опросе задачи, что может привести к заметным накладным расходам. Для доступа к данным метрик используйте Handle::metrics().

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

По умолчанию используется линейная гистограмма из 10 интервалов шириной по 100 микросекунд каждый. Она занимает очень мало памяти, но может не обеспечивать достаточную детализацию. Чтобы повысить детализацию при небольшом расходе памяти, используйте metrics_poll_time_histogram_configuration(), чтобы выбрать LogHistogram.

Примеры

use tokio::runtime;

let rt = runtime::Builder::new_multi_thread()
    .enable_metrics_poll_time_histogram()
    .build()
    .unwrap();

pub fn metrics_poll_count_histogram_scale( &mut self, histogram_scale: HistogramScale, ) -> &mut Self

👎Устарело:

используйте metrics_poll_time_histogram_configuration

Доступно только на tokio_unstable.

Задаёт масштаб гистограммы для отслеживания распределения времени опроса задач.

Распределение времени опроса задач можно отслеживать с помощью линейной или логарифмической шкалы. При использовании линейной шкалы каждый интервал гистограммы охватывает одинаковый диапазон времени опроса. При использовании логарифмической шкалы каждый следующий интервал охватывает диапазон вдвое больше предыдущего.

По умолчанию: линейная шкала.

Примеры

use tokio::runtime::{self, HistogramScale};

let rt = runtime::Builder::new_multi_thread()
    .enable_metrics_poll_time_histogram()
    .metrics_poll_count_histogram_scale(HistogramScale::Log)
    .build()
    .unwrap();

pub fn metrics_poll_time_histogram_configuration( &mut self, configuration: HistogramConfiguration, ) -> &mut Self

Доступно только на tokio_unstable.

Настраивает гистограмму для отслеживания времени опроса

Примеры

Настройка LogHistogram с конфигурацией по умолчанию:

use tokio::runtime;
use tokio::runtime::{HistogramConfiguration, LogHistogram};

let rt = runtime::Builder::new_multi_thread()
    .enable_metrics_poll_time_histogram()
    .metrics_poll_time_histogram_configuration(
        HistogramConfiguration::log(LogHistogram::default())
    )
    .build()
    .unwrap();

Настройка линейной гистограммы из 100 интервалов шириной по 10 мкс каждый

use tokio::runtime;
use std::time::Duration;
use tokio::runtime::HistogramConfiguration;

let rt = runtime::Builder::new_multi_thread()
    .enable_metrics_poll_time_histogram()
    .metrics_poll_time_histogram_configuration(
        HistogramConfiguration::linear(Duration::from_micros(10), 100)
    )
    .build()
    .unwrap();

Настройка LogHistogram со следующими параметрами:

Измерение времени от 100 нс до 120 с
Максимальная погрешность — 0,1
Не более 1024 интервалов

use std::time::Duration;
use tokio::runtime;
use tokio::runtime::{HistogramConfiguration, LogHistogram};

let rt = runtime::Builder::new_multi_thread()
    .enable_metrics_poll_time_histogram()
    .metrics_poll_time_histogram_configuration(
        HistogramConfiguration::log(LogHistogram::builder()
            .max_value(Duration::from_secs(120))
            .min_value(Duration::from_nanos(100))
            .max_error(0.1)
            .max_buckets(1024)
            .expect("configuration uses 488 buckets")
        )
    )
    .build()
    .unwrap();

При переходе с устаревшей гистограммы (HistogramScale::Log) и необходимости сохранить прежнее поведение используйте precision_exact(0). В результате создаётся гистограмма, в которой размер каждого интервала вдвое больше предыдущего.

use std::time::Duration;
use tokio::runtime::{HistogramConfiguration, LogHistogram};
let rt = tokio::runtime::Builder::new_current_thread()
    .enable_all()
    .enable_metrics_poll_time_histogram()
    .metrics_poll_time_histogram_configuration(HistogramConfiguration::log(
        LogHistogram::builder()
            .min_value(Duration::from_micros(20))
            .max_value(Duration::from_millis(4))
            // Set `precision_exact` to `0` to match `HistogramScale::Log`
            .precision_exact(0)
            .max_buckets(10)
            .unwrap(),
    ))
    .build()
    .unwrap();

pub fn metrics_poll_count_histogram_resolution( &mut self, resolution: Duration, ) -> &mut Self

👎Устарело:

используйте metrics_poll_time_histogram_configuration

Доступно только при tokio_unstable.

Задаёт разрешение гистограммы для отслеживания распределения времени опроса задач.

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

Обратите внимание: при использовании логарифмической шкалы разрешение округляется вверх до ближайшей степени 2 в наносекундах.

По умолчанию: 100 микросекунд.

Примеры

use tokio::runtime;
use std::time::Duration;

let rt = runtime::Builder::new_multi_thread()
    .enable_metrics_poll_time_histogram()
    .metrics_poll_count_histogram_resolution(Duration::from_micros(100))
    .build()
    .unwrap();

pub fn metrics_poll_count_histogram_buckets( &mut self, buckets: usize, ) -> &mut Self

👎Устарело:

используйте metrics_poll_time_histogram_configuration

Доступно только при tokio_unstable.

Задаёт количество интервалов гистограммы, отслеживающей распределение времени опроса задач.

Последний интервал учитывает все значения, превышающие диапазоны остальных интервалов. Например, если настроить гистограмму с линейной шкалой, разрешением 50 мс и 10 интервалами, десятый интервал будет учитывать опросы задач, выполнение которых занимает более 450 мс.

По умолчанию: 10

Примеры

use tokio::runtime;

let rt = runtime::Builder::new_multi_thread()
    .enable_metrics_poll_time_histogram()
    .metrics_poll_count_histogram_buckets(15)
    .build()
    .unwrap();

impl Builder

pub fn enable_io(&mut self) -> &mut Self

Доступно только при функции crate net или tokio_unstable и Linux и функции crate fs и функции crate io-uring и функции crate rt, или Unix и функции crate process, или Unix и функции crate signal.

Включает драйвер ввода-вывода.

Это позволяет использовать в среде выполнения типы net, process, signal и некоторые типы ввода-вывода.

Примеры

use tokio::runtime;

let rt = runtime::Builder::new_multi_thread()
    .enable_io()
    .build()
    .unwrap();

pub fn max_io_events_per_tick(&mut self, capacity: usize) -> &mut Self

Включает драйвер ввода-вывода и задаёт максимальное количество событий для обработки за один тик.

Примеры

use tokio::runtime;

let rt = runtime::Builder::new_current_thread()
    .enable_io()
    .max_io_events_per_tick(1024)
    .build()
    .unwrap();

impl Builder

pub fn enable_time(&mut self) -> &mut Self

Доступно только при функции crate time.

Включает драйвер времени.

Это позволяет использовать tokio::time в среде выполнения.

Примеры

use tokio::runtime;

let rt = runtime::Builder::new_multi_thread()
    .enable_time()
    .build()
    .unwrap();

impl Builder

pub fn enable_io_uring(&mut self) -> &mut Self

Доступно только при функции crate io-uring.

Включает драйвер io_uring в tokio.

Это позволяет использовать операции io_uring в среде выполнения.

Примеры

use tokio::runtime;

let rt = runtime::Builder::new_multi_thread()
    .enable_io_uring()
    .build()
    .unwrap();

impl Builder

pub fn start_paused(&mut self, start_paused: bool) -> &mut Self

Доступно только при функции crate test-util.

Определяет, будут ли часы среды выполнения запущены на паузе или идти.

Для приостановки времени требуется среда выполнения в текущем потоке; в противном случае создание среды выполнения приведёт к панике.

Примеры

use tokio::runtime;

let rt = runtime::Builder::new_current_thread()
    .enable_time()
    .start_paused(true)
    .build()
    .unwrap();

impl Builder

pub fn enable_metrics_schedule_latency_histogram(&mut self) -> &mut Self

Доступно только при включённой функции crate schedule-latency.

Включает отслеживание распределения задержек при планировании задач. Задержка при планировании задачи — это время между планированием задачи для выполнения и её опросом.

Эта функция поддерживается только на 64-разрядных целевых платформах.

По умолчанию задержки при планировании задач не измеряются, поскольку для этого требуется вызывать Instant::now() при планировании задачи и при её опросе, что может создавать измеримую дополнительную нагрузку. Используйте Handle::metrics(), чтобы получить доступ к данным метрик.

По умолчанию используется линейная гистограмма с 10 корзинами шириной 100 микросекунд каждая. Она занимает очень мало памяти, но может не обеспечивать достаточную детализацию. Для повышения детализации при низком потреблении памяти используйте metrics_schedule_latency_histogram_configuration(), чтобы выбрать LogHistogram.

Примеры

use tokio::runtime;

let rt = runtime::Builder::new_multi_thread()
    .enable_metrics_schedule_latency_histogram()
    .build()
    .unwrap();

pub fn metrics_schedule_latency_histogram_configuration( &mut self, configuration: HistogramConfiguration, ) -> &mut Self

Доступно только при включённой функции crate schedule-latency.

Настраивает гистограмму для отслеживания задержек при планировании задач.

Чтобы эта функция имела эффект, необходимо включить отслеживание задержек при планировании задач с помощью enable_metrics_schedule_latency_histogram().

Примеры

Настройте LogHistogram с [конфигурацией по умолчанию]:

use tokio::runtime;
use tokio::runtime::{HistogramConfiguration, LogHistogram};

let rt = runtime::Builder::new_multi_thread()
    .enable_metrics_schedule_latency_histogram()
    .metrics_schedule_latency_histogram_configuration(
        HistogramConfiguration::log(LogHistogram::default())
    )
    .build()
    .unwrap();

Настройте линейную гистограмму со 100 корзинами шириной 10 мкс каждая

use tokio::runtime;
use std::time::Duration;
use tokio::runtime::HistogramConfiguration;

let rt = runtime::Builder::new_multi_thread()
    .enable_metrics_schedule_latency_histogram()
    .metrics_schedule_latency_histogram_configuration(
        HistogramConfiguration::linear(Duration::from_micros(10), 100)
    )
    .build()
    .unwrap();

Настройте LogHistogram со следующими параметрами:

Измерять время от 100 нс до 120 с
Максимальная погрешность — 0,1
Не более 1024 корзин

use std::time::Duration;
use tokio::runtime;
use tokio::runtime::{HistogramConfiguration, LogHistogram};

let rt = runtime::Builder::new_multi_thread()
    .enable_metrics_schedule_latency_histogram()
    .metrics_schedule_latency_histogram_configuration(
        HistogramConfiguration::log(LogHistogram::builder()
            .max_value(Duration::from_secs(120))
            .min_value(Duration::from_nanos(100))
            .max_error(0.1)
            .max_buckets(1024)
            .expect("configuration uses 488 buckets")
        )
    )
    .build()
    .unwrap();

Реализации трейтов

impl Debug for Builder

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Форматирует значение с помощью указанного форматировщика. Подробнее

Автоматические реализации трейтов

impl !Freeze for Builder

impl !RefUnwindSafe for Builder

impl !UnwindSafe for Builder

impl Send for Builder

impl Sync for Builder

impl Unpin for Builder

impl UnsafeUnpin for Builder

Обобщённые реализации

impl<T> Any for T
where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

Получает TypeId для self. Подробнее

impl<T> Borrow<T> for T
where T: ?Sized,

fn borrow(&self) -> &T

Неизменяемо заимствует значение, принадлежащее владельцу. Подробнее

impl<T> BorrowMut<T> for T
where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

Изменяемо заимствует значение, принадлежащее владельцу. Подробнее

impl<T> From<T> for T

fn from(t: T) -> T

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

impl<T> Instrument for T

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Инструментирует этот тип с помощью указанного Span, возвращая обёртку Instrumented. Подробнее

fn in_current_span(self) -> Instrumented<Self> ⓘ

Инструментирует этот тип с помощью текущего Span, возвращая обёртку Instrumented. Подробнее

impl<T, U> Into for T
where U: From<T>,

fn into(self) -> U

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

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

impl<T, U> TryFrom for T
where U: Into<T>,

type Error = Infallible

Тип, возвращаемый в случае ошибки преобразования.

fn try_from(value: U) -> Result<T, <T as TryFrom>::Error>

Выполняет преобразование.

impl<T, U> TryInto for T
where U: TryFrom<T>,

type Error = >::Error

Тип, возвращаемый в случае ошибки преобразования.

fn try_into(self) -> Result<U, >::Error>

Выполняет преобразование.

impl<T> WithSubscriber for T

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Присоединяет предоставленный Subscriber к этому типу и возвращает обёртку WithDispatch. Подробнее

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Присоединяет текущий используемый по умолчанию Subscriber к этому типу и возвращает обёртку WithDispatch. Подробнее

Структура Builder

Примеры

Реализации

impl Builder

pub fn new_current_thread() -> Builder

pub fn new_multi_thread() -> Builder

pub fn enable_all(&mut self) -> &mut Self

Примеры

pub fn enable_alt_timer(&mut self) -> &mut Self

Примеры

pub fn enable_eager_driver_handoff(&mut self) -> &mut Self

pub fn worker_threads(&mut self, val: usize) -> &mut Self

По умолчанию

Примеры

Многопоточная среда выполнения с 4 потоками

Среда выполнения для текущего потока (будет работать только в текущем потоке через Runtime::block_on)

Паника

pub fn max_blocking_threads(&mut self, val: usize) -> &mut Self

Поведение очереди

Паника

Переход с версии 0.x

pub fn thread_name(&mut self, val: impl Into<String>) -> &mut Self

Примеры

pub fn name(&mut self, val: impl Into<String>) -> &mut Self

Примеры

Паника

pub fn thread_name_fn<F>(&mut self, f: F) -> &mut Selfwhere F: Fn() -> String + Send + Sync + 'static,

Примеры

pub fn thread_stack_size(&mut self, val: usize) -> &mut Self

Примеры

pub fn on_thread_start<F>(&mut self, f: F) -> &mut Selfwhere F: Fn() + Send + Sync + 'static,

Примеры

pub fn on_thread_stop<F>(&mut self, f: F) -> &mut Selfwhere F: Fn() + Send + Sync + 'static,

Примеры

pub fn on_thread_park<F>(&mut self, f: F) -> &mut Selfwhere F: Fn() + Send + Sync + 'static,

Примеры

Многопоточный исполнитель

Исполнитель в текущем потоке

pub fn on_thread_unpark<F>(&mut self, f: F) -> &mut Selfwhere F: Fn() + Send + Sync + 'static,

Примеры

pub fn on_task_spawn<F>(&mut self, f: F) -> &mut Selfwhere F: Fn(&TaskMeta<'_>) + Send + Sync + 'static,

Примеры

pub fn on_before_task_poll<F>(&mut self, f: F) -> &mut Selfwhere F: Fn(&TaskMeta<'_>) + Send + Sync + 'static,

Примеры

pub fn on_after_task_poll<F>(&mut self, f: F) -> &mut Selfwhere F: Fn(&TaskMeta<'_>) + Send + Sync + 'static,

Примеры

pub fn on_task_terminate<F>(&mut self, f: F) -> &mut Selfwhere F: Fn(&TaskMeta<'_>) + Send + Sync + 'static,

Примеры

pub fn build(&mut self) -> Result<Runtime>

Примеры

pub fn build_local(&mut self, options: LocalOptions) -> Result<LocalRuntime>

Паника

Примеры

pub fn thread_keep_alive(&mut self, duration: Duration) -> &mut Self

Пример

pub fn global_queue_interval(&mut self, val: u32) -> &mut Self

Панические сбои

Примеры

pub fn event_interval(&mut self, val: u32) -> &mut Self

Панические сбои

Примеры

pub fn unhandled_panic(&mut self, behavior: UnhandledPanic) -> &mut Self

Панические сбои

Нестабильный API

Примеры

pub fn disable_lifo_slot(&mut self) -> &mut Self

Нестабильный API

Примеры

pub fn rng_seed(&mut self, seed: RngSeed) -> &mut Self

Примеры

pub fn enable_metrics_poll_time_histogram(&mut self) -> &mut Self

Примеры

pub fn metrics_poll_count_histogram_scale( &mut self, histogram_scale: HistogramScale, ) -> &mut Self

Примеры

pub fn metrics_poll_time_histogram_configuration( &mut self, configuration: HistogramConfiguration, ) -> &mut Self

Примеры

pub fn metrics_poll_count_histogram_resolution( &mut self, resolution: Duration, ) -> &mut Self

Примеры

pub fn metrics_poll_count_histogram_buckets( &mut self, buckets: usize, ) -> &mut Self

Примеры

Среда выполнения для текущего потока (будет работать только в текущем потоке через `Runtime::block_on`)

pub fn thread_name_fn<F>(&mut self, f: F) -> &mut Self
where F: Fn() -> String + Send + Sync + 'static,

pub fn on_thread_start<F>(&mut self, f: F) -> &mut Self
where F: Fn() + Send + Sync + 'static,

pub fn on_thread_stop<F>(&mut self, f: F) -> &mut Self
where F: Fn() + Send + Sync + 'static,

pub fn on_thread_park<F>(&mut self, f: F) -> &mut Self
where F: Fn() + Send + Sync + 'static,

pub fn on_thread_unpark<F>(&mut self, f: F) -> &mut Self
where F: Fn() + Send + Sync + 'static,

pub fn on_task_spawn<F>(&mut self, f: F) -> &mut Self
where F: Fn(&TaskMeta<'_>) + Send + Sync + 'static,

pub fn on_before_task_poll<F>(&mut self, f: F) -> &mut Self
where F: Fn(&TaskMeta<'_>) + Send + Sync + 'static,

pub fn on_after_task_poll<F>(&mut self, f: F) -> &mut Self
where F: Fn(&TaskMeta<'_>) + Send + Sync + 'static,

pub fn on_task_terminate<F>(&mut self, f: F) -> &mut Self
where F: Fn(&TaskMeta<'_>) + Send + Sync + 'static,

impl<T> Any for T
where T: 'static + ?Sized,

impl<T> Borrow<T> for T
where T: ?Sized,

impl<T> BorrowMut<T> for T
where T: ?Sized,

impl<T, U> Into<U> for T
where U: From<T>,

impl<T, U> TryFrom<U> for T
where U: Into<T>,

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,