cocotb 1.9.2__cp39-cp39-win_amd64.whl → 2.0.0rc2__cp39-cp39-win_amd64.whl

cocotb/_scheduler.py

@@ -0,0 +1,448 @@
+# Copyright cocotb contributors
+# Copyright (c) 2013, 2018 Potential Ventures Ltd
+# Copyright (c) 2013 SolarFlare Communications Inc
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Task scheduler."""
+
+import logging
+import threading
+from bdb import BdbQuit
+from collections import OrderedDict
+from typing import Any, Callable, Coroutine, Dict, List, TypeVar, Union
+
+import cocotb
+import cocotb._gpi_triggers
+import cocotb.handle
+from cocotb import debug
+from cocotb._base_triggers import Event, Trigger
+from cocotb._bridge import external_state, external_waiter
+from cocotb._exceptions import InternalError
+from cocotb._gpi_triggers import (
+    GPITrigger,
+    NextTimeStep,
+    ReadWrite,
+)
+from cocotb._outcomes import Error, Outcome, Value, capture
+from cocotb._profiling import profiling_context
+from cocotb._py_compat import ParamSpec, insertion_ordered_dict
+from cocotb.task import Task, _TaskState
+
+T = TypeVar("T")
+
+P = ParamSpec("P")
+
+
+class Scheduler:
+    """The main Task scheduler.
+
+    How It Generally Works:
+        Tasks are `queued` to run in the scheduler with :meth:`_queue`.
+        Queueing adds the Task and an Outcome value to :attr:`_pending_tasks`.
+        The main scheduling loop is located in :meth:`_event_loop` and loops over the queued Tasks and `schedules` them.
+        :meth:`_schedule` schedules a Task -
+        continuing its execution from where it previously yielded control -
+        by injecting the Outcome value associated with the Task from the queue.
+        The Task's body will run until it finishes or reaches the next :keyword:`await` statement.
+        If a Task reaches an :keyword:`await`, :meth:`_schedule` will convert the value yielded from the Task into a Trigger with :meth:`_trigger_from_any` and its friend methods.
+        Triggers are then `primed` (with :meth:`~cocotb.triggers.Trigger._prime`)
+        with a `react` function (:meth:`_sim_react` or :meth:`_react)
+        so as to wake up Tasks waiting for that Trigger to `fire` (when the event encoded by the Trigger occurs).
+        This is accomplished by :meth:`_resume_task_upon`.
+        :meth:`_resume_task_upon` also associates the Trigger with the Task waiting on it to fire by adding them to the :attr:`_trigger2tasks` map.
+        If, instead of reaching an :keyword:`await`, a Task finishes, :meth:`_schedule` will cause the :class:`~cocotb.task.Join` trigger to fire.
+        Once a Trigger fires it calls the react function which queues all Tasks waiting for that Trigger to fire.
+        Then the process repeats.
+
+        When a Task is cancelled (:meth:`_unschedule`), it is removed from the Task queue if it is currently queued.
+        Also, the Task and Trigger are deassociated in the :attr:`_trigger2tasks` map.
+        If the cancelled Task is the last Task waiting on a Trigger, that Trigger is `unprimed` to prevent it from firing.
+
+    Simulator Phases:
+        All GPITriggers (triggers that are fired by the simulator) go through :meth:`_sim_react`
+        which looks at the fired GPITriggers to determine and track the current simulator phase cocotb is executing in.
+
+        Normal phase:
+            Corresponds to all non-ReadWrite and non-ReadOnly phases.
+            Any writes are cached for the next ReadWrite phase and do not happen immediately.
+            Scheduling :class:`~cocotb.triggers.ReadWrite` and :class:`~cocotb.triggers.ReadOnly` are valid.
+
+        ReadWrite phase:
+            Corresponds to ``cbReadWriteSynch`` (VPI) or ``vhpiCbRepLastKnownDeltaCycle`` (VHPI).
+            At the start of scheduling in this phase we play back all the *previously* cached write updates.
+            Any writes are cached for the next ReadWrite phase and do not happen immediately.
+            Scheduling :class:`~cocotb.triggers.ReadWrite` and :class:`~cocotb.triggers.ReadOnly` are valid.
+            One caveat is that scheduling a :class:`~cocotb.triggers.ReadWrite` while in this phase may not be valid.
+            If there were no writes applied at the beginning of this phase, there will be no more events in this time step,
+            and there will not be another ReadWrite phase in this time step.
+            Simulators generally handle this caveat gracefully by leaving you in the ReadWrite phase of the next time step.
+
+        ReadOnly phase
+            Corresponds to ``cbReadOnlySynch`` (VPI) or ``vhpiCbRepEndOfTimeStep`` (VHPI).
+            In this state we are not allowed to perform writes.
+            Scheduling :class:`~cocotb.triggers.ReadWrite` and :class:`~cocotb.triggers.ReadOnly` are *not* valid.
+
+    Caveats and Special Cases:
+        The scheduler treats Tests specially.
+        If a Test finishes or a Task ends with an Exception, the scheduler is put into a `terminating` state.
+        All currently queued Tasks are cancelled and all pending Triggers are unprimed.
+        This is currently spread out between :meth:`_handle_termination` and :meth:`_cleanup`.
+        In that mix of functions, the :attr:`_test_complete_cb` callback is called to inform whomever (the regression_manager) the test finished.
+        The scheduler also is responsible for starting the next Test in the Normal phase by priming a ``Timer(1)`` with the second half of test completion handling.
+
+        The scheduler is currently where simulator time phase is tracked.
+        This is mostly because this is where :meth:`_sim_react` is most conveniently located.
+        The scheduler can't currently be made independent of simulator-specific code because of the above special cases which have to respect simulator phasing.
+
+        Currently Task cancellation is accomplished with :meth:`Task.kill() <cocotb.task.Task.kill>`.
+        This function immediately cancels the Task by re-entering the scheduler.
+        This can cause issues if you are trying to cancel the Test Task or the currently executing Task.
+
+        TODO: There are attributes and methods for dealing with "externals", but I'm not quite sure how it all works yet.
+    """
+
+    # Singleton events, recycled to avoid spurious object creation
+    _next_time_step = NextTimeStep()
+    _read_write = ReadWrite()
+
+    def __init__(self) -> None:
+        self.log = logging.getLogger("cocotb.scheduler")
+
+        # A dictionary of pending tasks for each trigger,
+        # indexed by trigger
+        self._trigger2tasks: Dict[Trigger, list[Task[object]]] = (
+            insertion_ordered_dict()
+        )
+
+        self._scheduled_tasks: OrderedDict[Task[object], Union[BaseException, None]] = (
+            OrderedDict()
+        )
+        self._pending_threads: List[external_waiter[Any]] = []
+        self._pending_events: List[Event] = []
+
+        self._main_thread = threading.current_thread()
+
+        self._current_task: Union[Task[object], None] = None
+
+    def _sim_react(self, trigger: GPITrigger) -> None:
+        """Called when a :class:`~cocotb.triggers.GPITrigger` fires.
+
+        This is often the entry point into Python from the simulator,
+        so this function is in charge of enabling profiling.
+        It must also track the current simulator time phase,
+        and start the unstarted event loop.
+        """
+        with profiling_context:
+            # TODO: move state tracking to global variable
+            # and handle this via some kind of trigger-specific Python callback
+            cocotb._gpi_triggers._current_gpi_trigger = trigger
+
+            # apply inertial writes if ReadWrite
+            if trigger is self._read_write:
+                cocotb.handle._apply_scheduled_writes()
+
+            self._react(trigger)
+            self._event_loop()
+
+    def _react(self, trigger: Trigger) -> None:
+        """Called when a :class:`~cocotb.triggers.Trigger` fires.
+
+        Finds all Tasks waiting on the Trigger that fired and queues them.
+        """
+        if debug.debug:
+            self.log.debug("Trigger fired: %s", trigger)
+
+        # find all tasks waiting on trigger that fired
+        try:
+            scheduling = self._trigger2tasks.pop(trigger)
+        except KeyError:
+            # GPI triggers should only be ever pending if there is an
+            # associated task waiting on that trigger, otherwise it would
+            # have been unprimed already
+            if isinstance(trigger, GPITrigger):
+                self.log.warning(
+                    "No tasks waiting on GPITrigger that fired: %s\n"
+                    "This is due to an issue with the GPI or a simulator bug.",
+                    trigger,
+                )
+            # For Python triggers this isn't actually an error - we might do
+            # event.set() without knowing whether any tasks are actually
+            # waiting on this event, for example
+            elif debug.debug:
+                self.log.debug("No tasks waiting on trigger that fired: %s", trigger)
+            return
+
+        if debug.debug:
+            debugstr = "\n\t".join([str(task) for task in scheduling])
+            if len(scheduling) > 0:
+                debugstr = "\n\t" + debugstr
+            self.log.debug(
+                "%d pending tasks for trigger %s%s",
+                len(scheduling),
+                trigger,
+                debugstr,
+            )
+
+        # queue all tasks to wake up
+        for task in scheduling:
+            # unset trigger
+            task._trigger = None
+            self._schedule_task_internal(task)
+
+        # cleanup trigger
+        trigger._cleanup()
+
+    def _event_loop(self) -> None:
+        """Run the main event loop.
+
+        This should only be started by:
+        * The beginning of a test, when there is no trigger to react to
+        * A GPI trigger
+        """
+
+        while self._scheduled_tasks:
+            task, exc = self._scheduled_tasks.popitem(last=False)
+
+            if debug.debug:
+                self.log.debug("Scheduling task %s", task)
+            self._resume_task(task, exc)
+            if debug.debug:
+                self.log.debug("Scheduled task %s", task)
+
+            # remove our reference to the objects at the end of each loop,
+            # to try and avoid them being destroyed at a weird time (as
+            # happened in gh-957)
+            del task
+
+            # Schedule may have queued up some events so we'll burn through those
+            while self._pending_events:
+                if debug.debug:
+                    self.log.debug(
+                        "Scheduling pending event %s", self._pending_events[0]
+                    )
+                self._pending_events.pop(0).set()
+
+        # no more pending tasks
+        if debug.debug:
+            self.log.debug("All tasks scheduled, handing control back to simulator")
+
+    def _unschedule(self, task: Task[Any]) -> None:
+        """Unschedule a task and unprime dangling pending triggers.
+
+        Also:
+          * enters the scheduler termination state if the Test Task is unscheduled.
+          * creates and fires a :class:`~cocotb.task.Join` trigger.
+          * forcefully ends the Test if a Task ends with an exception.
+        """
+
+        # remove task from queue
+        if task in self._scheduled_tasks:
+            self._scheduled_tasks.pop(task)
+
+        # Unprime the trigger this task is waiting on
+        trigger = task._trigger
+        if trigger is not None:
+            task._trigger = None
+            if task in self._trigger2tasks.setdefault(trigger, []):
+                self._trigger2tasks[trigger].remove(task)
+            if not self._trigger2tasks[trigger]:
+                trigger._unprime()
+                del self._trigger2tasks[trigger]
+
+    def _schedule_task_upon(self, task: Task[Any], trigger: Trigger) -> None:
+        """Schedule `task` to be resumed when `trigger` fires."""
+        # TODO Move this all into Task
+        task._trigger = trigger
+        task._state = _TaskState.PENDING
+
+        trigger_tasks = self._trigger2tasks.setdefault(trigger, [])
+        trigger_tasks.append(task)
+
+        try:
+            # TODO maybe associate the react method with the trigger object so
+            # we don't have to do a type check here.
+            if isinstance(trigger, GPITrigger):
+                trigger._prime(self._sim_react)
+            else:
+                trigger._prime(self._react)
+        except Exception as e:
+            # discard the trigger we associated, it will never fire
+            self._trigger2tasks.pop(trigger)
+
+            # replace it with a new trigger that throws back the exception
+            self._schedule_task_internal(task, e)
+
+    def _schedule_task(self, task: Task[Any]) -> None:
+        """Queue *task* for scheduling.
+
+        It is an error to attempt to queue a task that has already been queued.
+        """
+        if task.done():
+            raise RuntimeError(
+                f"{task} has finished executing and can not be scheduled again. Did you call start_soon() on a finished Task?"
+            )
+        if task in self._scheduled_tasks:
+            return
+        for tasks in self._trigger2tasks.values():
+            if task in tasks:
+                return
+        self._schedule_task_internal(task)
+
+    def _schedule_task_internal(
+        self, task: Task[Any], exc: Union[BaseException, None] = None
+    ) -> None:
+        # TODO Move state tracking into Task
+        task._state = _TaskState.SCHEDULED
+        self._scheduled_tasks[task] = exc
+
+    def _queue_function(self, task: Coroutine[Trigger, None, T]) -> T:
+        """Queue a task for execution and move the containing thread
+        so that it does not block execution of the main thread any longer.
+        """
+        # We should be able to find ourselves inside the _pending_threads list
+        matching_threads = [
+            t for t in self._pending_threads if t.thread == threading.current_thread()
+        ]
+        if len(matching_threads) == 0:
+            raise RuntimeError("queue_function called from unrecognized thread")
+
+        # Raises if there is more than one match. This can never happen, since
+        # each entry always has a unique thread.
+        (t,) = matching_threads
+
+        outcome: Union[Outcome[T], None] = None
+
+        async def wrapper() -> None:
+            nonlocal outcome
+            # This function runs in the scheduler thread
+            try:
+                outcome = Value(await task)
+            except (KeyboardInterrupt, SystemExit, BdbQuit):
+                # Allow these to bubble up to the execution root to fail the sim immediately.
+                # This follows asyncio's behavior.
+                raise
+            except BaseException as e:
+                outcome = Error(e)
+            # Notify the current (scheduler) thread that we are about to wake
+            # up the background (`@external`) thread, making sure to do so
+            # before the background thread gets a chance to go back to sleep by
+            # calling thread_suspend.
+            # We need to do this here in the scheduler thread so that no more
+            # tasks run until the background thread goes back to sleep.
+            t.thread_resume()
+            event.set()
+
+        event = threading.Event()
+        # must register this with test as there's no way to clean up with threading
+        self._schedule_task_internal(cocotb.start_soon(wrapper()))
+        # The scheduler thread blocks in `thread_wait`, and is woken when we
+        # call `thread_suspend` - so we need to make sure the task is
+        # queued before that.
+        t.thread_suspend()
+        # This blocks the calling `@external` thread until the task finishes
+        event.wait()
+        assert outcome is not None
+        return outcome.get()
+
+    def _run_in_executor(
+        self, func: "Callable[P, T]", *args: "P.args", **kwargs: "P.kwargs"
+    ) -> Coroutine[Trigger, None, T]:
+        """Run the task in a separate execution thread
+        and return an awaitable object for the caller.
+        """
+        # Create a thread
+        # Create a trigger that is called as a result of the thread finishing
+        # Create an Event object that the caller can await on
+        # Event object set when the thread finishes execution, this blocks the
+        # calling task (but not the thread) until the external completes
+
+        waiter = external_waiter[T]()
+
+        def execute_external() -> None:
+            waiter._outcome = capture(func, *args, **kwargs)
+            if debug.debug:
+                self.log.debug(
+                    "Execution of external routine done %s", threading.current_thread()
+                )
+            waiter.thread_done()
+
+        async def wrapper() -> T:
+            thread = threading.Thread(
+                group=None,
+                target=execute_external,
+                name=func.__qualname__ + "_thread",
+            )
+
+            waiter.thread = thread
+            self._pending_threads.append(waiter)
+
+            await waiter.event.wait()
+
+            return waiter.result  # raises if there was an exception
+
+        return wrapper()
+
+    def _resume_task(self, task: Task[object], exc: Union[BaseException, None]) -> None:
+        """Resume *task* with *outcome*.
+
+        Args:
+            task: The task to schedule.
+            outcome: The outcome to inject into the *task*.
+
+        Scheduling runs *task* until it either finishes or reaches the next :keyword:`await` statement.
+        If *task* completes, it is unscheduled, a Join trigger fires, and test completion is inspected.
+        Otherwise, it reached an :keyword:`await` and we have a result object which is converted to a trigger,
+        that trigger is primed,
+        then that trigger and the *task* are registered with the :attr:`_trigger2tasks` map.
+        """
+        if self._current_task is not None:
+            raise InternalError("_schedule() called while another Task is executing")
+        try:
+            self._current_task = task
+
+            trigger = task._advance(exc)
+
+            if task.done():
+                if debug.debug:
+                    self.log.debug("%s completed with %s", task, task._outcome)
+                assert trigger is None
+                self._unschedule(task)
+
+            if not task.done():
+                if debug.debug:
+                    self.log.debug("%r yielded %s", task, trigger)
+                if not isinstance(trigger, Trigger):
+                    e = TypeError(
+                        f"Coroutine yielded an object of type {type(trigger)}, which the scheduler can't "
+                        f"handle: {trigger!r}\n"
+                    )
+                    self._schedule_task_internal(task, e)
+                else:
+                    self._schedule_task_upon(task, trigger)
+
+            # We do not return from here until pending threads have completed, but only
+            # from the main thread, this seems like it could be problematic in cases
+            # where a sim might change what this thread is.
+
+            if self._main_thread is threading.current_thread():
+                for ext in self._pending_threads:
+                    ext.thread_start()
+                    if debug.debug:
+                        self.log.debug(
+                            "Blocking from %s on %s",
+                            threading.current_thread(),
+                            ext.thread,
+                        )
+                    state = ext.thread_wait()
+                    if debug.debug:
+                        self.log.debug(
+                            "Back from wait on self %s with newstate %s",
+                            threading.current_thread(),
+                            state,
+                        )
+                    if state == external_state.EXITED:
+                        self._pending_threads.remove(ext)
+                        self._pending_events.append(ext.event)
+        finally:
+            self._current_task = None

cocotb/_test.py

@@ -0,0 +1,248 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+import inspect
+import os
+import pdb
+from typing import (
+    Any,
+    Callable,
+    Coroutine,
+    List,
+    Optional,
+    Union,
+)
+
+import cocotb
+from cocotb._base_triggers import NullTrigger, Trigger
+from cocotb._deprecation import deprecated
+from cocotb._exceptions import InternalError
+from cocotb._outcomes import Error, Outcome, Value
+from cocotb._test_functions import TestSuccess
+from cocotb.task import ResultType, Task
+
+_pdb_on_exception = "COCOTB_PDB_ON_EXCEPTION" in os.environ
+
+
+class RunningTest:
+    """State of the currently executing Test."""
+
+    # TODO
+    # Make the tasks list a TaskManager.
+    # Make shutdown errors and outcome be an ExceptionGroup from that TaskManager.
+    # Replace result() with passing the outcome to the done callback.
+    # Make this and Task the same object which is a Coroutine.
+    # Reimplement the logic in the body of an async function.
+    # Make RunningTest a normal Task that the RegressionManager runs and registers a
+    #  done callback with.
+
+    def __init__(
+        self, test_complete_cb: Callable[[], None], main_task: Task[None]
+    ) -> None:
+        self._test_complete_cb: Callable[[], None] = test_complete_cb
+        self._main_task: Task[None] = main_task
+        self._main_task._add_done_callback(self._test_done_callback)
+
+        self.tasks: List[Task[Any]] = [main_task]
+
+        self._outcome: Union[None, Outcome[None]] = None
+        self._shutdown_errors: list[Outcome[None]] = []
+
+    def _test_done_callback(self, task: Task[None]) -> None:
+        self.tasks.remove(task)
+        # If cancelled, end the Test without additional error. This case would only
+        # occur if a child threw a CancelledError or if the Test was forced to shutdown.
+        if task.cancelled():
+            self.abort(Value(None))
+            return
+        # Handle outcome appropriately and shut down the Test.
+        e = task.exception()
+        if e is None:
+            self.abort(Value(task.result()))
+        elif isinstance(e, TestSuccess):
+            task._log.info("Test stopped early by this task")
+            self.abort(Value(None))
+        else:
+            task._log.warning(e, exc_info=e)
+            self.abort(Error(e))
+
+    def start(self) -> None:
+        cocotb._scheduler_inst._schedule_task_internal(self._main_task)
+        cocotb._scheduler_inst._event_loop()
+
+    def result(self) -> Outcome[None]:
+        if self._outcome is None:  # pragma: no cover
+            raise InternalError("Getting result before test is completed")
+
+        if not isinstance(self._outcome, Error) and self._shutdown_errors:
+            return self._shutdown_errors[0]
+        return self._outcome
+
+    def abort(self, outcome: Outcome[None]) -> None:
+        """Force this test to end early."""
+
+        # If we are shutting down, save any errors
+        if self._outcome is not None:
+            if isinstance(outcome, Error):
+                self._shutdown_errors.append(outcome)
+            return
+
+        # Break into pdb on test end before all Tasks are killed.
+        if _pdb_on_exception and isinstance(outcome, Error):
+            try:
+                pdb.post_mortem(outcome.error.__traceback__)
+            except BaseException:
+                pdb.set_trace()
+
+        # Set outcome and cancel Tasks.
+        self._outcome = outcome
+        for task in self.tasks[:]:
+            task._cancel_now()
+
+        self._test_complete_cb()
+
+    def add_task(self, task: Task[Any]) -> None:
+        self.tasks.append(task)
+        task._add_done_callback(self._task_done_callback)
+
+    def _task_done_callback(self, task: Task[Any]) -> None:
+        self.tasks.remove(task)
+        # if cancelled, do nothing
+        if task.cancelled():
+            return
+        # if there's a Task awaiting this one, don't fail
+        if task.complete in cocotb._scheduler_inst._trigger2tasks:
+            return
+        # if no failure, do nothing
+        e = task.exception()
+        if e is None:
+            return
+        # there was a failure and no one is watching, fail test
+        elif isinstance(e, TestSuccess):
+            task._log.info("Test stopped early by this task")
+            self.abort(Value(None))
+        else:
+            task._log.warning(e, exc_info=e)
+            self.abort(Error(e))
+
+
+def start_soon(
+    coro: Union[Task[ResultType], Coroutine[Trigger, None, ResultType]],
+    *,
+    name: Optional[str] = None,
+) -> Task[ResultType]:
+    """
+    Schedule a :term:`coroutine` to be run concurrently in a :class:`~cocotb.task.Task`.
+
+    Note that this is not an :keyword:`async` function,
+    and the new task will not execute until the calling task yields control.
+
+    Args:
+        coro: A :class:`!Task` or :term:`!coroutine` to be run concurrently.
+        name:
+            The task's name.
+
+            .. versionadded:: 2.0
+
+    Returns:
+        The :class:`~cocotb.task.Task` that is scheduled to be run.
+
+    .. versionadded:: 1.6
+    """
+    task = create_task(coro, name=name)
+    cocotb._scheduler_inst._schedule_task(task)
+    return task
+
+
+@deprecated("Use ``cocotb.start_soon`` instead.")
+async def start(
+    coro: Union[Task[ResultType], Coroutine[Trigger, None, ResultType]],
+    *,
+    name: Optional[str] = None,
+) -> Task[ResultType]:
+    """
+    Schedule a :term:`coroutine` to be run concurrently, then yield control to allow pending tasks to execute.
+
+    The calling task will resume execution before control is returned to the simulator.
+
+    When the calling task resumes, the newly scheduled task may have completed,
+    raised an Exception, or be pending on a :class:`~cocotb.triggers.Trigger`.
+
+    Args:
+        coro: A :class:`!Task` or :term:`!coroutine` to be run concurrently.
+        name:
+            The task's name.
+
+            .. versionadded:: 2.0
+
+    Returns:
+        The :class:`~cocotb.task.Task` that has been scheduled and allowed to execute.
+
+    .. versionadded:: 1.6
+
+    .. deprecated:: 2.0
+        Use :func:`cocotb.start_soon` instead.
+        If you need the scheduled Task to start before continuing the current Task,
+        use an :class:`.Event` to block the current Task until the scheduled Task starts,
+        like so:
+
+        .. code-block:: python
+
+            async def coro(started: Event) -> None:
+                started.set()
+                # Do stuff...
+
+
+            task_started = Event()
+            task = cocotb.start_soon(coro(task_started))
+            await task_started.wait()
+    """
+    task = start_soon(coro, name=name)
+    await NullTrigger()
+    return task
+
+
+def create_task(
+    coro: Union[Task[ResultType], Coroutine[Trigger, None, ResultType]],
+    *,
+    name: Optional[str] = None,
+) -> Task[ResultType]:
+    """
+    Construct a :term:`!coroutine` into a :class:`~cocotb.task.Task` without scheduling the task.
+
+    The task can later be scheduled with :func:`cocotb.start` or :func:`cocotb.start_soon`.
+
+    Args:
+        coro: A :class:`!Task` or a :term:`!coroutine` to be turned into a :class:`!Task`.
+        name:
+            The task's name.
+
+            .. versionadded:: 2.0
+
+    Returns:
+        Either the provided :class:`~cocotb.task.Task` or a new Task wrapping the coroutine.
+
+    .. versionadded:: 1.6
+    """
+    if isinstance(coro, Task):
+        if name is not None:
+            coro.set_name(name)
+        return coro
+    elif isinstance(coro, Coroutine):
+        task = Task[ResultType](coro, name=name)
+        cocotb._regression_manager._running_test.add_task(task)
+        return task
+    elif inspect.iscoroutinefunction(coro):
+        raise TypeError(
+            f"Coroutine function {coro} should be called prior to being scheduled."
+        )
+    elif inspect.isasyncgen(coro):
+        raise TypeError(
+            f"{coro.__qualname__} is an async generator, not a coroutine. "
+            "You likely used the yield keyword instead of await."
+        )
+    else:
+        raise TypeError(
+            f"Attempt to add an object of type {type(coro)} to the scheduler, "
+            f"which isn't a coroutine: {coro!r}\n"
+        )