//! Executor for running tests with mocked environment

//!

//! See [`MockExecutor`]

use std::any::Any;

use std::cell::Cell;

use std::collections::VecDeque;

use std::fmt::{self, Debug, Display};

use std::future::Future;

use std::io::{self, Write as _};

use std::iter;

use std::panic::{AssertUnwindSafe, catch_unwind, panic_any};

use std::pin::{Pin, pin};

use std::sync::{Arc, Mutex, MutexGuard, Weak};

use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};

use futures::FutureExt as _;

use futures::pin_mut;

use futures::task::{FutureObj, Spawn, SpawnError};

use assert_matches::assert_matches;

use educe::Educe;

use itertools::Either::{self, *};

use itertools::{chain, izip};

use slotmap_careful::DenseSlotMap;

use std::backtrace::Backtrace;

use strum::EnumIter;

// NB: when using traced_test, the trace! and error! output here is generally suppressed

// in tests of other crates.  To see it, you can write something like this

// (in the dev-dependencies of the crate whose tests you're running):

//    tracing-test = { version = "0.2.4", features = ["no-env-filter"] }

use tracing::{error, trace};

use oneshot_fused_workaround::{self as oneshot, Canceled};

use tor_error::error_report;

use tor_rtcompat::{Blocking, ToplevelBlockOn};

use Poll::*;

use TaskState::*;

/// Type-erased future, one for each of our (normal) tasks

type TaskFuture = FutureObj<'static, ()>;

/// Future for the argument to `block_on`, which is handled specially

type MainFuture<'m> = Pin<&'m mut dyn Future<Output = ()>>;

//---------- principal data structures ----------

/// Executor for running tests with mocked environment

///

/// For test cases which don't actually wait for anything in the real world.

///

/// This is the executor.

/// It implements [`Spawn`] and [`ToplevelBlockOn`]

///

/// It will usually be used as part of a `MockRuntime`.

///

/// To run futures, call [`ToplevelBlockOn::block_on`]

///

/// # Restricted environment

///

/// Tests run with this executor must not attempt to block

/// on anything "outside":

/// every future that anything awaits must (eventually) be woken directly

/// *by some other task* in the same test case.

///

/// (By directly we mean that the [`Waker::wake`] call is made

/// by that waking future, before that future itself awaits anything.)

///

/// # Panics

///

/// The executor will panic

/// if the toplevel future (passed to `block_on`)

/// doesn't complete (without externally blocking),

/// but instead waits for something.

///

/// The executor will malfunction or panic if reentered.

/// (Eg, if `block_on` is reentered.)

#[derive(Clone, Default, Educe)]

#[educe(Debug)]

pub struct MockExecutor {

    /// Mutable state

    #[educe(Debug(ignore))]

    shared: Arc<Shared>,

}

/// Shared state and ancillary information

///

/// This is always within an `Arc`.

#[derive(Default)]

struct Shared {

    /// Shared state

    data: Mutex<Data>,

    /// Condition variable for thread scheduling

    ///

    /// Signaled when [`Data.thread_to_run`](struct.Data.html#structfield.thread_to_run)

    /// is modified.

    thread_condvar: std::sync::Condvar,

}

/// Task id, module to hide `Ti` alias

mod task_id {

    slotmap_careful::new_key_type! {

        /// Task ID, usually called `TaskId`

        ///

        /// Short name in special `task_id` module so that [`Debug`] is nice

        pub(super) struct Ti;

    }

}

use task_id::Ti as TaskId;

/// Executor's state

///

/// ### Task state machine

///

/// A task is created in `tasks`, `Awake`, so also in `awake`.

///

/// When we poll it, we take it out of `awake` and set it to `Asleep`,

/// and then call `poll()`.

/// Any time after that, it can be made `Awake` again (and put back onto `awake`)

/// by the waker ([`ActualWaker`], wrapped in [`Waker`]).

///

/// The task's future is of course also present here in this data structure.

/// However, during poll we must release the lock,

/// so we cannot borrow the future from `Data`.

/// Instead, we move it out.  So `Task.fut` is an `Option`.

///

/// ### "Main" task - the argument to `block_on`

