austin-python 2.3.0__tar.gz → 2.4.0__tar.gz

{austin_python-2.3.0 → austin_python-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: austin-python
-Version: 2.3.0
+Version: 2.4.0
 Summary: Python wrapper for Austin, the CPython frame stack sampler.
 Project-URL: homepage, https://github.com/P403n1x87/austin-python
 Project-URL: documentation, https://austin-python.readthedocs.io

{austin_python-2.3.0 → austin_python-2.4.0}/austin/events.py

@@ -47,31 +47,59 @@ class AustinMetadata(AustinEvent):
 class AustinTask:
     """A node in an asyncio task tree (3.14+ only).
 
-    ``frames`` is this task's own last-known suspended coroutine-chain
-    snapshot -- empty if it was never captured suspended (e.g. it was only
-    ever seen actively running rather than awaiting something). ``awaiting``
-    are the tasks this task is itself awaiting, i.e. the tasks for which this
-    task is the direct waiter.
-
-    ``elapsed`` does NOT describe ``frames``. Austin only re-samples a task's
-    chain (and reports a new node) when its identity has actually changed
-    since the last scan, so the two are always one step apart: ``frames`` is
-    the task's brand new position (just captured because it changed), while
-    ``elapsed`` is how long the task dwelled at its *previous*, now-replaced
-    position -- the earliest point at which that duration could be known at
-    all. None on a task's first-ever sighting, when there is no previous
-    position to report a duration for. Always a wall/CPU time value, or None
-    if Austin was run in pure memory mode (no per-task memory delta exists to
-    report -- see austin's own py_proc.c, _py_proc__maybe_discover_asyncio).
+    ``frames`` is this task's last-known position: its coroutine chain if it
+    was suspended, or the frames it was running if it was running.
+    ``awaiting`` are the tasks this task is itself awaiting, i.e. the tasks
+    for which this task is the direct waiter.
+
+    This is the structure of the tree only. The time tasks spend at their
+    positions is carried by AustinTaskReport (see AustinSample.task_reports)
+    and, while they are running, by the samples they are running at (see
+    AustinSample.running_task).
     """
 
     task_id: int
     name: t.Optional[str]
     frames: t.Tuple[AustinFrame, ...] = ()
-    elapsed: t.Optional[MicroSeconds] = None
     awaiting: t.Tuple["AustinTask", ...] = ()
 
 
+@dataclass(frozen=True)
+class AustinTaskReport:
+    """A report of a task's position (3.14+ only).
+
+    Austin only reports a task's position when it has changed. ``frames`` is
+    the task's new position, and ``elapsed`` is how long the task was
+    *suspended* at its ``previous`` one, which this report replaces -- the
+    earliest point at which that duration could be known at all. Austin
+    doesn't report it: readers work it out as the time of the task's thread's
+    samples while the task held that position without running. It is await
+    time only: the time a task spends running is the time of the samples it
+    is running at (see AustinSample.running_task). Always 0 in CPU mode, where
+    a suspended task uses no CPU.
+
+    ``previous`` is None on a task's first report, which has no previous
+    position (and so ``elapsed`` is 0). A report with no ``frames`` closes the
+    task: it is gone, and ``elapsed`` is the time at its last position. At the
+    end of a stream, each task still alive gets a report with ``frames`` equal
+    to ``previous``, carrying the time it has spent at its position since.
+
+    Each report is attached to exactly one sample, so summing ``elapsed``
+    over every sample's reports counts each duration once.
+    """
+
+    task_id: int
+    name: t.Optional[str]
+    frames: t.Tuple[AustinFrame, ...]
+    previous: t.Optional[t.Tuple[AustinFrame, ...]]
+    elapsed: MicroSeconds
+
+    @property
+    def closing(self) -> bool:
+        """Whether this report closes the task."""
+        return not self.frames
+
+
 @dataclass(frozen=True)
 class AustinSample(AustinEvent):
     """Austin sample."""
@@ -92,7 +120,13 @@ class AustinSample(AustinEvent):
     frames: t.Optional[t.Tuple[AustinFrame, ...]] = None
     gc: t.Optional[bool] = None
     idle: t.Optional[bool] = None
+    # The live tasks owned by this sample's thread, as of this sample.
     tasks: t.Tuple[AustinTask, ...] = ()
+    # The task reports that came with this sample, each one exactly once.
+    task_reports: t.Tuple[AustinTaskReport, ...] = ()
+    # The task this sample's thread was running, if any. The sample's metrics
+    # then belong to that task too, at its latest position (see AustinTask).
+    running_task: t.Optional[int] = None
 
     def key(
         self,