cocotb 1.7.1__cp310-cp310-win32.whl → 1.8.0rc1__cp310-cp310-win32.whl

cocotb/task.py

@@ -0,0 +1,325 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+import collections.abc
+import inspect
+import os
+import typing
+import warnings
+from asyncio import CancelledError, InvalidStateError
+
+import cocotb
+import cocotb.triggers
+from cocotb import outcomes
+from cocotb.log import SimLog
+from cocotb.result import ReturnValue
+from cocotb.utils import extract_coro_stack, lazy_property, remove_traceback_frames
+
+T = typing.TypeVar("T")
+Self = typing.TypeVar("Self")
+
+# Sadly the Python standard logging module is very slow so it's better not to
+# make any calls by testing a boolean flag first
+_debug = "COCOTB_SCHEDULER_DEBUG" in os.environ
+
+
+class Task(typing.Coroutine[typing.Any, typing.Any, T]):
+    """Concurrently executing task.
+
+    This class is not intended for users to directly instantiate.
+    Use :func:`cocotb.create_task` to create a Task object,
+    or use :func:`cocotb.start_soon` or :func:`cocotb.start` to
+    create a Task and schedule it to run.
+
+    .. versionchanged:: 1.8.0
+        Moved to the ``cocotb.task`` module.
+    """
+
+    _name: str = "Task"  # class name of schedulable task
+    _id_count = 0  # used by the scheduler for debug
+
+    def __init__(self, inst):
+
+        if isinstance(inst, collections.abc.Coroutine):
+            self._natively_awaitable = True
+        elif inspect.isgenerator(inst):
+            self._natively_awaitable = False
+        elif inspect.iscoroutinefunction(inst):
+            raise TypeError(
+                "Coroutine function {} should be called prior to being "
+                "scheduled.".format(inst)
+            )
+        elif inspect.isasyncgen(inst):
+            raise TypeError(
+                "{} is an async generator, not a coroutine. "
+                "You likely used the yield keyword instead of await.".format(
+                    inst.__qualname__
+                )
+            )
+        else:
+            raise TypeError(
+                f"{inst} isn't a valid coroutine! Did you forget to use the yield keyword?"
+            )
+        self._coro = inst
+        self._started = False
+        self._outcome: outcomes.Outcome = None
+        self._trigger: typing.Optional[cocotb.triggers.Trigger] = None
+        self._cancelled: typing.Optional[CancelledError] = None
+
+        self._task_id = self._id_count
+        type(self)._id_count += 1
+        self.__name__ = f"{type(self)._name} {self._task_id}"
+        self.__qualname__ = self.__name__
+
+    @lazy_property
+    def log(self) -> SimLog:
+        # Creating a logger is expensive, only do it if we actually plan to
+        # log anything
+        return SimLog(f"cocotb.{self.__qualname__}.{self._coro.__qualname__}")
+
+    @property
+    def retval(self) -> T:
+        """Return the result of the Task.
+
+        If the Task ran to completion, the result is returned.
+        If the Task failed with an exception, the exception is re-raised.
+        If the Task is not yet complete, a :exc:`RuntimeError` is raised.
+
+        .. deprecated:: 1.7.0
+        """
+        warnings.warn(
+            "Deprecated in favor of the result() method. "
+            "Replace `task.retval` with `task.result()`.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        if self._outcome is None:
+            raise RuntimeError("coroutine is not complete")
+        return self._outcome.get()
+
+    @property
+    def _finished(self) -> bool:
+        """``True`` if the Task is finished executing.
+
+        .. deprecated:: 1.7.0
+        """
+        warnings.warn(
+            "Deprecated in favor of the done() method. "
+            "Replace `task._finished` with `task.done()`.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self._outcome is not None
+
+    def __iter__(self: Self) -> Self:
+        # for use in "yield from" statements
+        return self
+
+    def __str__(self) -> str:
+        return f"<{self.__name__}>"
+
+    def _get_coro_stack(self) -> typing.Any:
+        """Get the coroutine callstack of this Task."""
+        coro_stack = extract_coro_stack(self._coro)
+
+        # Remove Trigger.__await__() from the stack, as it's not really useful
+        if self._natively_awaitable and len(coro_stack):
+            if coro_stack[-1].name == "__await__":
+                coro_stack.pop()
+
+        return coro_stack
+
+    def __repr__(self) -> str:
+        coro_stack = self._get_coro_stack()
+
+        if cocotb.scheduler._current_task is self:
+            fmt = "<{name} running coro={coro}()>"
+        elif self.done():
+            fmt = "<{name} finished coro={coro}() outcome={outcome}>"
+        elif self._trigger is not None:
+            fmt = "<{name} pending coro={coro}() trigger={trigger}>"
+        elif not self._started:
+            fmt = "<{name} created coro={coro}()>"
+        else:
+            fmt = "<{name} adding coro={coro}()>"
+
+        try:
+            coro_name = coro_stack[-1].name
+        # coro_stack may be empty if:
+        # - exhausted generator
+        # - finished coroutine
+        except IndexError:
+            coro_name = self._coro.__name__
+
+        repr_string = fmt.format(
+            name=self.__name__,
+            coro=coro_name,
+            trigger=self._trigger,
+            outcome=self._outcome,
+        )
+        return repr_string
+
+    def _advance(self, outcome: outcomes.Outcome) -> typing.Any:
+        """Advance to the next yield in this coroutine.
+
+        Args:
+            outcome: The :any:`outcomes.Outcome` object to resume with.
+
+        Returns:
+            The object yielded from the coroutine or None if coroutine finished
+
+        """
+        try:
+            self._started = True
+            return outcome.send(self._coro)
+        except ReturnValue as e:
+            self._outcome = outcomes.Value(e.retval)
+        except StopIteration as e:
+            self._outcome = outcomes.Value(e.value)
+        except BaseException as e:
+            self._outcome = outcomes.Error(
+                remove_traceback_frames(e, ["_advance", "send"])
+            )
+
+    def send(self, value: typing.Any) -> typing.Any:
+        return self._coro.send(value)
+
+    def throw(self, exc: BaseException) -> typing.Any:
+        return self._coro.throw(exc)
+
+    def close(self) -> None:
+        return self._coro.close()
+
+    def kill(self) -> None:
+        """Kill a coroutine."""
+        if self._outcome is not None:
+            # already finished, nothing to kill
+            return
+
+        if _debug:
+            self.log.debug("kill() called on coroutine")
+        # todo: probably better to throw an exception for anyone waiting on the coroutine
+        self._outcome = outcomes.Value(None)
+        cocotb.scheduler._unschedule(self)
+
+    def join(self) -> "cocotb.triggers.Join":
+        """Return a trigger that will fire when the wrapped coroutine exits."""
+        return cocotb.triggers.Join(self)
+
+    def has_started(self) -> bool:
+        """Return ``True`` if the Task has started executing."""
+        return self._started
+
+    def cancel(self, msg: typing.Optional[str] = None) -> None:
+        """Cancel a Task's further execution.
+
+        When a Task is cancelled, a :exc:`asyncio.CancelledError` is thrown into the Task.
+        """
+        self._cancelled = CancelledError(msg)
+        warnings.warn(
+            "Calling this method will cause a CancelledError to be thrown in the "
+            "Task sometime in the future.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        self.kill()
+
+    def cancelled(self) -> bool:
+        """Return ``True`` if the Task was cancelled."""
+        return self._cancelled is not None
+
+    def done(self) -> bool:
+        """Return ``True`` if the Task has finished executing."""
+        return self._outcome is not None or self.cancelled()
+
+    def result(self) -> T:
+        """Return the result of the Task.
+
+        If the Task ran to completion, the result is returned.
+        If the Task failed with an exception, the exception is re-raised.
+        If the Task was cancelled, the CancelledError is re-raised.
+        If the coroutine is not yet complete, a :exc:`asyncio.InvalidStateError` is raised.
+        """
+        if not self.done():
+            raise InvalidStateError("result is not yet available")
+        elif self.cancelled():
+            raise self._cancelled
+        else:
+            return self._outcome.get()
+
+    def exception(self) -> typing.Optional[BaseException]:
+        """Return the exception of the Task.
+
+        If the Task ran to completion, ``None`` is returned.
+        If the Task failed with an exception, the exception is returned.
+        If the Task was cancelled, the CancelledError is re-raised.
+        If the coroutine is not yet complete, a :exc:`asyncio.InvalidStateError` is raised.
+        """
+        if not self.done():
+            raise InvalidStateError("result is not yet available")
+        elif self.cancelled():
+            raise self._cancelled
+        elif isinstance(self._outcome, outcomes.Error):
+            return self._outcome.error
+        else:
+            return None
+
+    def __bool__(self) -> bool:
+        """``True`` if Task is not done.
+
+        .. deprecated:: 1.7.0
+        """
+        warnings.warn(
+            "Deprecated in favor of the done() method. "
+            "Replace with `not task.done()`.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return not self.done()
+
+    def __await__(self) -> typing.Generator[typing.Any, typing.Any, T]:
+        # It's tempting to use `return (yield from self._coro)` here,
+        # which bypasses the scheduler. Unfortunately, this means that
+        # we can't keep track of the result or state of the coroutine,
+        # things which we expose in our public API. If you want the
+        # efficiency of bypassing the scheduler, remove the `@coroutine`
+        # decorator from your `async` functions.
+
+        # Hand the coroutine back to the scheduler trampoline.
+        return (yield self)
+
+
+class _RunningCoroutine(Task[T]):
+    """
+    The result of calling a :any:`cocotb.coroutine` decorated coroutine.
+
+    All this class does is provide some extra attributes.
+
+    .. versionchanged:: 1.8.0
+        Moved to the ``cocotb.task`` module.
+    """
+
+    def __init__(self, inst, parent):
+        super().__init__(inst)
+        self._parent = parent
+        self.__doc__ = parent._func.__doc__
+        self.module = parent._func.__module__
+        self.funcname = parent._func.__name__
+
+
+class _RunningTest(_RunningCoroutine[T]):
+    """
+    The result of calling a :class:`cocotb.test` decorated object.
+
+    All this class does is change ``__name__`` to show "Test" instead of "Task".
+
+    .. versionchanged:: 1.8.0
+        Moved to the ``cocotb.task`` module.
+    """
+
+    _name: str = "Test"
+
+    def __init__(self, inst, parent):
+        super().__init__(inst, parent)
+        self.__name__ = f"{type(self)._name} {self.funcname}"
+        self.__qualname__ = self.__name__

cocotb/triggers.py

@@ -33,11 +33,12 @@ import warnings
 from collections.abc import Awaitable
 from decimal import Decimal
 from numbers import Real
-from typing import Optional, Union
+from typing import Any, Coroutine, Optional, TypeVar, Union
 
 import cocotb
 from cocotb import outcomes, simulator
 from cocotb.log import SimLog
+from cocotb.task import Task
 from cocotb.utils import (
     ParametrizedSingleton,
     get_sim_steps,
@@ -46,6 +47,8 @@ from cocotb.utils import (
     remove_traceback_frames,
 )
 
+T = TypeVar("T")
+
 
 def _pointer_str(obj):
     """
@@ -189,6 +192,10 @@ class Timer(GPITrigger):
                When *units* is ``'step'``,
                the timestep is determined by the simulator (see :make:var:`COCOTB_HDL_TIMEPRECISION`).
 
+            round_mode (str, optional):
+                String specifying how to handle time values that sit between time steps
+                (one of ``'error'``, ``'round'``, ``'ceil'``, ``'floor'``).
+
         Examples:
 
             >>> await Timer(100, units='ps')
@@ -778,7 +785,7 @@ class _AggregateWaitable(Waitable):
 
         # Do some basic type-checking up front, rather than waiting until we
         # await them.
-        allowed_types = (Trigger, Waitable, cocotb.decorators.Task)
+        allowed_types = (Trigger, Waitable, Task)
         for trigger in self.triggers:
             if not isinstance(trigger, allowed_types):
                 raise TypeError(
@@ -793,8 +800,7 @@ class _AggregateWaitable(Waitable):
         return "{}({})".format(
             type(self).__qualname__,
             ", ".join(
-                repr(Join(t)) if isinstance(t, cocotb.decorators.Task) else repr(t)
-                for t in self.triggers
+                repr(Join(t)) if isinstance(t, Task) else repr(t) for t in self.triggers
             ),
         )
 
@@ -934,7 +940,12 @@ class ClockCycles(Waitable):
         return fmt.format(type(self).__qualname__, self.signal, self.num_cycles)
 
 
-async def with_timeout(trigger, timeout_time, timeout_unit="step"):
+async def with_timeout(
+    trigger: Union[Trigger, Waitable, Task, Coroutine[Any, Any, T]],
+    timeout_time: Union[float, Decimal],
+    timeout_unit: str = "step",
+    round_mode: Optional[str] = None,
+) -> T:
     r"""
     Waits on triggers or coroutines, throws an exception if it waits longer than the given time.
 
@@ -972,12 +983,15 @@ async def with_timeout(trigger, timeout_time, timeout_unit="step"):
         await with_timeout(First(coro, event.wait()), 100, 'ns')
 
     Args:
-        trigger (:class:`~cocotb.triggers.Trigger`, :class:`~cocotb.triggers.Waitable`, :class:`~cocotb.decorators.Task`, or :term:`python:coroutine`):
+        trigger (:class:`~cocotb.triggers.Trigger`, :class:`~cocotb.triggers.Waitable`, :class:`~cocotb.task.Task`, or :term:`python:coroutine`):
             A single object that could be right of an :keyword:`await` expression in cocotb.
         timeout_time (numbers.Real or decimal.Decimal):
             Simulation time duration before timeout occurs.
         timeout_unit (str, optional):
             Units of timeout_time, accepts any units that :class:`~cocotb.triggers.Timer` does.
+        round_mode (str, optional):
+            String specifying how to handle time values that sit between time steps
+            (one of ``'error'``, ``'round'``, ``'ceil'``, ``'floor'``).
 
     Returns:
         First trigger that completed if timeout did not occur.
@@ -1005,7 +1019,9 @@ async def with_timeout(trigger, timeout_time, timeout_unit="step"):
         shielded = False
     else:
         shielded = True
-    timeout_timer = cocotb.triggers.Timer(timeout_time, timeout_unit)
+    timeout_timer = cocotb.triggers.Timer(
+        timeout_time, timeout_unit, round_mode=round_mode
+    )
     res = await First(timeout_timer, trigger)
     if res is timeout_timer:
         if not shielded:

cocotb/types/logic_array.py

@@ -28,6 +28,8 @@ class LogicArray(Array[Logic]):
     used.
     Like :class:`Array`, if no *range* argument is given, it is deduced from the length
     of the iterable or bit string used to initialize the variable.
+    If a *range* argument is given, but no value,
+    the array is filled with the default value of Logic().
 
     .. code-block:: python3
 
@@ -37,12 +39,15 @@ class LogicArray(Array[Logic]):
         >>> LogicArray([0, True, "X"])
         LogicArray('01X', Range(2, 'downto', 0))
 
-        >>> LogicArray(0xA)                     # picks smallest range that can fit the value
+        >>> LogicArray(0xA)  # picks smallest range that can fit the value
         LogicArray('1010', Range(3, 'downto', 0))
 
-        >>> LogicArray(-4, Range(0, "to", 3))   # will sign-extend
+        >>> LogicArray(-4, Range(0, "to", 3))  # will sign-extend
         LogicArray('1100', Range(0, 'to', 3))
 
+        >>> LogicArray(range=Range(0, "to", 3))  # default values
+        LogicArray('XXXX', Range(0, 'to', 3))
+
     :class:`LogicArray`\ s support the same operations as :class:`Array`;
     however, it enforces the condition that all elements must be a :class:`Logic`.
 
@@ -115,12 +120,38 @@ class LogicArray(Array[Logic]):
 
     __slots__ = ()
 
+    @typing.overload
     def __init__(
         self,
         value: typing.Union[int, typing.Iterable[LogicConstructibleT], BinaryValue],
+        range: typing.Optional[Range],
+    ):
+        ...
+
+    @typing.overload
+    def __init__(
+        self,
+        value: typing.Union[
+            int, typing.Iterable[LogicConstructibleT], BinaryValue, None
+        ],
+        range: Range,
+    ):
+        ...
+
+    def __init__(
+        self,
+        value: typing.Union[
+            int, typing.Iterable[LogicConstructibleT], BinaryValue, None
+        ] = None,
         range: typing.Optional[Range] = None,
     ) -> None:
-        if isinstance(value, int):
+        if value is None and range is None:
+            raise ValueError(
+                "at least one of the value and range input parameters must be given"
+            )
+        if value is None:
+            self._value = [Logic() for _ in range]
+        elif isinstance(value, int):
             if value < 0:
                 bitlen = int.bit_length(value + 1) + 1
             else: