some_executor 0.7.2

// SPDX-License-Identifier: MIT OR Apache-2.0
/*!

# some_executor

![logo](https://github.com/drewcrawford/some_executor/raw/main/art/logo.png)

Rust made the terrible mistake of not having an async executor in std.  Worse, there is no
trait for executors to implement, and no API for async code to expect.  So everyone writes
their code against one specific executor, and it's always tokio.  But tokio has too many
drawbacks to be the universal choice, and the other executors are too cumbersome to be
practical.  Async rust is stuck in limbo.

There are many proposals to fix this.  This one's mine.

`some_executor` is a small crate that sits between the code that *has* futures and the code
that *runs* them:

* **If you spawn futures**, you get one obvious `spawn` that works on "some" executor: a
  generic argument, a stored trait object, the executor your caller is already running on,
  or a program-wide global.  Whichever you pick, you get back an observer you can await,
  poll, detach, or drop to cancel.
* **If you write an executor**, you implement one trait, and cancellation, task-locals,
  observers, priorities and hints are done for you.  You get to focus on scheduling.
* **If you write async code**, you get the featureset that (in my opinion) is table stakes for
  async rust: cancellation, task-locals, priorities, execution hints, task IDs and labels.
  They work the same on every executor, because the executor doesn't implement them; this
  crate does.

There is also a built-in fallback executor, so all of this works out of the box.  It is not
good, but it is always there; when you want a real one, see the reference executors below.

# Quick start

```
use some_executor::SomeExecutor;
use some_executor::current_executor::current_executor;
use some_executor::observer::FinishedObservation;
use some_executor::task::{Configuration, Task};

# // Runs on the event loop on wasm32 and blocks natively.  It cannot be a plain
# // block_on: on the browser main thread that would starve the event loop the
# // fallback executor needs to start its worker.  See "Crossing from sync into async".
# wasm_lite_std::async_doctest!(async {
// A Task is a future plus a label and some scheduling metadata.
let task = Task::without_notifications(
    "add".to_string(),
    Configuration::default(),
    async { 2 + 2 },
);

// Spawn it on whatever executor is current: the one this task is running on,
// else the thread's, else the global one, else the built-in fallback.
let mut executor = current_executor();
let observer = executor.spawn(task);

// The observer is a Future.  Dropping it instead would cancel the task.
match observer.await {
    FinishedObservation::Ready(value) => assert_eq!(value, 4),
    FinishedObservation::Cancelled => unreachable!(),
}
# });
```

The rest of this page is organized by what you are trying to do.

# Spawning tasks

Every path to spawning starts with a [`Task`]: your future, a `String` label, and a
[`Configuration`].  Then pick how you want to get hold of an executor.

| You want to...                                            | Use                                                                        |
|-----------------------------------------------------------|----------------------------------------------------------------------------|
| Take an executor as a generic argument and monomorphize   | [`SomeExecutorExt`] (or [`StaticExecutorExt`], [`LocalExecutorExt`])       |
| Store an executor in a struct, erasing its type           | [`DynExecutor`], [`DynStaticExecutor`], [`SomeLocalExecutor`]              |
| Borrow the executor your caller is already running on     | [`current_executor`], or [`Task::spawn_current`] for fire-and-forget       |
| Use the executor pinned to this thread                    | [`thread_executor`], [`thread_static_executor`], [`thread_local_executor`] |
| Spawn from nowhere in particular (a signal handler, say)  | [`global_executor`]                                                        |

Whichever you use, `spawn` returns an [`Observer`] (usually a [`TypedObserver`]):

* `.await` it to get a [`FinishedObservation`]: the task's output, or `Cancelled`.
* Call [`observe`](Observer::observe) to peek without waiting.
* Call [`detach`](Observer::detach) to let the task run to completion unobserved.
* Drop it to request cancellation.  Cancellation is cooperative: the task sees it through
  [`IS_CANCELLED`], and executors may stop polling.

## Which executor is "current"?

[`current_executor`] walks a fixed hierarchy and always returns something:

1. The executor the current task was spawned on ([`TASK_EXECUTOR`]).
2. The executor set for this thread with [`set_thread_executor`].
3. The program-wide executor set with [`set_global_executor`].
4. The built-in fallback executor.

The fallback executor exists so that libraries built on this crate work with zero
configuration.  It prints a warning when used, because it is not production quality; install
a real one (see [reference executors](#reference-executors)) with [`set_global_executor`] or
[`set_thread_executor`].  Set `SOME_EXECUTOR_BUILTIN_SHOULD_PANIC=1` to make the fallback
panic instead, which is a good way to find places you forgot to do that.

## Three flavors of executor

Executors differ in what futures they can accept.  This crate models the three cases that
come up in practice, each with a generic (`*Ext`) trait for static dispatch and an object-safe
base trait for dynamic dispatch:

| Futures are...              | Object-safe trait                       | Generic trait          | Typical executor                              |
|-----------------------------|-----------------------------------------|------------------------|-----------------------------------------------|
| `Send + 'static`            | [`SomeExecutor`] (see [`DynExecutor`])  | [`SomeExecutorExt`]    | Thread pools; anything that moves work        |
| `'static`, not `Send`       | [`SomeStaticExecutor`] (see [`DynStaticExecutor`]) | [`StaticExecutorExt`] | Main-thread and single-threaded executors; wasm |
| Neither (`'a` and `!Send`)  | [`SomeLocalExecutor`]                   | [`LocalExecutorExt`]   | Executors scoped to a stack frame             |

The `Send` and static flavors are cloneable, like a channel sender, and can be discovered
through [`current_executor`] and friends.  Local executors are borrowed and cannot be
cloned; the [`SomeLocalExecutor`] docs explain the lifetime parameter and why.  If you
don't know which you need, start with [`SomeExecutor`].

## Configuring a task

[`Configuration`] (build one with [`ConfigurationBuilder`]) carries three things an
executor may use, and none of them changes what your future does:

* A [`Hint`]: is this task expected to be I/O-bound, CPU-bound, or unknown?
* A [`Priority`], for executors that schedule by priority.
* A `poll_after` [`Instant`], before which the executor must not poll the task.

Every task also has a label and a [`TaskID`], both visible from inside the task and from its
observer, which makes tracing and logging across executors practical.

## Reference executors

These crates implement the traits above and are the ones I actually use:

* [some_global_executor](https://sealedabstract.com/code/some_global_executor) is a
  thread-pool executor for `Send` tasks.  It runs on OS threads natively and on web workers
  on wasm32, and can install itself as the thread or global executor.  If you want one
  executor to replace the built-in fallback, this is it.
* [some_local_executor](https://sealedabstract.com/code/some_local_executor) is a local
  executor that runs its tasks on the current thread and can also receive tasks from other
  threads.
* [test_executors](https://sealedabstract.com/code/test_executors) provides toy executors good
  enough for unit tests.

# Crossing from sync into async

Every program crosses from sync into async exactly once: in `fn main`, in a test, in a CLI
tool, at an FFI callback.  Which API you want depends on whether you are *choosing* an
executor or *using* one.

Choosing is [`ExecutorMain`].  It is the trait spelling of "construct the chosen backend,
install it, run this future", so that an `#[some_executor::main(SomeBackend)]` attribute can
expand to something that compiles against a backend the macro has never heard of.  It returns
`()` rather than the future's output, which is what makes it implementable on the wasm32 main
thread as well as natively.

Using is [`SomeExecutor::block_on`].  Given an executor -- including the one
[`current_executor`] hands you -- it drives a future to completion and returns its output,
blocking the calling thread:

```
use some_executor::SomeExecutor;
use some_executor::current_executor::current_executor;

# // A doctest runs on the browser main thread, which cannot block; on wasm32 this
# // runs the body on a worker, where it can.  Natively it just calls the closure.
# wasm_lite_std::worker_doctest!(|| {
let mut executor = current_executor();
assert_eq!(executor.block_on(async { 2 + 2 }), 4);
# });
```

Underneath both is the free [`block_on`](fn@block_on) function, which polls a future in place
on the calling thread with no executor involved.  Because the future never leaves the thread,
it needs neither `Send` nor `'static` and may borrow from the stack -- unlike spawning:

```
# wasm_lite_std::worker_doctest!(|| {
let name = String::from("world");
let greeting = some_executor::block_on(async { format!("hello {}", name.as_str()) });
assert_eq!(greeting, "hello world");
# });
```

Blocking is not universally available, which is why the entry point and the primitive are
separate.  It works whenever the blocking thread can keep driving every scheduler the future
depends on: another thread is doing the work, or the executor owns its own loop and runs it
here.  It cannot work when the wakeups come from a scheduler this thread can only run by
unwinding -- the browser main thread, where the JavaScript event loop delivers every timer,
promise and worker message.  [`block_on`](fn@block_on) panics there with an explanation
rather than hanging the tab; a wasm32 worker has no such problem, and [`ExecutorMain`] is the
portable choice for an entry point.

# Writing async code

Mostly, write the code you want to write.  Nothing here requires you to know which executor
you are running on.  What you get on top:

* [`task_local!`] declares task-local storage, comparable to `thread_local!` or tokio's
  `task_local!`, with `scope`, `get`, `set` and immutable (`static const`) variants.
* Built-in task-locals describe the current task: [`TASK_ID`], [`TASK_LABEL`],
  [`TASK_PRIORITY`], and [`IS_CANCELLED`].
* [`IS_CANCELLED`] lets long-running work notice a cancellation request and return early.
* [`TASK_EXECUTOR`] and [`TASK_STATIC_EXECUTOR`] hold the executor a task was spawned on, which
  is how [`current_executor`] and [`Task::spawn_current`] find it.

```
use some_executor::task_local;
use some_executor::task::{TASK_LABEL, IS_CANCELLED};

task_local! {
    static REQUEST_ID: u64;
}

async fn handle() {
    let label = TASK_LABEL.with(|l| l.cloned());
    let request = REQUEST_ID.get();
    // Do a unit of work, then check for cancellation before the next one.
    if IS_CANCELLED.with(|c| c.map(|c| c.is_cancelled()).unwrap_or(false)) {
        return;
    }
    let _ = (label, request);
}
```

# Implementing an executor

An executor is anything that accepts a [`Task`] and polls it.  In outline:

1. Implement [`SomeExecutor`] (for `Send` futures), [`SomeStaticExecutor`] (for `'static`,
   `!Send` futures) and/or [`SomeLocalExecutor`] (for borrowed futures).  Add the matching
   `*Ext` marker trait if your executor is `Clone`.
2. In your `spawn`, call [`Task::spawn`] (or `spawn_static` / `spawn_local`) with `&mut self`.
   You get back a [`SpawnedTask`] to schedule and an observer to hand to the caller.
3. Poll the spawned task.  Its `poll` takes an executor context so that
   [`current_executor`] works inside the task; the spawned task itself installs task-locals,
   reports completion to the observer, and stops early on cancellation.
4. Respect [`poll_after`]: do not poll before that instant.  Sleep, defer, re-queue,
   whatever fits your design.  This is the main gotcha.
5. Optionally implement [`ExecutorNotified`] to be told when a task's observer requests
   cancellation, so you can drop it early instead of discovering that on the next poll.
6. Optionally register yourself with [`set_thread_executor`] / [`set_global_executor`] (or the
   static and local equivalents) so that [`current_executor`] finds you.
7. If your executor runs tasks on the calling thread, override
   [`SomeExecutor::block_on_objsafe`].  The default parks the caller, which is correct for a
   thread pool and a deadlock for a current-thread executor; run your own polling loop until
   the future resolves instead.  Implement [`ExecutorMain`] too, so `#[some_executor::main]`
   can name you.

For static executors, [`static_support`] provides [`OwnedSomeStaticExecutorErasingNotifier`]
to erase your notifier type into the common [`DynStaticExecutor`] shape.  For the object-safe
methods (`spawn_objsafe` and friends), the `ObjSafe*` and `Boxed*` type aliases at the crate
root spell out the erased types so you don't have to.

# Compared with `executor-trait`

One way to understand this crate is as an alternative to
[executor-trait](https://crates.io/crates/executor-trait/).  I like it a lot; here is why I
made this instead:

1. To support futures whose output isn't `()`.
2. To avoid boxing futures where it isn't necessary.
3. To carry hints and priorities to the executor.
4. To provide task-locals and the other features async code actually needs.
5. To support cancellation much more robustly.

Philosophically, `executor-trait` ships the lowest common denominator that every executor can
support.  This crate ships the **highest common denominator that all async code can use**,
together with **polyfills and fallbacks so every executor can offer it**, even ones that don't
support a feature natively.  It is straightforward to implement either crate's API in terms
of the other, so the two can be used together.

# wasm32

`wasm32-unknown-unknown` is a first-class target, with and without atomics.  Timing uses
[`Instant`], which is `std::time::Instant` natively and a web-clock on wasm, and the fallback
executor schedules through the browser event loop.

# Status

This interface is unstable and may change.

[`Task`]: task::Task
[`Task::spawn`]: task::Task::spawn
[`Task::spawn_current`]: task::Task::spawn_current
[`TaskID`]: task::TaskID
[`SpawnedTask`]: task::SpawnedTask
[`Configuration`]: task::Configuration
[`ConfigurationBuilder`]: task::ConfigurationBuilder
[`Observer`]: observer::Observer
[`TypedObserver`]: observer::TypedObserver
[`FinishedObservation`]: observer::FinishedObservation
[`ExecutorNotified`]: observer::ExecutorNotified
[`current_executor`]: current_executor::current_executor
[`thread_executor`]: thread_executor::thread_executor
[`thread_static_executor`]: thread_executor::thread_static_executor
[`thread_local_executor`]: thread_executor::thread_local_executor
[`set_thread_executor`]: thread_executor::set_thread_executor
[`global_executor`]: global_executor::global_executor
[`set_global_executor`]: global_executor::set_global_executor
[`OwnedSomeStaticExecutorErasingNotifier`]: static_support::OwnedSomeStaticExecutorErasingNotifier
[`poll_after`]: task::Task::poll_after
[`TASK_ID`]: task::TASK_ID
[`TASK_LABEL`]: task::TASK_LABEL
[`TASK_PRIORITY`]: task::TASK_PRIORITY
[`TASK_EXECUTOR`]: task::TASK_EXECUTOR
[`TASK_STATIC_EXECUTOR`]: task::TASK_STATIC_EXECUTOR
[`IS_CANCELLED`]: task::IS_CANCELLED
[`Hint`]: hint::Hint
[`current_executor`]: current_executor::current_executor
[`global_executor`]: global_executor::global_executor
*/

