1 use crate::runtime::handle::Handle;
2 use crate::runtime::{blocking, driver, Callback, Runtime};
9 /// Builds Tokio Runtime with custom configuration values.
12 /// Runtime is constructed by calling [`build`].
27 /// use tokio::runtime::Builder;
30 ///     // build runtime
31 ///     let runtime = Builder::new_multi_thread()
38 ///     // use runtime ...
42     /// Runtime type
55     /// The number of worker threads, used by Runtime.
63     /// Name fn used for threads spawned by the runtime.
66     /// Stack size used for threads spawned by the runtime.
103     /// How the runtime should respond to unhandled panics.
106     /// to configure the runtime behavior when a spawned task panics.
112         /// The runtime should ignore panics on spawned tasks.
122         /// use tokio::runtime::{self, UnhandledPanic};
125         /// let rt = runtime::Builder::new_current_thread()
149         /// The runtime should immediately shutdown if a spawned task panics.
151         /// The runtime will immediately shutdown even if the panicked task's
153         /// immediately dropped and call to [`Runtime::block_on`] will panic.
158         /// use tokio::runtime::{self, UnhandledPanic};
161         /// let rt = runtime::Builder::new_current_thread()
197     /// To spawn non-`Send` tasks on the resulting runtime, combine it with a
223     /// Returns a new runtime builder initialized with default configuration
248             thread_name: std::sync::Arc::new(|| "tokio-runtime-worker".into()),  in new()
284     /// use tokio::runtime;
286     /// let rt = runtime::Builder::new_multi_thread()
304     /// Sets the number of worker threads the `Runtime` will use.
315     /// When using the `current_thread` runtime this method has no effect.
319     /// ## Multi threaded runtime with 4 threads
322     /// use tokio::runtime;
324     /// // This will spawn a work-stealing runtime with 4 worker threads.
325     /// let rt = runtime::Builder::new_multi_thread()
333     /// ## Current thread runtime (will only run on the current thread via `Runtime::block_on`)
336     /// use tokio::runtime;
338     /// // Create a runtime that _must_ be driven from a call
339     /// // to `Runtime::block_on`.
340     /// let rt = runtime::Builder::new_current_thread()
344     /// // This will run the runtime and future on the current thread
358     /// Specifies the limit for additional threads spawned by the Runtime.
387     /// Sets name of threads spawned by the `Runtime`'s thread pool.
389     /// The default name is "tokio-runtime-worker".
394     /// # use tokio::runtime;
397     /// let rt = runtime::Builder::new_multi_thread()
408     /// Sets a function used to generate the name of threads spawned by the `Runtime`'s thread pool.
410     /// The default name fn is `|| "tokio-runtime-worker".into()`.
415     /// # use tokio::runtime;
418     /// let rt = runtime::Builder::new_multi_thread()
446     /// # use tokio::runtime;
449     /// let rt = runtime::Builder::new_multi_thread()
467     /// # use tokio::runtime;
469     /// let runtime = runtime::Builder::new_multi_thread()
492     /// # use tokio::runtime;
494     /// let runtime = runtime::Builder::new_multi_thread()
517     /// Note: There can only be one park callback for a runtime; calling this function
526     /// # use tokio::runtime;
532     /// let runtime = runtime::Builder::new_multi_thread()
546     /// runtime.block_on(async {
555     /// # use tokio::runtime;
561     /// let runtime = runtime::Builder::new_current_thread()
574     /// runtime.block_on(async {
592     /// more runtime threads to go idle.
594     /// Note: There can only be one unpark callback for a runtime; calling this function
600     /// # use tokio::runtime;
602     /// let runtime = runtime::Builder::new_multi_thread()
608     /// runtime.unwrap().block_on(async {
623     /// Creates the configured `Runtime`.
625     /// The returned `Runtime` instance is ready to spawn tasks.
630     /// use tokio::runtime::Builder;
635     ///     println!("Hello from the Tokio runtime");
638     pub fn build(&mut self) -> io::Result<Runtime> {  in build()  argument
668     /// # use tokio::runtime;
671     /// let rt = runtime::Builder::new_multi_thread()
701     /// # use tokio::runtime;
703     /// let rt = runtime::Builder::new_multi_thread()
733     /// # use tokio::runtime;
735     /// let rt = runtime::Builder::new_multi_thread()
746         /// Configure how the runtime responds to an unhandled panic on a
750         /// [`std::panic::catch_unwind`]) has no impact on the runtime's
757         ///   spawned tasks have no impact on the runtime's execution.
758         /// * `UnhandledPanic::ShutdownRuntime` will force the runtime to
762         ///   [`Runtime::block_on`] will panic.
772         /// The following demonstrates a runtime configured to shutdown on
773         /// panic. The first spawned task panics and results in the runtime
775         /// execute. The call to `block_on` will panic due to the runtime being
779         /// use tokio::runtime::{self, UnhandledPanic};
782         /// let rt = runtime::Builder::new_current_thread()
821         /// but the runtime is underutilized. Use tokio-rs/tokio-metrics to
834         /// use tokio::runtime;
836         /// let rt = runtime::Builder::new_multi_thread()
847         /// threads associated with the runtime being built.
849         /// This option is intended to make certain parts of the runtime
855         /// the runtime, the internals of Tokio and the Rust compiler may affect
864         /// # use tokio::runtime::{self, RngSeed};
867         /// let rt = runtime::Builder::new_current_thread()
880     fn build_current_thread_runtime(&mut self) -> io::Result<Runtime> {  in build_current_thread_runtime()  argument
881         use crate::runtime::scheduler::{self, CurrentThread};  in build_current_thread_runtime()
882         use crate::runtime::{runtime::Scheduler, Config};  in build_current_thread_runtime()
890         // Generate a rng seed for this runtime.  in build_current_thread_runtime()
919         Ok(Runtime::from_parts(  in build_current_thread_runtime()
932         /// the runtime.
937         /// use tokio::runtime;
939         /// let rt = runtime::Builder::new_multi_thread()
955         /// use tokio::runtime;
957         /// let rt = runtime::Builder::new_current_thread()
974         /// Doing this enables using `tokio::time` on the runtime.
979         /// use tokio::runtime;
981         /// let rt = runtime::Builder::new_multi_thread()
995         /// Controls if the runtime's clock starts paused or advancing.
997         /// Pausing time requires the current-thread runtime; construction of
998         /// the runtime will panic otherwise.
1003         /// use tokio::runtime;
1005         /// let rt = runtime::Builder::new_current_thread()
1020         fn build_threaded_runtime(&mut self) -> io::Result<Runtime> {
1022             use crate::runtime::{Config, runtime::Scheduler};
1023             use crate::runtime::scheduler::{self, MultiThread};
1034             // Generate a rng seed for this runtime.
1062             Ok(Runtime::from_parts(Scheduler::MultiThread(scheduler), handle, blocking_pool))