uc-toffee 2.0.0__py3-none-any.whl

toffee/__init__.py

@@ -0,0 +1,267 @@
+from .backend import (
+    BackendCapabilities,
+    BackendHandle,
+    BackendHit,
+    MemoryBackend,
+    RunLimit,
+    RunResult,
+    StopReason,
+    SimulationBackend,
+    XCommClockBackend,
+)
+from ._asyncio_observer import SimulationNotSettledError
+from .decorators import PythonTriggerDefinition, TriggerDefinition, pytrigger, xtrigger
+from .components import Driver, Monitor, SignalDriver
+from .agent import Agent
+from .scoreboard import (
+    AcceptedDriver,
+    CheckContext,
+    Difference,
+    MissingExpectedError,
+    ObservedMonitor,
+    Scoreboard,
+    ScoreboardAssociationError,
+    ScoreboardError,
+    ScoreboardIncompleteError,
+    ScoreboardMismatch,
+    ScoreboardMode,
+    ScoreboardStatus,
+    ScoreboardTimeoutError,
+    structural_differences,
+)
+from .transfers import MISSING, TransferState, XTransfer
+from .coverage import (
+    Bin,
+    BinKind,
+    BinSpec,
+    CoverageDatabase,
+    CoverageMergeError,
+    CoverageSample,
+    CoverageSchemaError,
+    CoverGroup,
+    CoverGroupDef,
+    CoverPointDef,
+    CrossDef,
+    Iff,
+    IllegalBinError,
+    IllegalHit,
+    IllegalPolicy,
+    OverlapPolicy,
+)
+from .data import (
+    Bundle,
+    BundleValue,
+    Field,
+    PackedArray,
+    PackedLayout,
+    PackedView,
+    split_packed,
+)
+from .async_drivers import AsyncDriver, AsyncSingleCycleDriver, DriverIncompleteError
+from .sync_drivers import SyncDriver, SyncSingleCycleDriver
+from .staged_drivers import AsyncMultiCycleDriver, DriveStage, SyncMultiCycleDriver
+from .combinators import AllOf, AnyOf
+from .events import (
+    ConditionEvent,
+    EdgeEvent,
+    FsmEvent,
+    LogicValue,
+    PhaseEvent,
+    XEvent,
+    XEventKind,
+    XPhase,
+)
+from .ir import (
+    bits,
+    BitsType,
+    BoolType,
+    FSM,
+    FsmSpec,
+    Hold,
+    Next,
+    Sequence,
+    SequenceSpec,
+    State,
+    Wait,
+    Within,
+    XExpr,
+)
+from .external import AsyncioEventTrigger, QueueTrigger, TaskComplete, WallTimeout
+from .interfaces import Decoupled, ReadyValid, Role, Transfer
+from .monitors import MonitorClosedError, MonitorOverflowError, ReadyValidMonitor, SamplingMonitor
+from .reactor import (
+    Registration,
+    Subscription,
+    SubscriptionOverflowError,
+    Reactor,
+)
+from .subscriptions import (
+    BoundSubscriptionSpec,
+    XSubscriptionSpec,
+    on,
+)
+from .execution import Execution
+from .protocols import drive_ready_valid
+from .signals import as_xdata
+from .triggers import (
+    ClockCycles,
+    CompiledTrigger,
+    ConditionMode,
+    DriveStable,
+    FallingEdge,
+    PhaseTrigger,
+    PythonPredicateTrigger,
+    RisingEdge,
+    SimTimeout,
+    Value,
+    ValueChange,
+    XTrigger,
+)
+
+__all__ = [
+    "bits",
+    "BitsType",
+    "BoolType",
+    "Agent",
+    "SimulationNotSettledError",
+    "AcceptedDriver",
+    "BackendHandle",
+    "BackendCapabilities",
+    "BackendHit",
+    "Bundle",
+    "BundleValue",
+    "Bin",
+    "BinKind",
+    "BinSpec",
+    "BoundSubscriptionSpec",
+    "AllOf",
+    "AnyOf",
+    "AsyncioEventTrigger",
+    "ClockCycles",
+    "CheckContext",
+    "CompiledTrigger",
+    "ConditionMode",
+    "ConditionEvent",
+    "CoverageDatabase",
+    "CoverageMergeError",
+    "CoverageSample",
+    "CoverageSchemaError",
+    "build_unified_coverage_model",
+    "CoverGroup",
+    "CoverGroupDef",
+    "CoverPointDef",
+    "CrossDef",
+    "Decoupled",
+    "DriveStable",
+    "Difference",
+    "Driver",
+    "SignalDriver",
+    "SyncDriver",
+    "SyncSingleCycleDriver",
+    "SyncMultiCycleDriver",
+    "EdgeEvent",
+    "FallingEdge",
+    "Field",
+    "FSM",
+    "FsmSpec",
+    "FsmEvent",
+    "generate_unified_coverage_report",
+    "generate_unified_coverage_site",
+    "Hold",
+    "Next",
+    "LogicValue",
+    "Iff",
+    "IllegalBinError",
+    "IllegalHit",
+    "IllegalPolicy",
+    "MemoryBackend",
+    "MISSING",
+    "MissingExpectedError",
+    "MonitorOverflowError",
+    "MonitorClosedError",
+    "Monitor",
+    "ObservedMonitor",
+    "OverlapPolicy",
+    "PackedArray",
+    "PackedLayout",
+    "PackedView",
+    "parse_lcov",
+    "PhaseEvent",
+    "PhaseTrigger",
+    "PythonPredicateTrigger",
+    "QueueTrigger",
+    "AsyncDriver",
+    "DriverIncompleteError",
+    "AsyncSingleCycleDriver",
+    "AsyncMultiCycleDriver",
+    "DriveStage",
+    "Registration",
+    "render_unified_coverage_html",
+    "ReadyValid",
+    "ReadyValidMonitor",
+    "SamplingMonitor",
+    "RisingEdge",
+    "RunLimit",
+    "RunResult",
+    "Role",
+    "Scoreboard",
+    "ScoreboardAssociationError",
+    "ScoreboardError",
+    "ScoreboardIncompleteError",
+    "ScoreboardMismatch",
+    "ScoreboardMode",
+    "ScoreboardStatus",
+    "ScoreboardTimeoutError",
+    "StopReason",
+    "Sequence",
+    "SequenceSpec",
+    "Execution",
+    "SimulationBackend",
+    "SimTimeout",
+    "State",
+    "Subscription",
+    "SubscriptionOverflowError",
+    "TaskComplete",
+    "Transfer",
+    "TransferState",
+    "Value",
+    "ValueChange",
+    "WallTimeout",
+    "Wait",
+    "Within",
+    "XEvent",
+    "XEventKind",
+    "XExpr",
+    "XPhase",
+    "Reactor",
+    "XCommClockBackend",
+    "XTrigger",
+    "XTransfer",
+    "XSubscriptionSpec",
+    "on",
+    "as_xdata",
+    "pytrigger",
+    "split_packed",
+    "structural_differences",
+    "xtrigger",
+    "TriggerDefinition",
+    "PythonTriggerDefinition",
+    "drive_ready_valid",
+]
+
+
+_LAZY_REPORT_EXPORTS = {
+    "build_unified_coverage_model",
+    "generate_unified_coverage_report",
+    "generate_unified_coverage_site",
+    "parse_lcov",
+    "render_unified_coverage_html",
+}
+
+
+def __getattr__(name: str):
+    if name in _LAZY_REPORT_EXPORTS:
+        from . import coverage_report
+
+        return getattr(coverage_report, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

toffee/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

toffee/_artifacts.py

@@ -0,0 +1,56 @@
+"""Atomic files and identities for the runner's exclusively owned directory."""
+from __future__ import annotations
+
+import gzip
+from hashlib import file_digest
+import json
+import os
+from pathlib import Path
+import tempfile
+from typing import Any
+
+
+def fingerprint(path: Path) -> dict[str, Any]:
+    if path.is_symlink() or not path.is_file() or path.resolve() != path:
+        raise ValueError(f"artifact is not a regular non-symlink file: {path}")
+    with path.open("rb") as stream:
+        digest = file_digest(stream, "sha256").hexdigest()
+    return {"path": str(path), "size": path.stat().st_size, "sha256": digest}
+
+
+def write(path: Path, value: Any, *, compressed: bool = False) -> dict[str, Any]:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, name = tempfile.mkstemp(prefix=".pending-", dir=path.parent)
+    pending = Path(name)
+    try:
+        with os.fdopen(descriptor, "wb") as raw:
+            if compressed:
+                with gzip.GzipFile(fileobj=raw, mode="wb", filename="", mtime=0) as stream:
+                    for part in json.JSONEncoder(separators=(",", ":")).iterencode(value):
+                        stream.write(part.encode())
+            else:
+                raw.write((json.dumps(value, indent=2, ensure_ascii=False) + "\n").encode())
+            raw.flush()
+            os.fsync(raw.fileno())
+        pending.replace(path)
+        sync_directory(path.parent)
+    finally:
+        pending.unlink(missing_ok=True)
+    return fingerprint(path)
+
+
+def sync_directory(path: Path) -> None:
+    descriptor = os.open(path, os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def read_checked(row: dict[str, Any], root: Path, *, compressed: bool = False) -> Any:
+    path = Path(row["path"])
+    if not path.is_relative_to(root) or fingerprint(path) != row:
+        raise ValueError(f"artifact identity or ownership mismatch: {path}")
+    opener = gzip.open if compressed else open
+    with opener(path, "rt", encoding="utf-8") as stream:
+        return json.load(stream)

toffee/_asyncio_observer.py

@@ -0,0 +1,164 @@
+"""Observe native asyncio callbacks; never select or execute tasks ourselves."""
+
+from __future__ import annotations
+
+import asyncio
+from contextvars import ContextVar
+from typing import Any
+
+
+current_domain: ContextVar[CallbackDomain | None] = ContextVar(
+    "toffee_callback_domain", default=None,
+)
+_observers: dict[asyncio.AbstractEventLoop, _LoopObserver] = {}
+_MISSING = object()
+
+
+class SimulationNotSettledError(RuntimeError):
+    """Immediate simulation work exceeded the configured settling budget."""
+
+
+class _PendingCall:
+    __slots__ = ("domain", "callback", "handle")
+
+    def __init__(self, domain: CallbackDomain, callback: Any) -> None:
+        self.domain = domain
+        self.callback = callback
+        self.handle: asyncio.Handle | None = None
+
+    def __call__(self, *args: Any) -> None:
+        try:
+            self.callback(*args)
+        finally:
+            self.domain.pending.discard(self)
+            # Break the Handle -> callback -> Handle cycle on the hot path.
+            self.handle = None
+
+    def __repr__(self) -> str:
+        return f"observed({self.callback!r})"
+
+
+class _LoopObserver:
+    def __init__(self, loop: asyncio.AbstractEventLoop) -> None:
+        if not isinstance(loop, asyncio.BaseEventLoop):
+            raise RuntimeError(
+                "Execution callback observation requires an asyncio.BaseEventLoop; "
+                f"unsupported loop: {type(loop).__module__}.{type(loop).__name__}"
+            )
+        self.loop = loop
+        self.original = original = loop.call_soon
+        self.original_attribute = vars(loop).get("call_soon", _MISSING)
+        self.users: set[CallbackDomain] = set()
+
+        def call_soon(callback, *args, context=None):
+            domain = current_domain.get() if context is None else context.get(current_domain)
+            if domain is None or domain.closed or domain.observer is not self:
+                # Task yields commonly have no arguments. Avoid allocating an
+                # unpacked keyword call on every unrelated host continuation.
+                if not args:
+                    return original(callback, context=context)
+                return original(callback, *args, context=context)
+            # Let the original entry validate invalid callbacks, including its
+            # debug-only coroutine check. Wrapping must not hide those errors.
+            if not callable(callback) or (
+                loop.get_debug()
+                and (asyncio.iscoroutine(callback) or asyncio.iscoroutinefunction(callback))
+            ):
+                return original(callback, *args, context=context)
+            call = _PendingCall(domain, callback)
+            domain.pending.add(call)
+            try:
+                if not args:
+                    handle = original(call, context=context)
+                elif len(args) == 1:
+                    handle = original(call, args[0], context=context)
+                else:
+                    handle = original(call, *args, context=context)
+            except BaseException:
+                domain.pending.discard(call)
+                raise
+            call.handle = handle
+            return handle
+
+        self.hook = call_soon
+        try:
+            loop.call_soon = call_soon
+        except (AttributeError, TypeError) as error:
+            raise RuntimeError("event loop does not support callback observation") from error
+
+    @classmethod
+    def attach(cls, domain: CallbackDomain) -> _LoopObserver:
+        loop = asyncio.get_running_loop()
+        observer = _observers.get(loop)
+        if observer is None:
+            observer = cls(loop)
+            _observers[loop] = observer
+        else:
+            observer.check()
+        observer.users.add(domain)
+        return observer
+
+    def check(self) -> None:
+        if self.loop.call_soon is not self.hook:
+            raise RuntimeError(
+                "loop.call_soon changed during Execution; "
+                "callback settlement can no longer be guaranteed"
+            )
+
+    def detach(self, domain: CallbackDomain) -> None:
+        self.users.discard(domain)
+        if self.users:
+            return
+        # A host-installed replacement belongs to the host, even if it wraps us.
+        if self.loop.call_soon is self.hook:
+            if self.original_attribute is _MISSING:
+                delattr(self.loop, "call_soon")
+            else:
+                self.loop.call_soon = self.original_attribute
+        _observers.pop(self.loop, None)
+
+
+class CallbackDomain:
+    def __init__(self, max_settle_rounds: int) -> None:
+        self.pending: set[_PendingCall] = set()
+        self.closed = False
+        self.max_settle_rounds = max_settle_rounds
+        self._detached = False
+        self.observer = _LoopObserver.attach(self)
+
+    async def settle(self, backend: Any) -> None:
+        self.observer.check()
+        rounds = 0
+        while self.pending and not self.closed:
+            # Only our registered Handles are inspected, never the loop queue
+            # or Task internals. A cancelled Handle won't call our finally.
+            for call in tuple(self.pending):
+                if call.handle is not None and call.handle.cancelled():
+                    self.pending.discard(call)
+                    call.handle = None
+                    call.callback = None
+            if not self.pending:
+                return
+            if rounds >= self.max_settle_rounds:
+                callbacks = ", ".join(repr(call) for call in list(self.pending)[:3])
+                phase = getattr(backend, "phase", None)
+                raise SimulationNotSettledError(
+                    f"simulation did not settle at tick={getattr(backend, 'tick', '?')} "
+                    f"phase={getattr(phase, 'name', phase)} after {rounds} rounds; "
+                    f"{len(self.pending)} pending callbacks: {callbacks}"
+                )
+            await asyncio.sleep(0)
+            rounds += 1
+            self.observer.check()
+
+    def stop(self) -> None:
+        self.closed = True
+        # Scheduled callbacks still run normally, with their original owner.
+        self.pending.clear()
+
+    def close(self) -> None:
+        if self._detached:
+            return
+        self.stop()
+        self.observer.detach(self)
+        self._detached = True

toffee/_cleanup.py

@@ -0,0 +1,27 @@
+"""Preserve the original failure while reporting independent cleanup errors."""
+
+from __future__ import annotations
+
+
+def raise_cleanup_errors(
+    message: str, errors: list[BaseException], primary: BaseException | None = None,
+) -> None:
+    unique: list[BaseException] = [primary] if primary is not None else []
+
+    def retain(error: BaseException) -> None:
+        if any(error is previous for previous in unique):
+            return
+        if isinstance(error, BaseExceptionGroup):
+            for nested in error.exceptions:
+                retain(nested)
+        else:
+            unique.append(error)
+
+    for error in errors:
+        retain(error)
+    if len(unique) == 1:
+        if unique[0] is not primary:
+            raise unique[0]
+    elif unique:
+        raise BaseExceptionGroup(message, unique)
+    # With only the primary failure, let the owning context propagate it.

toffee/_context.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .reactor import Reactor
+
+_current_reactor: ContextVar["Reactor | None"] = ContextVar(
+    "toffee_current_reactor", default=None
+)
+
+
+def current_reactor() -> "Reactor":
+    reactor = _current_reactor.get()
+    if reactor is None:
+        raise RuntimeError("XTrigger must be awaited inside an active Execution")
+    return reactor
+
+
+def bind_reactor(reactor: "Reactor | None") -> Token["Reactor | None"]:
+    return _current_reactor.set(reactor)
+
+
+def reset_reactor(token: Token["Reactor | None"]) -> None:
+    _current_reactor.reset(token)

toffee/_coverage_capture.py

@@ -0,0 +1,43 @@
+"""Private, runner-owned capture. Ordinary library use has no global collector."""
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any
+from weakref import WeakSet
+
+_sink: ContextVar[Any] = ContextVar("toffee_coverage_capture", default=None)
+_suspended: ContextVar[bool] = ContextVar("toffee_coverage_capture_suspended", default=False)
+_live: WeakSet[Any] = WeakSet()
+
+
+def register(group: Any) -> None:
+    if _suspended.get():
+        return
+    _live.add(group)
+    sink = _sink.get()
+    if sink is not None:
+        sink.register(group)
+
+
+def live_groups():
+    return tuple(_live)
+
+
+@contextmanager
+def capture(sink: Any):
+    token = _sink.set(sink)
+    try:
+        yield
+    finally:
+        _sink.reset(token)
+
+
+@contextmanager
+def suspended():
+    token = _suspended.set(True)
+    try:
+        with capture(None):
+            yield
+    finally:
+        _suspended.reset(token)