pub mod block_on;
pub mod context;
pub mod current_executor;
mod dyn_executor;
mod dyn_observer;
mod dyn_observer_notified;
pub mod entry_point;

/// Turns an `async fn main` into a `fn main` that installs an executor and runs
/// it. See [`entry_point`] for the trait it expands to a call on.
///
/// ```no_run
/// # // no_run because: the attribute generates this doctest's own `fn main`, so
/// # // running it would install a process-wide executor inside the test harness.
/// #[some_executor::main]
/// async fn main() {
///     println!("hello");
/// }
/// ```
pub use some_executor_macros::main;

pub mod global_executor;
pub mod hint;
mod last_resort;
mod local;
pub mod observer;
pub mod static_executor;
mod static_last_resort;
pub mod static_support;
mod sys;
pub mod task;
pub mod thread_executor;

/// Platform-appropriate instant type for time measurements.
///
/// This is a re-export of either `std::time::Instant` (on native platforms) or
/// `web_time::Instant` (on wasm32), providing a unified interface for time-related
/// operations across all supported platforms.
///
/// Use this type for task scheduling and timing operations within the executor framework.
pub use sys::Instant;

/// Re-exported so `some_executor::block_on(..)` works without importing the module.
pub use block_on::block_on;

/// Re-exported so backends can `impl some_executor::ExecutorMain for ..`.
pub use entry_point::ExecutorMain;