///

/// The signature of `BlockOn::block_on` accepts a non-`'static` future

/// (and a non-`Send`/`Sync` one).

///

/// So we cannot store that future in `Data` because `Data` is `'static`.

/// Instead, this main task future is passed as an argument down the call stack.

/// In the data structure we simply store a placeholder, `TaskFutureInfo::Main`.

#[derive(Educe, derive_more::Debug)]

#[educe(Default)]

struct Data {

    /// Tasks

    ///

    /// Includes tasks spawned with `spawn`,

    /// and also the future passed to `block_on`.

    #[debug("{:?}", DebugTasks(self, || tasks.keys()))]

    tasks: DenseSlotMap<TaskId, Task>,

    /// `awake` lists precisely: tasks that are `Awake`, plus maybe stale `TaskId`s

    ///

    /// Tasks are pushed onto the *back* when woken,

    /// so back is the most recently woken.

    #[debug("{:?}", DebugTasks(self, || awake.iter().cloned()))]

    awake: VecDeque<TaskId>,

    /// If a future from `progress_until_stalled` exists

    progressing_until_stalled: Option<ProgressingUntilStalled>,

    /// Scheduling policy

    scheduling: SchedulingPolicy,

    /// (Sub)thread we want to run now

    ///

    /// At any one time only one thread is meant to be running.

    /// Other threads are blocked in condvar wait, waiting for this to change.

    ///

    /// **Modified only** within

    /// [`thread_context_switch_send_instruction_to_run`](Shared::thread_context_switch_send_instruction_to_run),

    /// which takes responsibility for preserving the following **invariants**:

    ///

    ///  1. no-one but the named thread is allowed to modify this field.

    ///  2. after modifying this field, signal `thread_condvar`

    #[educe(Default(expression = "ThreadDescriptor::Executor"))]

    thread_to_run: ThreadDescriptor,

}

/// How we should schedule?

#[derive(Debug, Clone, Default, EnumIter)]

#[non_exhaustive]

pub enum SchedulingPolicy {

    /// Task *most* recently woken is run

    ///

    /// This is the default.

    ///

    /// It will expose starvation bugs if a task never sleeps.

    /// (Which is a good thing in tests.)

    #[default]

    Stack,

    /// Task *least* recently woken is run.

    Queue,

}

/// Record of a single task

///

/// Tracks a spawned task, or the main task (the argument to `block_on`).

///

/// Stored in [`Data`]`.tasks`.

struct Task {

    /// For debugging output

    desc: String,

    /// Has this been woken via a waker?  (And is it in `Data.awake`?)

    ///

    /// **Set to `Awake` only by [`Task::set_awake`]**,

    /// preserving the invariant that

    /// every `Awake` task is in [`Data.awake`](struct.Data.html#structfield.awake).

    state: TaskState,

    /// The actual future (or a placeholder for it)

    ///

    /// May be `None` briefly in the executor main loop, because we've

    /// temporarily moved it out so we can poll it,

    /// or if this is a Subthread task which is currently running sync code

    /// (in which case we're blocked in the executor waiting to be

    /// woken up by [`thread_context_switch`](Shared::thread_context_switch).

    ///

    /// Note that the `None` can be observed outside the main loop, because

    /// the main loop unlocks while it polls, so other (non-main-loop) code

    /// might see it.

    fut: Option<TaskFutureInfo>,

}

/// A future as stored in our record of a [`Task`]

#[derive(Educe)]

#[educe(Debug)]

enum TaskFutureInfo {

    /// The [`Future`].  All is normal.

    Normal(#[educe(Debug(ignore))] TaskFuture),

    /// The future isn't here because this task is the main future for `block_on`

    Main,

    /// This task is actually a [`Subthread`](MockExecutor::subthread_spawn)

    ///

    /// Instead of polling it, we'll switch to it with

    /// [`thread_context_switch`](Shared::thread_context_switch).

    Subthread,

}

/// State of a task - do we think it needs to be polled?

///

/// Stored in [`Task`]`.state`.

#[derive(Debug)]

enum TaskState {

    /// Awake - needs to be polled

    ///

