      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

    use futures_task::{LocalSpawn, Spawn};

    #[cfg(feature = "compat")]
    use crate::compat::Compat;

    #[cfg(feature = "channel")]
    #[cfg(feature = "std")]
    use crate::future::{FutureExt, RemoteHandle};
    #[cfg(feature = "alloc")]
    use alloc::boxed::Box;
    #[cfg(feature = "alloc")]
    use futures_core::future::Future;
    #[cfg(feature = "alloc")]
    use futures_task::{FutureObj, LocalFutureObj, SpawnError};

    impl<Sp: ?Sized> SpawnExt for Sp where Sp: Spawn {}
    impl<Sp: ?Sized> LocalSpawnExt for Sp where Sp: LocalSpawn {}

    /// Extension trait for `Spawn`.
    pub trait SpawnExt: Spawn {
        /// Spawns a task that polls the given future with output `()` to
        /// completion.
        ///
        /// This method returns a [`Result`] that contains a [`SpawnError`] if
        /// spawning fails.
        ///
        /// You can use [`spawn_with_handle`](SpawnExt::spawn_with_handle) if
        /// you want to spawn a future with output other than `()` or if you want
        /// to be able to await its completion.
        ///
        /// Note this method will eventually be replaced with the upcoming
        /// `Spawn::spawn` method which will take a `dyn Future` as input.
        /// Technical limitations prevent `Spawn::spawn` from being implemented
        /// today. Feel free to use this method in the meantime.
        ///
        /// ```
        /// use futures::executor::ThreadPool;
        /// use futures::task::SpawnExt;
        ///
        /// let executor = ThreadPool::new().unwrap();
        ///
        /// let future = async { /* ... */ };
        /// executor.spawn(future).unwrap();
        /// ```
        #[cfg(feature = "alloc")]
        fn spawn<Fut>(&self, future: Fut) -> Result<(), SpawnError>
        where
            Fut: Future<Output = ()> + Send + 'static,
        {
            self.spawn_obj(FutureObj::new(Box::new(future)))
        }

        /// Spawns a task that polls the given future to completion and returns a
        /// future that resolves to the spawned future's output.
        ///
        /// This method returns a [`Result`] that contains a [`RemoteHandle`](crate::future::RemoteHandle), or, if
        /// spawning fails, a [`SpawnError`]. [`RemoteHandle`](crate::future::RemoteHandle) is a future that
        /// resolves to the output of the spawned future.
        ///
        /// ```
        /// use futures::executor::{block_on, ThreadPool};
        /// use futures::future;
        /// use futures::task::SpawnExt;
        ///
        /// let executor = ThreadPool::new().unwrap();
        ///
        /// let future = future::ready(1);
        /// let join_handle_fut = executor.spawn_with_handle(future).unwrap();
        /// assert_eq!(block_on(join_handle_fut), 1);
        /// ```
        #[cfg(feature = "channel")]
        #[cfg_attr(docsrs, doc(cfg(feature = "channel")))]
        #[cfg(feature = "std")]
        fn spawn_with_handle<Fut>(&self, future: Fut) -> Result<RemoteHandle<Fut::Output>, SpawnError>
        where
            Fut: Future + Send + 'static,
            Fut::Output: Send,
        {
            let (future, handle) = future.remote_handle();
            self.spawn(future)?;
            Ok(handle)
        }

        /// Wraps a [`Spawn`] and makes it usable as a futures 0.1 `Executor`.
        /// Requires the `compat` feature to enable.
        #[cfg(feature = "compat")]
        #[cfg_attr(docsrs, doc(cfg(feature = "compat")))]
        fn compat(self) -> Compat<Self>
        where
            Self: Sized,
        {
            Compat::new(self)
        }
    }

    /// Extension trait for `LocalSpawn`.
    pub trait LocalSpawnExt: LocalSpawn {
        /// Spawns a task that polls the given future with output `()` to
        /// completion.
        ///
        /// This method returns a [`Result`] that contains a [`SpawnError`] if
        /// spawning fails.
        ///
        /// You can use [`spawn_with_handle`](SpawnExt::spawn_with_handle) if
        /// you want to spawn a future with output other than `()` or if you want
        /// to be able to await its completion.
        ///
        /// Note this method will eventually be replaced with the upcoming
        /// `Spawn::spawn` method which will take a `dyn Future` as input.
        /// Technical limitations prevent `Spawn::spawn` from being implemented
        /// today. Feel free to use this method in the meantime.
        ///
        /// ```
        /// use futures::executor::LocalPool;
        /// use futures::task::LocalSpawnExt;
        ///
        /// let executor = LocalPool::new();
        /// let spawner = executor.spawner();
        ///
        /// let future = async { /* ... */ };
        /// spawner.spawn_local(future).unwrap();
        /// ```
        #[cfg(feature = "alloc")]
        fn spawn_local<Fut>(&self, future: Fut) -> Result<(), SpawnError>
        where
            Fut: Future<Output = ()> + 'static,
        {
            self.spawn_local_obj(LocalFutureObj::new(Box::new(future)))
        }

        /// Spawns a task that polls the given future to completion and returns a
        /// future that resolves to the spawned future's output.
        ///
        /// This method returns a [`Result`] that contains a [`RemoteHandle`](crate::future::RemoteHandle), or, if
        /// spawning fails, a [`SpawnError`]. [`RemoteHandle`](crate::future::RemoteHandle) is a future that
        /// resolves to the output of the spawned future.
        ///
        /// ```
        /// use futures::executor::LocalPool;
        /// use futures::task::LocalSpawnExt;
        ///
        /// let mut executor = LocalPool::new();
        /// let spawner = executor.spawner();
        ///
        /// let future = async { 1 };
        /// let join_handle_fut = spawner.spawn_local_with_handle(future).unwrap();
        /// assert_eq!(executor.run_until(join_handle_fut), 1);
        /// ```
        #[cfg(feature = "channel")]
        #[cfg_attr(docsrs, doc(cfg(feature = "channel")))]
        #[cfg(feature = "std")]
        fn spawn_local_with_handle<Fut>(
            &self,
            future: Fut,
        ) -> Result<RemoteHandle<Fut::Output>, SpawnError>
        where
            Fut: Future + 'static,
        {
            let (future, handle) = future.remote_handle();
            self.spawn_local(future)?;
            Ok(handle)
        }
    }