/// Reports a misuse the crate can detect but not prevent.
///
/// Prints `message` to stderr (or the browser console), or panics with it if
/// `SOME_EXECUTOR_BUILTIN_SHOULD_PANIC` is set to `1`, `true`, or `yes`. The escalation
/// switch exists because these conditions are usually configuration mistakes, and a
/// panic in development is easier to act on than a line of output in a busy log.
pub(crate) fn warn_or_panic(message: &str) {
    let should_panic = std::env::var("SOME_EXECUTOR_BUILTIN_SHOULD_PANIC")
        .map(|v| {
            let v = v.to_lowercase();
            v == "1" || v == "true" || v == "yes"
        })
        .unwrap_or(false);

    if should_panic {
        panic!("{}", message);
    }

    #[cfg(not(target_arch = "wasm32"))]
    {
        eprintln!("{}", message);
    }
    #[cfg(target_arch = "wasm32")]
    {
        wasm_lite::console::log(message);
    }
}

/// Task priority for scheduling hints.
///
/// This is a re-export of the priority crate's Priority type,
/// allowing executors to make scheduling decisions based on task priority.
pub type Priority = priority::Priority;

use crate::observer::{
    ExecutorNotified, FinishedObservation, Observer, ObserverNotified, TypedObserver,
};
use crate::task::Task;
use std::any::Any;
use std::convert::Infallible;
use std::fmt::Debug;
use std::future::Future;
use std::pin::Pin;