    /// Established by [`waker.wake()`](Waker::wake)

    Awake,

    /// Asleep - does *not* need to be polled

    ///

    /// Established each time just before we call the future's [`poll`](Future::poll)

    Asleep(Vec<SleepLocation>),

}

/// Actual implementor of `Wake` for use in a `Waker`

///

/// Futures (eg, channels from [`futures`]) will use this to wake a task

/// when it should be polled.

///

/// This type must not be `Cloned` with the `Data` lock held.

/// Consequently, a `Waker` mustn't either.

struct ActualWaker {

    /// Executor state

    ///

    /// The Waker mustn't to hold a strong reference to the executor,

    /// since typically a task holds a future that holds a Waker,

    /// and the executor holds the task - so that would be a cycle.

    data: Weak<Shared>,

    /// Which task this is

    id: TaskId,

}

/// State used for an in-progress call to

/// [`progress_until_stalled`][`MockExecutor::progress_until_stalled`]

///

/// If present in [`Data`], an (async) call to `progress_until_stalled`

/// is in progress.

///

/// The future from `progress_until_stalled`, [`ProgressUntilStalledFuture`]

/// is a normal-ish future.

/// It can be polled in the normal way.

/// When it is polled, it looks here, in `finished`, to see if it's `Ready`.

///

/// The future is made ready, and woken (via `waker`),

/// by bespoke code in the task executor loop.

///

/// When `ProgressUntilStalledFuture` (maybe completes and) is dropped,

/// its `Drop` impl is used to remove this from `Data.progressing_until_stalled`.

#[derive(Debug)]

struct ProgressingUntilStalled {

    /// Have we, in fact, stalled?

    ///

    /// Made `Ready` by special code in the executor loop

    finished: Poll<()>,

    /// Waker

    ///

    /// Signalled by special code in the executor loop

    waker: Option<Waker>,

}

/// Future from

/// [`progress_until_stalled`][`MockExecutor::progress_until_stalled`]

///

/// See [`ProgressingUntilStalled`] for an overview of this aspect of the contraption.

///

/// Existence of this struct implies `Data.progressing_until_stalled` is `Some`.

/// There can only be one at a time.

#[derive(Educe)]

#[educe(Debug)]

struct ProgressUntilStalledFuture {

    /// Executor's state; this future's state is in `.progressing_until_stalled`

    #[educe(Debug(ignore))]

    shared: Arc<Shared>,

}

/// Identifies a thread we know about - the executor thread, or a Subthread

///

/// Not related to `std::thread::ThreadId`.

///

/// See [`spawn_subthread`](MockExecutor::subthread_spawn) for definition of a Subthread.

///

/// This being a thread-local and not scoped by which `MockExecutor` we're talking about

/// means that we can't cope if there are multiple `MockExecutor`s involved in the same thread.

/// That's OK (and documented).

#[derive(Copy, Clone, Eq, PartialEq, derive_more::Debug)]

enum ThreadDescriptor {

    /// Foreign - neither the (running) executor, nor a Subthread

    #[debug("FOREIGN")]

    Foreign,

    /// The executor.

    #[debug("Exe")]

    Executor,

    /// This task, which is a Subthread.

    #[debug("{_0:?}")]

    Subthread(TaskId),

}

/// Marker indicating that this task is a Subthread, not an async task.

///

/// See [`spawn_subthread`](MockExecutor::subthread_spawn) for definition of a Subthread.

#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]

struct IsSubthread;

/// [`Shared::subthread_yield`] should set our task awake before switching to the executor

#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]

struct SetAwake;

thread_local! {

    /// Identifies this thread.

    pub static THREAD_DESCRIPTOR: Cell<ThreadDescriptor> = const {

        Cell::new(ThreadDescriptor::Foreign)

    };

}

//---------- creation ----------

impl MockExecutor {

    /// Make a `MockExecutor` with default parameters

    /// Make a `MockExecutor` with a specific `SchedulingPolicy`

}

impl From<Data> for MockExecutor {

}

//---------- spawning ----------

impl MockExecutor {

    /// Spawn a task and return something to identify it

    ///

