      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
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
    257
    258
    259
    260
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270
    271
    272
    273
    274
    275
    276
    277
    278
    279
    280
    281
    282
    283
    284
    285
    286
    287
    288
    289
    290
    291
    292
    293
    294
    295
    296
    297
    298
    299
    300
    301
    302
    303
    304
    305
    306
    307
    308
    309
    310
    311
    312
    313
    314
    315
    316
    317
    318
    319
    320
    321
    322
    323
    324
    325
    326
    327
    328
    329
    330
    331
    332
    333
    334
    335
    336
    337
    338
    339
    340
    341
    342
    343
    344
    345
    346
    347
    348
    349
    350
    351
    352
    353
    354
    355
    356
    357
    358
    359
    360
    361
    362
    363
    364
    365
    366
    367
    368
    369
    370
    371
    372
    373
    374
    375
    376
    377
    378
    379
    380
    381
    382
    383
    384
    385
    386
    387
    388
    389
    390
    391
    392
    393
    394
    395
    396
    397
    398
    399
    400
    401
    402
    403
    404
    405
    406
    407
    408
    409
    410
    411
    412
    413
    414
    415
    416
    417
    418
    419
    420
    421
    422
    423
    424
    425
    426
    427
    428
    429
    430
    431
    432
    433
    434
    435
    436
    437
    438
    439
    440
    441
    442
    443
    444
    445
    446
    447
    448
    449
    450
    451
    452
    453
    454
    455
    456
    457
    458
    459
    460
    461
    462
    463
    464
    465
    466
    467
    468
    469
    470
    471
    472
    473
    474
    475
    476
    477
    478
    479
    480
    481
    482
    483
    484
    485
    486
    487
    488
    489
    490
    491
    492
    493
    494
    495
    496
    497
    498
    499
    500
    501
    502
    503
    504
    505
    506
    507
    508
    509
    510
    511
    512
    513
    514
    515
    516
    517
    518
    519
    520
    521
    522
    523
    524
    525
    526
    527
    528
    529
    530
    531
    532
    533
    534
    535
    536
    537
    538
    539
    540
    541
    542
    543
    544
    545
    546
    547
    548
    549
    550
    551
    552
    553
    554
    555
    556
    557
    558
    559
    560
    561
    562
    563

    //! The Tokio runtime.
    //!
    //! Unlike other Rust programs, asynchronous applications require runtime
    //! support. In particular, the following runtime services are necessary:
    //!
    //! * An **I/O event loop**, called the driver, which drives I/O resources and
    //!   dispatches I/O events to tasks that depend on them.
    //! * A **scheduler** to execute [tasks] that use these I/O resources.
    //! * A **timer** for scheduling work to run after a set period of time.
    //!
    //! Tokio's [`Runtime`] bundles all of these services as a single type, allowing
    //! them to be started, shut down, and configured together. However, often it is
    //! not required to configure a [`Runtime`] manually, and a user may just use the
    //! [`tokio::main`] attribute macro, which creates a [`Runtime`] under the hood.
    //!
    //! # Usage
    //!
    //! When no fine tuning is required, the [`tokio::main`] attribute macro can be
    //! used.
    //!
    //! ```no_run
    //! use tokio::net::TcpListener;
    //! use tokio::io::{AsyncReadExt, AsyncWriteExt};
    //!
    //! #[tokio::main]
    //! async fn main() -> Result<(), Box<dyn std::error::Error>> {
    //!     let listener = TcpListener::bind("127.0.0.1:8080").await?;
    //!
    //!     loop {
    //!         let (mut socket, _) = listener.accept().await?;
    //!
    //!         tokio::spawn(async move {
    //!             let mut buf = [0; 1024];
    //!
    //!             // In a loop, read data from the socket and write the data back.
    //!             loop {
    //!                 let n = match socket.read(&mut buf).await {
    //!                     // socket closed
    //!                     Ok(n) if n == 0 => return,
    //!                     Ok(n) => n,
    //!                     Err(e) => {
    //!                         println!("failed to read from socket; err = {:?}", e);
    //!                         return;
    //!                     }
    //!                 };
    //!
    //!                 // Write the data back
    //!                 if let Err(e) = socket.write_all(&buf[0..n]).await {
    //!                     println!("failed to write to socket; err = {:?}", e);
    //!                     return;
    //!                 }
    //!             }
    //!         });
    //!     }
    //! }
    //! ```
    //!
    //! From within the context of the runtime, additional tasks are spawned using
    //! the [`tokio::spawn`] function. Futures spawned using this function will be
    //! executed on the same thread pool used by the [`Runtime`].
    //!
    //! A [`Runtime`] instance can also be used directly.
    //!
    //! ```no_run
    //! use tokio::net::TcpListener;
    //! use tokio::io::{AsyncReadExt, AsyncWriteExt};
    //! use tokio::runtime::Runtime;
    //!
    //! fn main() -> Result<(), Box<dyn std::error::Error>> {
    //!     // Create the runtime
    //!     let rt  = Runtime::new()?;
    //!
    //!     // Spawn the root task
    //!     rt.block_on(async {
    //!         let listener = TcpListener::bind("127.0.0.1:8080").await?;
    //!
    //!         loop {
    //!             let (mut socket, _) = listener.accept().await?;
    //!
    //!             tokio::spawn(async move {
    //!                 let mut buf = [0; 1024];
    //!
    //!                 // In a loop, read data from the socket and write the data back.
    //!                 loop {
    //!                     let n = match socket.read(&mut buf).await {
    //!                         // socket closed
    //!                         Ok(n) if n == 0 => return,
    //!                         Ok(n) => n,
    //!                         Err(e) => {
    //!                             println!("failed to read from socket; err = {:?}", e);
    //!                             return;
    //!                         }
    //!                     };
    //!
    //!                     // Write the data back
    //!                     if let Err(e) = socket.write_all(&buf[0..n]).await {
    //!                         println!("failed to write to socket; err = {:?}", e);
    //!                         return;
    //!                     }
    //!                 }
    //!             });
    //!         }
    //!     })
    //! }
    //! ```
    //!
    //! ## Runtime Configurations
    //!
    //! Tokio provides multiple task scheduling strategies, suitable for different
    //! applications. The [runtime builder] or `#[tokio::main]` attribute may be
    //! used to select which scheduler to use.
    //!
    //! #### Multi-Thread Scheduler
    //!
    //! The multi-thread scheduler executes futures on a _thread pool_, using a
    //! work-stealing strategy. By default, it will start a worker thread for each
    //! CPU core available on the system. This tends to be the ideal configuration
    //! for most applications. The multi-thread scheduler requires the `rt-multi-thread`
    //! feature flag, and is selected by default:
    //! ```
    //! use tokio::runtime;
    //!
    //! # fn main() -> Result<(), Box<dyn std::error::Error>> {
    //! let threaded_rt = runtime::Runtime::new()?;
    //! # Ok(()) }
    //! ```
    //!
    //! Most applications should use the multi-thread scheduler, except in some
    //! niche use-cases, such as when running only a single thread is required.
    //!
    //! #### Current-Thread Scheduler
    //!
    //! The current-thread scheduler provides a _single-threaded_ future executor.
    //! All tasks will be created and executed on the current thread. This requires
    //! the `rt` feature flag.
    //! ```
    //! use tokio::runtime;
    //!
    //! # fn main() -> Result<(), Box<dyn std::error::Error>> {
    //! let basic_rt = runtime::Builder::new_current_thread()
    //!     .build()?;
    //! # Ok(()) }
    //! ```
    //!
    //! #### Resource drivers
    //!
    //! When configuring a runtime by hand, no resource drivers are enabled by
    //! default. In this case, attempting to use networking types or time types will
    //! fail. In order to enable these types, the resource drivers must be enabled.
    //! This is done with [`Builder::enable_io`] and [`Builder::enable_time`]. As a
    //! shorthand, [`Builder::enable_all`] enables both resource drivers.
    //!
    //! ## Lifetime of spawned threads
    //!
    //! The runtime may spawn threads depending on its configuration and usage. The
    //! multi-thread scheduler spawns threads to schedule tasks and for `spawn_blocking`
    //! calls.
    //!
    //! While the `Runtime` is active, threads may shutdown after periods of being
    //! idle. Once `Runtime` is dropped, all runtime threads are forcibly shutdown.
    //! Any tasks that have not yet completed will be dropped.
    //!
    //! [tasks]: crate::task
    //! [`Runtime`]: Runtime
    //! [`tokio::spawn`]: crate::spawn
    //! [`tokio::main`]: ../attr.main.html
    //! [runtime builder]: crate::runtime::Builder
    //! [`Runtime::new`]: crate::runtime::Runtime::new
    //! [`Builder::basic_scheduler`]: crate::runtime::Builder::basic_scheduler
    //! [`Builder::threaded_scheduler`]: crate::runtime::Builder::threaded_scheduler
    //! [`Builder::enable_io`]: crate::runtime::Builder::enable_io
    //! [`Builder::enable_time`]: crate::runtime::Builder::enable_time
    //! [`Builder::enable_all`]: crate::runtime::Builder::enable_all

    // At the top due to macros
    #[cfg(test)]
    #[macro_use]
    mod tests;

    pub(crate) mod enter;

    pub(crate) mod task;

    cfg_rt! {
        mod basic_scheduler;
        use basic_scheduler::BasicScheduler;

        mod blocking;
        use blocking::BlockingPool;
        pub(crate) use blocking::spawn_blocking;

        mod builder;
        pub use self::builder::Builder;

        pub(crate) mod context;
        pub(crate) mod driver;

        use self::enter::enter;

        mod handle;
        pub use handle::{EnterGuard, Handle};

        mod spawner;
        use self::spawner::Spawner;
    }

    cfg_rt_multi_thread! {
        mod park;
        use park::Parker;
    }

    cfg_rt_multi_thread! {
        mod queue;

        pub(crate) mod thread_pool;
        use self::thread_pool::ThreadPool;
    }

    cfg_rt! {
        use crate::task::JoinHandle;

        use std::future::Future;
        use std::time::Duration;

        /// The Tokio runtime.
        ///
        /// The runtime provides an I/O driver, task scheduler, [timer], and
        /// blocking pool, necessary for running asynchronous tasks.
        ///
        /// Instances of `Runtime` can be created using [`new`], or [`Builder`].
        /// However, most users will use the `#[tokio::main]` annotation on their
        /// entry point instead.
        ///
        /// See [module level][mod] documentation for more details.
        ///
        /// # Shutdown
        ///
        /// Shutting down the runtime is done by dropping the value. The current
        /// thread will block until the shut down operation has completed.
        ///
        /// * Drain any scheduled work queues.
        /// * Drop any futures that have not yet completed.
        /// * Drop the reactor.
        ///
        /// Once the reactor has dropped, any outstanding I/O resources bound to
        /// that reactor will no longer function. Calling any method on them will
        /// result in an error.
        ///
        /// # Sharing
        ///
        /// The Tokio runtime implements `Sync` and `Send` to allow you to wrap it
        /// in a `Arc`. Most fn take `&self` to allow you to call them concurrently
        /// accross multiple threads.
        ///
        /// Calls to `shutdown` and `shutdown_timeout` require exclusive ownership of
        /// the runtime type and this can be achieved via `Arc::try_unwrap` when only
        /// one strong count reference is left over.
        ///
        /// [timer]: crate::time
        /// [mod]: index.html
        /// [`new`]: method@Self::new
        /// [`Builder`]: struct@Builder
        #[derive(Debug)]
        pub struct Runtime {
            /// Task executor
            kind: Kind,

            /// Handle to runtime, also contains driver handles
            handle: Handle,

            /// Blocking pool handle, used to signal shutdown
            blocking_pool: BlockingPool,
        }

        /// The runtime executor is either a thread-pool or a current-thread executor.
        #[derive(Debug)]
        enum Kind {
            /// Execute all tasks on the current-thread.
            CurrentThread(BasicScheduler<driver::Driver>),

            /// Execute tasks across multiple threads.
            #[cfg(feature = "rt-multi-thread")]
            ThreadPool(ThreadPool),
        }

        /// After thread starts / before thread stops
        type Callback = std::sync::Arc<dyn Fn() + Send + Sync>;

        impl Runtime {
            /// Create a new runtime instance with default configuration values.
            ///
            /// This results in the multi threaded scheduler, I/O driver, and time driver being
            /// initialized.
            ///
            /// Most applications will not need to call this function directly. Instead,
            /// they will use the  [`#[tokio::main]` attribute][main]. When a more complex
            /// configuration is necessary, the [runtime builder] may be used.
            ///
            /// See [module level][mod] documentation for more details.
            ///
            /// # Examples
            ///
            /// Creating a new `Runtime` with default configuration values.
            ///
            /// ```
            /// use tokio::runtime::Runtime;
            ///
            /// let rt = Runtime::new()
            ///     .unwrap();
            ///
            /// // Use the runtime...
            /// ```
            ///
            /// [mod]: index.html
            /// [main]: ../attr.main.html
            /// [threaded scheduler]: index.html#threaded-scheduler
            /// [basic scheduler]: index.html#basic-scheduler
            /// [runtime builder]: crate::runtime::Builder
            #[cfg(feature = "rt-multi-thread")]
            #[cfg_attr(docsrs, doc(cfg(feature = "rt-multi-thread")))]
            pub fn new() -> std::io::Result<Runtime> {
                Builder::new_multi_thread().enable_all().build()
            }

            /// Return a handle to the runtime's spawner.
            ///
            /// The returned handle can be used to spawn tasks that run on this runtime, and can
            /// be cloned to allow moving the `Handle` to other threads.
            ///
            /// # Examples
            ///
            /// ```
            /// use tokio::runtime::Runtime;
            ///
            /// let rt = Runtime::new()
            ///     .unwrap();
            ///
            /// let handle = rt.handle();
            ///
            /// // Use the handle...
            /// ```
            pub fn handle(&self) -> &Handle {
                &self.handle
            }

            /// Spawn a future onto the Tokio runtime.
            ///
            /// This spawns the given future onto the runtime's executor, usually a
            /// thread pool. The thread pool is then responsible for polling the future
            /// until it completes.
            ///
            /// See [module level][mod] documentation for more details.
            ///
            /// [mod]: index.html
            ///
            /// # Examples
            ///
            /// ```
            /// use tokio::runtime::Runtime;
            ///
            /// # fn dox() {
            /// // Create the runtime
            /// let rt = Runtime::new().unwrap();
            ///
            /// // Spawn a future onto the runtime
            /// rt.spawn(async {
            ///     println!("now running on a worker thread");
            /// });
            /// # }
            /// ```
            #[cfg_attr(tokio_track_caller, track_caller)]
            pub fn spawn<F>(&self, future: F) -> JoinHandle<F::Output>
            where
                F: Future + Send + 'static,
                F::Output: Send + 'static,
            {
                self.handle.spawn(future)
            }

            /// Run the provided function on an executor dedicated to blocking operations.
            ///
            /// # Examples
            ///
            /// ```
            /// use tokio::runtime::Runtime;
            ///
            /// # fn dox() {
            /// // Create the runtime
            /// let rt = Runtime::new().unwrap();
            ///
            /// // Spawn a blocking function onto the runtime
            /// rt.spawn_blocking(|| {
            ///     println!("now running on a worker thread");
            /// });
            /// # }
            #[cfg_attr(tokio_track_caller, track_caller)]
            pub fn spawn_blocking<F, R>(&self, func: F) -> JoinHandle<R>
            where
                F: FnOnce() -> R + Send + 'static,
                R: Send + 'static,
            {
                self.handle.spawn_blocking(func)
            }

            /// Run a future to completion on the Tokio runtime. This is the
            /// runtime's entry point.
            ///
            /// This runs the given future on the runtime, blocking until it is
            /// complete, and yielding its resolved result. Any tasks or timers
            /// which the future spawns internally will be executed on the runtime.
            ///
            /// # Multi thread scheduler
            ///
            /// When the multi thread scheduler is used this will allow futures
            /// to run within the io driver and timer context of the overall runtime.
            ///
            /// # Current thread scheduler
            ///
            /// When the current thread scheduler is enabled `block_on`
            /// can be called concurrently from multiple threads. The first call
            /// will take ownership of the io and timer drivers. This means
            /// other threads which do not own the drivers will hook into that one.
            /// When the first `block_on` completes, other threads will be able to
            /// "steal" the driver to allow continued execution of their futures.
            ///
            /// # Panics
            ///
            /// This function panics if the provided future panics, or if called within an
            /// asynchronous execution context.
            ///
            /// # Examples
            ///
            /// ```no_run
            /// use tokio::runtime::Runtime;
            ///
            /// // Create the runtime
            /// let rt  = Runtime::new().unwrap();
            ///
            /// // Execute the future, blocking the current thread until completion
            /// rt.block_on(async {
            ///     println!("hello");
            /// });
            /// ```
            ///
            /// [handle]: fn@Handle::block_on
            pub fn block_on<F: Future>(&self, future: F) -> F::Output {
                let _enter = self.enter();

                match &self.kind {
                    Kind::CurrentThread(exec) => exec.block_on(future),
                    #[cfg(feature = "rt-multi-thread")]
                    Kind::ThreadPool(exec) => exec.block_on(future),
                }
            }

            /// Enter the runtime context.
            ///
            /// This allows you to construct types that must have an executor
            /// available on creation such as [`Sleep`] or [`TcpStream`]. It will
            /// also allow you to call methods such as [`tokio::spawn`].
            ///
            /// [`Sleep`]: struct@crate::time::Sleep
            /// [`TcpStream`]: struct@crate::net::TcpStream
            /// [`tokio::spawn`]: fn@crate::spawn
            ///
            /// # Example
            ///
            /// ```
            /// use tokio::runtime::Runtime;
            ///
            /// fn function_that_spawns(msg: String) {
            ///     // Had we not used `rt.enter` below, this would panic.
            ///     tokio::spawn(async move {
            ///         println!("{}", msg);
            ///     });
            /// }
            ///
            /// fn main() {
            ///     let rt = Runtime::new().unwrap();
            ///
            ///     let s = "Hello World!".to_string();
            ///
            ///     // By entering the context, we tie `tokio::spawn` to this executor.
            ///     let _guard = rt.enter();
            ///     function_that_spawns(s);
            /// }
            /// ```
            pub fn enter(&self) -> EnterGuard<'_> {
                self.handle.enter()
            }

            /// Shutdown the runtime, waiting for at most `duration` for all spawned
            /// task to shutdown.
            ///
            /// Usually, dropping a `Runtime` handle is sufficient as tasks are able to
            /// shutdown in a timely fashion. However, dropping a `Runtime` will wait
            /// indefinitely for all tasks to terminate, and there are cases where a long
            /// blocking task has been spawned, which can block dropping `Runtime`.
            ///
            /// In this case, calling `shutdown_timeout` with an explicit wait timeout
            /// can work. The `shutdown_timeout` will signal all tasks to shutdown and
            /// will wait for at most `duration` for all spawned tasks to terminate. If
            /// `timeout` elapses before all tasks are dropped, the function returns and
            /// outstanding tasks are potentially leaked.
            ///
            /// # Examples
            ///
            /// ```
            /// use tokio::runtime::Runtime;
            /// use tokio::task;
            ///
            /// use std::thread;
            /// use std::time::Duration;
            ///
            /// fn main() {
            ///    let runtime = Runtime::new().unwrap();
            ///
            ///    runtime.block_on(async move {
            ///        task::spawn_blocking(move || {
            ///            thread::sleep(Duration::from_secs(10_000));
            ///        });
            ///    });
            ///
            ///    runtime.shutdown_timeout(Duration::from_millis(100));
            /// }
            /// ```
            pub fn shutdown_timeout(mut self, duration: Duration) {
                // Wakeup and shutdown all the worker threads
                self.handle.spawner.shutdown();
                self.blocking_pool.shutdown(Some(duration));
            }

            /// Shutdown the runtime, without waiting for any spawned tasks to shutdown.
            ///
            /// This can be useful if you want to drop a runtime from within another runtime.
            /// Normally, dropping a runtime will block indefinitely for spawned blocking tasks
            /// to complete, which would normally not be permitted within an asynchronous context.
            /// By calling `shutdown_background()`, you can drop the runtime from such a context.
            ///
            /// Note however, that because we do not wait for any blocking tasks to complete, this
            /// may result in a resource leak (in that any blocking tasks are still running until they
            /// return.
            ///
            /// This function is equivalent to calling `shutdown_timeout(Duration::of_nanos(0))`.
            ///
            /// ```
            /// use tokio::runtime::Runtime;
            ///
            /// fn main() {
            ///    let runtime = Runtime::new().unwrap();
            ///
            ///    runtime.block_on(async move {
            ///        let inner_runtime = Runtime::new().unwrap();
            ///        // ...
            ///        inner_runtime.shutdown_background();
            ///    });
            /// }
            /// ```
            pub fn shutdown_background(self) {
                self.shutdown_timeout(Duration::from_nanos(0))
            }
        }
    }