// Type aliases for complex types to satisfy clippy::type_complexity warnings

/// Type alias for a boxed future that outputs boxed Any and is Send + 'static.
///
/// This type is used for type-erased futures that can be sent between threads.
/// It's primarily used internally for object-safe trait implementations.
pub type BoxedSendFuture =
    Pin<Box<dyn Future<Output = Box<dyn Any + 'static + Send>> + 'static + Send>>;

/// Type alias for a boxed observer notifier that handles Send Any values.
///
/// This type provides notifications when a type-erased Send task completes.
pub type BoxedSendObserverNotifier = Box<dyn ObserverNotified<dyn Any + Send> + Send>;

/// Type alias for a Task that can be used with object-safe spawning.
///
/// This allows spawning type-erased tasks through trait objects,
/// enabling dynamic dispatch when concrete types aren't known at compile time.
pub type ObjSafeTask = Task<BoxedSendFuture, BoxedSendObserverNotifier>;

/// Type alias for a boxed observer that handles Send Any values.
///
/// This observer can be used to track the status and result of type-erased Send tasks.
pub type BoxedSendObserver = Box<
    dyn Observer<Value = Box<dyn Any + Send>, Output = FinishedObservation<Box<dyn Any + Send>>>
        + Send,
>;

/// Type alias for a future that returns a boxed observer for Send Any values.
///
/// Used for async spawning methods that return observers asynchronously.
pub type BoxedSendObserverFuture<'s> = Box<dyn Future<Output = BoxedSendObserver> + 's>;

/// Type alias for the type-erased future accepted by [`SomeExecutor::block_on_objsafe`].
///
/// Unlike [`BoxedSendFuture`] this is neither `Send` nor `'static`: `block_on` polls the
/// future in place on the calling thread, so it never has to move anywhere and may
/// borrow from the caller's stack. Only the *output* is erased to `Box<dyn Any + Send>`,
/// which is what costs `F::Output: Send + 'static`.
pub type BoxedBlockOnFuture<'f> = Pin<Box<dyn Future<Output = Box<dyn Any + Send>> + 'f>>;

/// Type alias for a boxed future that outputs boxed Any (non-Send).
///
/// This type is used for type-erased futures that are local to a thread.
pub type BoxedLocalFuture = Pin<Box<dyn Future<Output = Box<dyn Any>>>>;

/// Type alias for a boxed observer notifier that handles Any values (non-Send).
///
/// This type provides notifications when a type-erased local task completes.
pub type BoxedLocalObserverNotifier = Box<dyn ObserverNotified<dyn Any + 'static>>;

/// Type alias for a Task that can be used with local object-safe spawning.
///
/// This allows spawning type-erased !Send tasks through trait objects.
pub type ObjSafeLocalTask = Task<BoxedLocalFuture, BoxedLocalObserverNotifier>;