    /// `desc` should `Display` as some kind of short string (ideally without spaces)

    /// and will be used in the `Debug` impl and trace log messages from `MockExecutor`.

    ///

    /// The returned value is an opaque task identifier which is very cheap to clone

    /// and which can be used by the caller in debug logging,

    /// if it's desired to correlate with the debug output from `MockExecutor`.

    /// Most callers will want to ignore it.

    ///

    /// This method is infallible.  (The `MockExecutor` cannot be shut down.)

    /// Spawn a task and return its output for further usage

    ///

    /// `desc` should `Display` as some kind of short string (ideally without spaces)

    /// and will be used in the `Debug` impl and trace log messages from `MockExecutor`.

    /// Spawn a task and return its `TaskId`

    ///

    /// Convenience method for use by `spawn_identified` and `spawn_obj`.

    /// The future passed to `block_on` is not handled here.

}

impl Data {

    /// Insert a task given its `TaskFutureInfo` and return its `TaskId`.

}

impl Spawn for MockExecutor {

}

impl Blocking for MockExecutor {

    type ThreadHandle<T: Send + 'static> = Pin<Box<dyn Future<Output = T>>>;

    {

            ThreadDescriptor::Executor | ThreadDescriptor::Subthread(_),

            "MockExecutor::spawn_blocking_io only allowed from future or subthread, being run by this executor"

        );

        )

    {

}

//---------- block_on ----------

impl ToplevelBlockOn for MockExecutor {

    {

        // Box this just so that we can conveniently control precisely when it's dropped.

        // (We could do this with Option and Pin::set but that seems clumsier.)

        };

        {

        }

        #[allow(clippy::let_and_return)] // clarity

            // eprintln can be captured by libtest, but the debug_dump goes to io::stderr.

            // use the latter, so that the debug dump is prefixed by this message.

            // write to tracing too, so the tracing log is clear about when we crashed

            // Sequencing here is subtle.

            //

            // We should do the dump before dropping the input future, because the input

            // future is likely to own things that, when dropped, wake up other tasks,

            // rendering the dump inaccurate.

            //

            // But also, dropping the input future may well drop a ProgressUntilStalledFuture

            // which then reenters us.  More generally, we mustn't call user code

            // with the lock held.

            //

            // And, we mustn't panic with the data lock held.

            //

            // If value was Some, then this closure is dropped without being called,

            // which drops the future after it has yielded the value, which is correct.

                r"

all futures blocked. waiting for the real world? or deadlocked (waiting for each other) ?

"

            );

        });

}

//---------- execution - core implementation ----------

impl MockExecutor {

    /// Keep polling tasks until nothing more can be done

    ///

    /// Ie, stop when `awake` is empty and `progressing_until_stalled` is `None`.

        loop {

            // Handle `progressing_until_stalled`

                    // No progressing_until_stalled, we're actually done.

                };

                    pus.finished, Pending,

                    "ProgressingUntilStalled finished twice?!"

                );

                // Release the lock temporarily so that ActualWaker::clone doesn't deadlock

                {

            };

        }

    /// Keep polling tasks until `awake` is empty

    ///

    /// (Ignores `progressing_until_stalled` - so if one is active,

    /// will return when all other tasks have blocked.)

    ///

    /// # Panics

    ///

    /// Might malfunction or panic if called reentrantly

            ThreadDescriptor::Foreign,

            "MockExecutor executor re-entered"

        );

            }

        }

    /// Keep polling tasks until `awake` is empty (inner, executor main loop)

    ///

    /// This is only called from [`MockExecutor::execute_until_first_stall`],

    /// so it could also be called `execute_until_first_stall_inner`.

        'outer: loop {

            // Take a `Awake` task off `awake` and make it `Asleep`

                };

                };

            };

            // Poll the selected task

            };

            // Deal with the returned `Poll`

            let _fut_drop_late;

            {

                    Left(Pending) => {

                        // The task might have been woken *by its own poll method*.

                        // That's why we set it to `Asleep` *earlier* rather than here.

                        // All we need to do is put the future back.

                    }

                    Left(Ready(())) => {

                        // Oh, it finished!

                        // It might be in `awake`, but that's allowed to contain stale tasks,

                        // so we *don't* need to scan that list and remove it.

                        // It is important that we don't drop `fut` until we have released

                        // the data lock, since it is an external type and might try to reenter

                        // us (eg by calling spawn).  If we do that here, we risk deadlock.

                        // So, move `fut` to a variable with scope outside the block with `data`.

                    }

                    Right(IsSubthread) => {

                        // Task is a subthread, which has called thread_context_switch

                        // to switch to us.  We "poll" it by switching back.

                        // Put back `TFI::Subthread`, which was moved out temporarily, above.

                        // Now, if the Subthread still exists, that's because it's switched

                        // back to us, and is waiting in subthread_block_on_future again.

                        // Or it might have ended, in which case it's not in `tasks` any more.

                        // In any case we can go back to scheduling futures.

                    }

                }

            }

        }

}