/// Type alias for a boxed observer that handles Any values (non-Send).
///
/// This observer can be used to track the status and result of type-erased local tasks.
pub type BoxedLocalObserver =
    Box<dyn Observer<Value = Box<dyn Any>, Output = FinishedObservation<Box<dyn Any>>>>;

/// Type alias for a future that returns a boxed observer for local Any values.
///
/// Used for async spawning methods that return local observers asynchronously.
pub type BoxedLocalObserverFuture<'s> = Box<dyn Future<Output = BoxedLocalObserver> + 's>;

/// Type alias for a boxed future that outputs boxed Any and is 'static but not Send.
///
/// This type is used for type-erased futures with static lifetime but no Send requirement.
pub type BoxedStaticFuture = Pin<Box<dyn Future<Output = Box<dyn Any + 'static>> + 'static>>;

/// Type alias for a boxed observer notifier that handles 'static Any values (non-Send).
///
/// This type provides notifications when a type-erased static task completes.
pub type BoxedStaticObserverNotifier = Box<dyn ObserverNotified<dyn Any + 'static>>;

/// Type alias for a Task that can be used with static object-safe spawning.
///
/// This allows spawning type-erased 'static tasks without Send requirement.
pub type ObjSafeStaticTask = Task<BoxedStaticFuture, BoxedStaticObserverNotifier>;

/// Type alias for a boxed observer that handles 'static Any values (non-Send).
///
/// This observer can be used to track the status and result of type-erased static tasks.
pub type BoxedStaticObserver =
    Box<dyn Observer<Value = Box<dyn Any>, Output = FinishedObservation<Box<dyn Any>>>>;

/// Type alias for a future that returns a boxed observer for static Any values.
///
/// Used for async spawning methods that return static observers asynchronously.
pub type BoxedStaticObserverFuture<'s> = Box<dyn Future<Output = BoxedStaticObserver> + 's>;

/*
Design notes.
Send is required because we often want to take this trait object and port it to another thread, etc.
Sync is required to have a global executor.
Clone is required so that we can get copies for sending.
PartialEq could be used to compare runtimes, but I can't imagine anyone needs it
PartialOrd, Ord what does it mean?
Hash might make sense if we support eq but again, I can't imagine anyone needs it.
Debug
I think all the rest are nonsense.
*/
/// A trait targeting 'some' executor.
///
/// Code targeting this trait can spawn tasks on an executor without knowing which executor it is.
/// This is the core abstraction that allows writing executor-agnostic async code.
///
/// If possible, use the [`SomeExecutorExt`] trait instead for a more ergonomic API.
/// This trait is primarily useful when you need an object-safe trait for dynamic dispatch.
///
/// # Example
///
/// ```
/// # use some_executor::{SomeExecutor, task::Task};
/// # use std::any::Any;
/// # use std::pin::Pin;
/// # use std::future::Future;
/// # use std::convert::Infallible;
/// # fn example(exec: &mut dyn SomeExecutor<ExecutorNotifier = Infallible>) {
/// let future = Box::new(async { Box::new(42) as Box<dyn Any + Send> });
/// let task = Task::new_objsafe(
///     "example".to_string(),
///     future,
///     Default::default(),
///     None
/// );
/// let observer = exec.spawn_objsafe(task);
/// // Can track task completion via observer
/// # }
/// ```
pub trait SomeExecutor: Send + Sync + Debug {
    /**
    # Design notes
    I think we want ExecutorNotified to imply Send (or at least in the case of SomeExecutor trait).
    We want to permit the notifier to be sent into e.g. the future, running on a threadpool for example.
     */
    type ExecutorNotifier: ExecutorNotified + Send;
    /**
    Spawns a future onto the runtime.

    # Parameters
    - `task`: The task to spawn.


    # Note

    `Send` and `'static` are generally required to move the future onto a new thread.

    # Implementation notes
    Implementations should generally ensure that a dlog-context is available to the future.

    For details on why F::Output is Unpin, see the comment on [observer::TypedObserver].
    */
    fn spawn<F: Future + Send + 'static, Notifier: ObserverNotified<F::Output> + Send>(
        &mut self,
        task: Task<F, Notifier>,
    ) -> impl Observer<Value = F::Output> + Send
    where
        Self: Sized,
        F::Output: Send + Unpin;

    /**
    Spawns a future onto the runtime.

    Like [Self::spawn], but some implementors may have a fast path for the async context.

    # Implementation notes

    For details on why F::Output is Unpin, see the comment on [observer::TypedObserver].
    */
    fn spawn_async<'s, F: Future + Send + 'static, Notifier: ObserverNotified<F::Output> + Send>(
        &'s mut self,
        task: Task<F, Notifier>,
    ) -> impl Future<Output = impl Observer<Value = F::Output>> + Send + 's
    where
        Self: Sized,
        F::Output: Send + Unpin;

    /**
    Spawns a future onto the runtime.

    # Note

    This differs from [SomeExecutor::spawn] in that we take a boxed future, since we can't have generic fn.  Implementations probably pin this with [Box::into_pin].
    */
    fn spawn_objsafe(&mut self, task: ObjSafeTask) -> BoxedSendObserver;

    /**
    Spawns a future onto the runtime.

    # Note

    This differs from [SomeExecutor::spawn] in that we take a boxed future, since we can't have generic fn.  Implementations probably pin this with [Box::into_pin].
    */
    fn spawn_objsafe_async<'s>(&'s mut self, task: ObjSafeTask) -> BoxedSendObserverFuture<'s>;

    /**
    Clones the executor.

    The returned value will spawn tasks onto the same executor.
    */
    fn clone_box(&self) -> Box<DynExecutor>;

    /**
    Produces an executor notifier.
    */
    fn executor_notifier(&mut self) -> Option<Self::ExecutorNotifier>;

    /**
    Drives `future` to completion on this executor, blocking the calling thread until it
    resolves.

    This is the one-way door from sync into async: `fn main`, a test, a CLI tool, or an
    FFI callback crosses here once and is executor-agnostic from then on. For the
    duration of the block, this executor is installed as the thread's executor, so
    [`current_executor`](current_executor::current_executor) inside the future finds it.

    Unlike spawning, the future is polled in place and so needs neither `Send` nor
    `'static`; it may borrow from the caller's stack. `F::Output` must be `Send` and
    `'static` because the value is erased through [`Self::block_on_objsafe`], which is
    what lets `Box<DynExecutor>` — and therefore
    [`current_executor`](current_executor::current_executor) and
    [`global_executor`](global_executor::global_executor) — dispatch to the real
    executor rather than to the default below. If you need a value that is not `Send`,
    call the free [`block_on`](fn@block_on) function instead and forgo executor dispatch.

    # Implementation notes

    Customize [`Self::block_on_objsafe`], not this method. This one only erases the
    output type, calls that one, and downcasts the result back — so overriding that one
    changes both paths, while overriding this one leaves anyone holding a
    `Box<DynExecutor>` on the default.

    The default parks the calling thread between polls and polls the future there. Two
    independent things have to be true for that to be correct, and a backend must
    override [`Self::block_on_objsafe`] if either fails:

    1.  **Something else makes progress while this thread is parked.** An executor that
        runs tasks on the calling thread — a current-thread or local executor — must run
        its own polling loop until the future resolves instead, because parking the
        caller stops the loop the future is waiting on. This one the default detects and
        reports rather than hanging silently; see the [`block_on`](mod@block_on) module
        documentation.
    2.  **The polling thread is in whatever ambient context your resources need.** The
        default installs this executor as the thread executor and nothing else. A backend
        whose timers, sockets or channels resolve their driver through a thread-local of
        its own — tokio, via its runtime `EnterGuard` — must override even though it
        satisfies (1), because its workers running elsewhere does not put *this* thread in
        the runtime. Otherwise the first context-dependent `.await` inside the future
        fails, and it fails immediately rather than stalling, so the detector above will
        not catch it.

    An override that wants the default's scoping can get it from
    [`install_thread_executor`](thread_executor::install_thread_executor), which restores
    the previous thread executor — including none — when its guard drops.

    # Panics

    May panic if called from inside a task already running on this executor;
    re-entrancy is not supported and is a deadlock on most backends.

    The default cannot observe a cancellation — it polls the future directly and no one
    else holds a handle to it. An override that spawns the future internally should
    panic if the task is cancelled out from under the caller, rather than inventing an
    output.
    */
    fn block_on<F: Future>(&mut self, future: F) -> F::Output
    where
        Self: Sized,
        F::Output: Send + 'static,
    {
        let erased: BoxedBlockOnFuture<'_> =
            Box::pin(async move { Box::new(future.await) as Box<dyn Any + Send> });
        *self
            .block_on_objsafe(erased)
            .downcast::<F::Output>()
            .expect("block_on_objsafe returned a value of the wrong type")
    }

    /**
    Drives a type-erased future to completion, blocking the calling thread.

    # Note

    This differs from [`Self::block_on`] in that we take a boxed future, since we can't
    have generic fn. This is the method that carries the behavior; the typed one is a
    wrapper that erases and then downcasts.

    See [`Self::block_on`] for the contract, and for why an executor that runs tasks on
    the calling thread must override this.
    */
    fn block_on_objsafe(&mut self, future: BoxedBlockOnFuture<'_>) -> Box<dyn Any + Send> {
        block_on::block_on_installed(self.clone_box(), future)
    }
}

/// A non-objsafe descendant of [SomeExecutor].
///
/// This trait provides a more ergonomic interface for executors, but is not object-safe
/// due to the Clone requirement. This is the preferred trait for most use cases where
/// you know the executor type at compile time.
///
/// # Example
///
/// ```
/// # use some_executor::{SomeExecutorExt, task::Task};
/// # use std::future::Future;
/// # use std::convert::Infallible;
/// # fn example<E: SomeExecutorExt>(mut exec: E) {
/// let task = Task::<_, Infallible>::without_notifications(
///     "example".to_string(),
///     Default::default(),
///     async { 42 }
/// );
/// let observer = exec.spawn(task);
/// // Type-safe observer for the return value
/// # }
/// ```
pub trait SomeExecutorExt: SomeExecutor + Clone {}