impl Data {

    /// Return the next task to run

    ///

    /// The task is removed from `awake`, but **`state` is not set to `Asleep`**.

    /// The caller must restore the invariant!

        use SchedulingPolicy as SP;

        }

}

impl ActualWaker {

    /// Obtain a strong reference to the executor's data

    /// Wake the task corresponding to this `ActualWaker`

    ///

    /// This is like `<Self as std::task::Wake>::wake()` but takes `&self`, not `Arc`

            // The executor is gone!  Don't try to wake.

        };

        };

    /// Create and return a `Waker` for task `id`

}

//---------- "progress until stalled" functionality ----------

impl MockExecutor {

    /// Run tasks in the current executor until every other task is waiting

    ///

    /// # Panics

    ///

    /// Might malfunction or panic if more than one such call is running at once.

    ///

    /// (Ie, you must `.await` or drop the returned `Future`

    /// before calling this method again.)

    ///

    /// Must be called and awaited within a future being run by `self`.

            "progress_until_stalled called more than once"

        );

}

impl Future for ProgressUntilStalledFuture {

    type Output = ();

}

impl Drop for ProgressUntilStalledFuture {

}

//---------- (sub)threads ----------

impl MockExecutor {

    /// Spawn a "Subthread", for processing in a sync context

    ///

    /// `call` will be run on a separate thread, called a "Subthread".

    ///

    /// But it will **not run simultaneously** with the executor,

    /// nor with other Subthreads.

    /// So Subthreads are somewhat like coroutines.

    ///

    /// `call` must be capable of making progress without waiting for any other Subthreads.

    /// `call` may wait for async futures, using

    /// [`subthread_block_on_future`](MockExecutor::subthread_block_on_future).

    ///

    /// Subthreads may be used for cpubound activity,

    /// or synchronous IO (such as large volumes of disk activity),

    /// provided that the synchronous code will reliably make progress,

    /// without waiting (directly or indirectly) for any async task or Subthread -

    /// except via `subthread_block_on_future`.

    ///

    /// # Subthreads vs raw `std::thread` threads

    ///

    /// Programs using `MockExecutor` may use `std::thread` threads directly.

    /// However, this is not recommended.  There are severe limitations:

    ///

    ///  * Only a Subthread can re-enter the async context from sync code:

    ///    this must be done with

    ///    using [`subthread_block_on_future`](MockExecutor::subthread_block_on_future).

    ///    (Re-entering the executor with

    ///    [`block_on`](tor_rtcompat::ToplevelBlockOn::block_on)

    ///    is not allowed.)

    ///  * If async tasks want to suspend waiting for synchronous code,

    ///    the synchronous code must run on a Subthread.

    ///    This allows the `MockExecutor` to know when

    ///    that synchronous code is still making progress.

    ///    (This is needed for

    ///    [`progress_until_stalled`](MockExecutor::progress_until_stalled)

    ///    and the facilities which use it, such as

    ///    [`MockRuntime::advance_until_stalled`](crate::MockRuntime::advance_until_stalled).)

    ///  * Subthreads never run in parallel -

    ///    they only run as scheduled deterministically by the `MockExecutor`.

    ///    So using Subthreads eliminates a source of test nonndeterminism.