/**
A trait for executors that can spawn tasks onto the local thread.

This type can spawn futures that are `!Send`.

# About the lifetime parameter

The lifetime parameter defines the lifetime of the executor itself, which is really the longest lifetime of any future it may be executing.

To understand this, it is helpful to consider 3 cases.

## Multithreaded executors

Multithreaded executors along the lines of [SomeExecutor] generally require their futures to be `'static`.
This is vaguely intuitive in the "it is nice to be able to move the future to another thread" sense,
but in full detail it is less intuitive than it seems.
If a future refers to data on the local stack frame, then the future may dangle if:

1.  The user returns upstack before the future completes, this could maybe be resolved with clever lifetimes?
2.  The thread panics before the future completes, this is a hard problem.
3.  The "thread" is really an async context, which is cancelled before the future completes, this is a hard problem.
4.  The thread is terminated by the OS for some reason, this is a hard problem.

For at least reasons 2-4, [SomeExecutor] implicitly requires `'static` futures.

## Local executors, globally-scoped

Now let us consider a local executor with global scope (such as a main thread executor).  These executors
disptach onto the local thread but exist for a long time, such as the lifetime of the program.  These
types of executors have requirements not so dissimilar from multithreaded executors:

1.  The user returns upstack before the future completes.  This is probably fine, if we poison the
    executor in some way (includingstatically), although care must be taken to ensure that the future's memory does not escape.
    For example, in a DMA-type operation where the OS is writing to a buffer independently,
    that buffer must not be located on the stack.
2.  If the thread panics before the future completes, that's probably fine as well since the executor
    is inherently poisoned by the panic.  See the DMA-style caveat above.
3.  If the async context is cancelled before the future completes, that's a big problem.  It is a hard one
    to solve because it's not obvious how to poison the executor deterministically.
4.  If the thread is terminated by the OS, the executor is poisoned so that's ok.

Due to reason 3, local executors with global scope generally require `'static` futures.

## Local executors, locally scoped

Alternatively we may spin up an executor e.g. on a stack frame, for a specific task.  In that case:

1.  Returning upstack inherently poisons the executor, with sensible lifetime design/analysis.
2.  Panicking poisons the executor.
3.  Cancellation posions the executor since the executor is on the same stackframe
4.  The thread is terminated by the OS, the executor is poisoned.

In this case, the executor can support non-`'static` futures.

## Overall

In summary, for executors with global scope, `'static' should be chosen as the lifetime parameter.

For executors with local scope, this trait can be implemented for any lifetime.

When in doubt, the `'static` lifetime can be chosen and upgraded later.

*/
pub trait SomeLocalExecutor<'future>: Debug {
    /// The notifier handle that can wake or signal work for this executor.
    type ExecutorNotifier: ExecutorNotified;
    /**
    Spawns a future onto the runtime.

    # Parameters
    - `task`: The task to spawn.

    */
    fn spawn_local<F, Notifier: ObserverNotified<F::Output>>(
        &mut self,
        task: Task<F, Notifier>,
    ) -> impl Observer<Value = F::Output>
    where
        Self: Sized,
        F: Future + 'future,
        /* I am a little uncertain whether this is really required */
        <F as Future>::Output: Unpin,
        <F as Future>::Output: 'static;

    /**
    Spawns a future onto the runtime.

    Like [Self::spawn_local], but some implementors may have a fast path for the async context.
    */
    fn spawn_local_async<F, Notifier: ObserverNotified<F::Output>>(
        &mut self,
        task: Task<F, Notifier>,
    ) -> impl Future<Output = impl Observer<Value = F::Output>>
    where
        Self: Sized,
        F: Future + 'future,
        <F as Future>::Output: 'static + Unpin;

    /**
    Spawns a future onto the runtime.

    # Note

    This differs from [SomeExecutor::spawn] in that we take a boxed future, since we can't have generic fn.  Implementations probably pin this with [Box::into_pin].
    */
    fn spawn_local_objsafe(&mut self, task: ObjSafeLocalTask) -> BoxedLocalObserver;

    /// Object-safe async variant of [`Self::spawn_local_objsafe`].
    fn spawn_local_objsafe_async<'s>(
        &'s mut self,
        task: ObjSafeLocalTask,
    ) -> BoxedLocalObserverFuture<'s>;

    /// Returns an executor notifier when notification is supported.
    fn executor_notifier(&mut self) -> Option<Self::ExecutorNotifier>;
}

/// Opt-in synchronous entry point for an executor that drives local tasks on the
/// calling thread.
///
/// This is deliberately separate from [`SomeLocalExecutor`] and deliberately has no
/// default implementation. Parking the caller, as [`SomeExecutor::block_on`] does by
/// default, stops a local executor's scheduler and deadlocks any future waiting on it.
/// An implementation must run its own polling loop until `future` resolves.
///
/// Backends that cannot block at all, notably an executor on the browser main thread,
/// should not implement this trait. [`ExecutorMain`] is the portable entry point for
/// those backends.
pub trait LocalBlockOn<'tasks>: SomeLocalExecutor<'tasks> {
    /// Drives `future` and this executor's scheduler until the future resolves.
    ///
    /// The future and its output need not be [`Send`]. The output remains bounded by
    /// `'static` to match the local executor's observer surface, but the future itself
    /// may borrow from the caller's stack.
    fn block_on_local<F: Future>(&mut self, future: F) -> F::Output
    where
        F::Output: 'static;
}

/// The appropriate type for a dynamically-dispatched executor.
///
/// This type alias provides a convenient way to work with trait objects
/// for executors when the concrete type isn't known at compile time.
///
/// # Example
///
/// ```
/// # use some_executor::DynExecutor;
/// # fn example() {
/// fn store_executor(exec: Box<DynExecutor>) {
///     // Can store and use the executor dynamically
/// }
/// # }
/// ```
pub type DynExecutor = dyn SomeExecutor<ExecutorNotifier = Infallible>;

/// The appropriate type for a dynamically-dispatched static executor.
///
/// This type alias provides a convenient way to work with trait objects
/// for static executors when the concrete type isn't known at compile time.
///
/// # Example
///
/// ```
/// # use some_executor::{DynStaticExecutor, observer::ExecutorNotified};
/// # fn example() {
/// fn store_static_executor(exec: Box<DynStaticExecutor>) {
///     // Can store and use the static executor dynamically
/// }
/// # }
/// ```
pub type DynStaticExecutor = dyn SomeStaticExecutor<ExecutorNotifier = Box<dyn ExecutorNotified>>;

/// A non-objsafe descendant of [SomeLocalExecutor].
///
/// This trait provides a more ergonomic interface for local executors, but is not object-safe.
/// Local executors run futures on the current thread and can handle !Send futures.
///
/// # Note
///
/// We don't support clone on LocalExecutor. There are a few reasons:
/// 1. The typical case of thread-local executor may operate primarily on the principle of (mutable) references into stack memory.
///    Accordingly, a clone may involve some kind of stack-heap transfer (can't really do that since Futures are pinned), or effectively
///    requiring heap allocations from the start. This is to be avoided.
/// 2. Similarly, the mentioned mutable references make it impossible to have two mutable references to the same executor.
/// 3. The SomeExecutor abstraction works more like a channel, where senders can be cloned. In practice, local executors want to implement
///    that – if at all – by bolting such a channel onto their executor with some kind of adapter tool. This allows the overhead to be
///    avoided in cases it isn't used.
///
/// # Example
///
/// ```
/// # use some_executor::{LocalExecutorExt, task::Task};
/// # use std::rc::Rc;
/// # use std::convert::Infallible;
/// # fn example<'a, E: LocalExecutorExt<'a>>(mut exec: E) {
/// // Can use !Send types like Rc
/// let data = Rc::new(42);
/// let task = Task::<_, Infallible>::without_notifications(
///     "example".to_string(),
///     Default::default(),
///     async move { *data }
/// );
/// let observer = exec.spawn_local(task);
/// # }
/// ```
pub trait LocalExecutorExt<'tasks>: SomeLocalExecutor<'tasks> {}

impl<'future> SomeLocalExecutor<'future> for Infallible {
    type ExecutorNotifier = Infallible;

    fn spawn_local<F, Notifier: ObserverNotified<F::Output>>(
        &mut self,
        _task: Task<F, Notifier>,
    ) -> impl Observer<Value = F::Output>
    where
        Self: Sized,
        F: Future + 'future,
        <F as Future>::Output: Unpin,
        <F as Future>::Output: 'static,
    {
        #[allow(unreachable_code)]
        {
            unimplemented!() as TypedObserver<F::Output, Infallible>
        }
    }

    fn spawn_local_async<F, Notifier: ObserverNotified<F::Output>>(
        &mut self,
        _task: Task<F, Notifier>,
    ) -> impl Future<Output = impl Observer<Value = F::Output>>
    where
        Self: Sized,
        F: Future + 'future,
        <F as Future>::Output: 'static,
    {
        #[allow(unreachable_code)]
        #[allow(clippy::async_yields_async)]
        {
            async { todo!() as TypedObserver<F::Output, Infallible> }
        }
    }

    fn spawn_local_objsafe(
        &mut self,
        _task: Task<
            Pin<Box<dyn Future<Output = Box<dyn Any>>>>,
            Box<dyn ObserverNotified<dyn Any + 'static>>,
        >,
    ) -> Box<dyn Observer<Value = Box<dyn Any>, Output = FinishedObservation<Box<dyn Any>>>> {
        unimplemented!()
    }

    fn spawn_local_objsafe_async<'s>(
        &'s mut self,
        _task: Task<
            Pin<Box<dyn Future<Output = Box<dyn Any>>>>,
            Box<dyn ObserverNotified<dyn Any + 'static>>,
        >,
    ) -> Box<
        dyn Future<
                Output = Box<
                    dyn Observer<Value = Box<dyn Any>, Output = FinishedObservation<Box<dyn Any>>>,
                >,
            > + 's,
    > {
        unimplemented!()
    }

    fn executor_notifier(&mut self) -> Option<Self::ExecutorNotifier> {
        unimplemented!()
    }
}

pub use static_executor::{SomeStaticExecutor, StaticBlockOn, StaticExecutorExt};

#[cfg(test)]
mod tests;