    ///    (Execution order is still varied due to explicitly varying the scheduling policy.)

    ///

    /// # Panics, abuse, and malfunctions

    ///

    /// If `call` panics and unwinds, `spawn_subthread` yields `Err`.

    /// The application code should to do something about it if this happens,

    /// typically, logging errors, tearing things down, or failing a test case.

    ///

    /// If the executor doesn't run, the subthread will not run either, and will remain stuck.

    /// (So, typically, if the thread supposed to run the executor panics,

    /// for example because a future or the executor itself panics,

    /// all the subthreads will become stuck - effectively, they'll be leaked.)

    ///

    /// `spawn_subthread` panics if OS thread spawning fails.

    /// (Like `std::thread::spawn()` does.)

    ///

    /// `MockExecutor`s will malfunction or panic if

    /// any executor invocation method (eg `block_on`) is called on a Subthread.

        // NB: we don't know which thread we're on!

        // In principle we might be on another Subthread.

        // So we can't context switch here.  That would be very confusing.

        //

        // Instead, we prepare the new Subthread as follows:

        //   - There is a task in the executor

        //   - The task is ready to be polled, whenever the executor decides to

        //   - The thread starts running right away, but immediately waits until it is scheduled

        // See `subthread_entrypoint`.

        {

                })

        }

    /// Call an async `Future` from a Subthread

    ///

    /// Blocks the Subthread, and arranges to run async tasks,

    /// including `fut`, until `fut` completes.

    ///

    /// `fut` is polled on the executor thread, not on the Subthread.

    /// (We may change that in the future, allowing passing a non-`Send` future.)

    ///

    /// # Panics, abuse, and malfunctions

    ///

    /// `subthread_block_on_future` will malfunction or panic

    /// if called on a thread that isn't a Subthread from the same `MockExecutor`

    /// (ie a thread made with [`spawn_subthread`](MockExecutor::subthread_spawn)).

    ///

    /// If `fut` itself panics, the executor will panic.

    ///

    /// If the executor isn't running, `subthread_block_on_future` will hang indefinitely.

    /// See `spawn_subthread`.

            ThreadDescriptor::Executor => {

            }

                "subthread_block_on_future called on foreign thread (not spawned with spawn_subthread)"

            ),

        };

        // We yield once before the first poll, and once after Ready, to shake up the

        // execution order a bit, depending on the scheduling policy.

            // Poll the provided future

            // Pending.  Switch back to the executor thread.

            // When the future becomes ready, the Waker will be woken, waking the task,

            // so that the executor will "poll" us again.

        };

}

impl Shared {

    /// Main entrypoint function for a Subthread

    ///

    /// Entered on a new `std::thread` thread created by

    /// [`subthread_spawn`](MockExecutor::subthread_spawn).

    ///

    /// When `call` completes, sends its returned value `T` to `output_tx`.

        // We start out Awake, but we wait for the executor to tell us to run.

        // This will be done the first time the task is "polled".

        // Run the user's actual thread function.

        // This will typically reenter us via subthread_block_on_future.

        // This makes the return value from subthread_spawn ready.

        // It will be polled by the executor in due course, presumably.

            #[allow(clippy::unnecessary_lazy_evaluations)]

        );

    /// Yield back to the executor from a subthread

    ///

    /// Checks that things are in order

    /// (in particular, that this task is in the data structure as a subhtread)

    /// and switches to the executor thread.

    ///

    /// The caller must arrange that the task gets woken.

    ///

    /// With [`SetAwake`], sets our task awake, so that we'll be polled

    /// again as soon as we get to the top of the executor's queue.

    /// Otherwise, we'll be reentered after someone wakes a [`Waker`] for the task.

        {

            };

        }

        );

    /// Switch from (sub)thread `us` to (sub)thread `them`

    ///

    /// Returns when someone calls `thread_context_switch(.., us)`.

    /// Instruct the (sub)thread `them` to run

    ///

    /// Update `thread_to_run`, which will wake up `them`'s

    /// call to `thread_context_switch_waitfor_instruction_to_run`.

    ///

    /// Must be called from (sub)thread `us`.

    /// Part of `thread_context_switch`, not normally called directly.

    /// Await an instruction for this thread, `us`, to run

    ///

    /// Waits for `thread_to_run` to be `us`,

    /// waiting for `thread_condvar` as necessary.

    ///

    /// Part of `thread_context_switch`, not normally called directly.

        #[allow(let_underscore_lock)]

                } else {

                }

                // We're in `.wait_while`, not `.wait_until`.  Confusing.

}

//---------- ancillary and convenience functions ----------

/// Trait to let us assert at compile time that something is nicely `Sync` etc.

#[allow(dead_code)] // yes, we don't *use* anything from this trait

trait EnsureSyncSend: Sync + Send + 'static {}

impl EnsureSyncSend for ActualWaker {}

impl EnsureSyncSend for MockExecutor {}

impl MockExecutor {

    /// Return the number of tasks running in this executor

    ///

    /// One possible use is for a test case to check that task(s)

    /// that ought to have exited, have indeed done so.

    ///

    /// In the usual case, the answer will be at least 1,

    /// because it counts the future passed to

    /// [`block_on`](MockExecutor::block_on)

    /// (perhaps via [`MockRuntime::test_with_various`](crate::MockRuntime::test_with_various)).

}

impl Shared {

    /// Lock and obtain the guard

    ///

    /// Convenience method which panics on poison

}

impl Task {

    /// Set task `id` to `Awake` and arrange that it will be polled.

        }

}

//---------- ActualWaker as RawWaker ----------

/// Using [`ActualWaker`] in a [`RawWaker`]

///

/// We need to make a

/// [`Waker`] (the safe, type-erased, waker, used by actual futures)

/// which contains an

/// [`ActualWaker`] (our actual waker implementation, also safe).

///

/// `std` offers `Waker::from<Arc<impl Wake>>`.

/// But we want a bespoke `Clone` implementation, so we don't want to use `Arc`.

///

/// So instead, we implement the `RawWaker` API in terms of `ActualWaker`.

/// We keep the `ActualWaker` in a `Box`, and actually `clone` it (and the `Box`).

///

/// SAFETY

///

///  * The data pointer is `Box::<ActualWaker>::into_raw()`

///  * We share these when we clone

///  * No-one is allowed `&mut ActualWaker` unless there are no other clones

///  * So we may make references `&ActualWaker`

impl ActualWaker {

    /// Wrap up an [`ActualWaker`] as a type-erased [`Waker`] for passing to futures etc.

    /// Helper: wrap up an [`ActualWaker`] as a [`RawWaker`].

    /// Implementation of [`RawWakerVTable`]'s `clone`

        unsafe {

        }

    /// Implementation of [`RawWakerVTable`]'s `wake`

    /// Implementation of [`RawWakerVTable`]'s `wake_ref_by`

    /// Implementation of [`RawWakerVTable`]'s `drop`

}

/// vtable for `Box<ActualWaker>` as `RawWaker`

//

// This ought to be in the impl block above, but

//   "associated `static` items are not allowed"

static RAW_WAKER_VTABLE: RawWakerVTable = RawWakerVTable::new(

    ActualWaker::raw_clone,

    ActualWaker::raw_wake,

    ActualWaker::raw_wake_by_ref,

    ActualWaker::raw_drop,

);

//---------- Sleep location tracking and dumping ----------

/// We record "where a future went to sleep" as (just) a backtrace

///

/// This type alias allows us to mock `Backtrace` for miri.

/// (It also insulates from future choices about sleep location representation.0

#[cfg(not(miri))]

type SleepLocation = Backtrace;

impl Data {

    /// Dump tasks and their sleep location backtraces

                Awake => {

                }

                    }

                }

            }

        }

            "\nNote: there might be spurious traces, see docs for MockExecutor::debug_dump\n"

}

/// Track sleep locations via `<Waker as Clone>`.

///

/// See [`MockExecutor::debug_dump`] for the explanation.

impl Clone for ActualWaker {

            // If the executor is gone, there is nothing to adjust

                }

            } else {

            }

}

//---------- API for full debug dump ----------

/// Debugging dump of a `MockExecutor`'s state