sensorium-trace 0.18.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. sensorium/__init__.py +0 -0
  2. sensorium/__main__.py +4 -0
  3. sensorium/_c/rt/sensorium_c_rt.c +1446 -0
  4. sensorium/_typescript/package-lock.json +68 -0
  5. sensorium/_typescript/package.json +39 -0
  6. sensorium/_typescript/src/bindings.mjs +792 -0
  7. sensorium/_typescript/src/cap.mjs +227 -0
  8. sensorium/_typescript/src/capabilities.mjs +40 -0
  9. sensorium/_typescript/src/dbg.mjs +348 -0
  10. sensorium/_typescript/src/escape.mjs +351 -0
  11. sensorium/_typescript/src/focus.mjs +135 -0
  12. sensorium/_typescript/src/hook.mjs +127 -0
  13. sensorium/_typescript/src/index.mjs +1 -0
  14. sensorium/_typescript/src/naming.mjs +63 -0
  15. sensorium/_typescript/src/positions.mjs +37 -0
  16. sensorium/_typescript/src/probe.mjs +246 -0
  17. sensorium/_typescript/src/qualname.mjs +236 -0
  18. sensorium/_typescript/src/redact.mjs +711 -0
  19. sensorium/_typescript/src/register.mjs +15 -0
  20. sensorium/_typescript/src/resolve.mjs +260 -0
  21. sensorium/_typescript/src/rt.mjs +798 -0
  22. sensorium/_typescript/src/setup.mjs +11 -0
  23. sensorium/_typescript/src/tally.mjs +164 -0
  24. sensorium/_typescript/src/tasks.mjs +175 -0
  25. sensorium/_typescript/src/transform.mjs +800 -0
  26. sensorium/_typescript/src/vite.mjs +99 -0
  27. sensorium/c/__init__.py +8 -0
  28. sensorium/c/cc.py +612 -0
  29. sensorium/c/cli.py +60 -0
  30. sensorium/c/convert.py +669 -0
  31. sensorium/c/decode.py +300 -0
  32. sensorium/c/driver.py +365 -0
  33. sensorium/c/dwarf.py +706 -0
  34. sensorium/c/format.py +271 -0
  35. sensorium/c/pkg.py +187 -0
  36. sensorium/c/plan.py +277 -0
  37. sensorium/cli.py +140 -0
  38. sensorium/driver.py +47 -0
  39. sensorium/exit.py +33 -0
  40. sensorium/invocations.py +83 -0
  41. sensorium/limits.py +253 -0
  42. sensorium/mcp/__init__.py +0 -0
  43. sensorium/mcp/audit.py +162 -0
  44. sensorium/mcp/child.py +240 -0
  45. sensorium/mcp/cmd.py +101 -0
  46. sensorium/mcp/jsonrpc.py +172 -0
  47. sensorium/mcp/result.py +187 -0
  48. sensorium/mcp/schema.py +390 -0
  49. sensorium/mcp/server.py +493 -0
  50. sensorium/mcp/tools.py +299 -0
  51. sensorium/paths.py +80 -0
  52. sensorium/query/__init__.py +0 -0
  53. sensorium/query/caps.py +150 -0
  54. sensorium/query/dbg_dialects.py +64 -0
  55. sensorium/query/diff_cmd.py +748 -0
  56. sensorium/query/diff_notes.py +117 -0
  57. sensorium/query/exceptions_c.py +263 -0
  58. sensorium/query/exceptions_cmd.py +788 -0
  59. sensorium/query/exceptions_group.py +571 -0
  60. sensorium/query/exceptions_invocation.py +487 -0
  61. sensorium/query/exceptions_rust.py +683 -0
  62. sensorium/query/exceptions_typescript.py +688 -0
  63. sensorium/query/expr.py +606 -0
  64. sensorium/query/failures_cmd.py +306 -0
  65. sensorium/query/flow_cmd.py +778 -0
  66. sensorium/query/flow_report.py +128 -0
  67. sensorium/query/flow_values.py +195 -0
  68. sensorium/query/fmt.py +280 -0
  69. sensorium/query/frame_cmd.py +237 -0
  70. sensorium/query/grep_cmd.py +156 -0
  71. sensorium/query/help.py +18 -0
  72. sensorium/query/info_cmd.py +527 -0
  73. sensorium/query/info_rust.py +214 -0
  74. sensorium/query/info_typescript.py +261 -0
  75. sensorium/query/js_inspect.py +394 -0
  76. sensorium/query/moves.py +254 -0
  77. sensorium/query/redact_cmd.py +304 -0
  78. sensorium/query/refocus_cmd.py +661 -0
  79. sensorium/query/refocus_env.py +493 -0
  80. sensorium/query/refocus_facts.py +269 -0
  81. sensorium/query/refocus_licence.py +187 -0
  82. sensorium/query/refocus_report.py +327 -0
  83. sensorium/query/refocus_rust.py +537 -0
  84. sensorium/query/refocus_threads.py +197 -0
  85. sensorium/query/refocus_typescript.py +756 -0
  86. sensorium/query/refocus_world.py +666 -0
  87. sensorium/query/runs_cmd.py +213 -0
  88. sensorium/query/rust_debug.py +176 -0
  89. sensorium/query/sites.py +171 -0
  90. sensorium/query/tree_cmd.py +511 -0
  91. sensorium/query/tree_threads.py +168 -0
  92. sensorium/query/vocab.py +723 -0
  93. sensorium/query/watch_cmd.py +657 -0
  94. sensorium/record/__init__.py +0 -0
  95. sensorium/record/boot.py +797 -0
  96. sensorium/record/boot_io.py +141 -0
  97. sensorium/record/budget.py +135 -0
  98. sensorium/record/capture.py +433 -0
  99. sensorium/record/children.py +755 -0
  100. sensorium/record/children_merge.py +179 -0
  101. sensorium/record/elide.py +55 -0
  102. sensorium/record/fingerprint.py +26 -0
  103. sensorium/record/thread_starts.py +261 -0
  104. sensorium/record/tracer.py +798 -0
  105. sensorium/record/tracer_exc.py +199 -0
  106. sensorium/record/tracer_frames.py +618 -0
  107. sensorium/redact.py +304 -0
  108. sensorium/redact_content.py +156 -0
  109. sensorium/redact_key.py +317 -0
  110. sensorium/redact_store.py +502 -0
  111. sensorium/redact_values.py +433 -0
  112. sensorium/store/__init__.py +0 -0
  113. sensorium/store/db.py +284 -0
  114. sensorium/store/gc.py +360 -0
  115. sensorium/store/payloads.py +69 -0
  116. sensorium/store/reader.py +438 -0
  117. sensorium/store/writer.py +283 -0
  118. sensorium/ts/__init__.py +10 -0
  119. sensorium/ts/build.py +783 -0
  120. sensorium/ts/cli.py +130 -0
  121. sensorium/ts/driver.py +472 -0
  122. sensorium/ts/focus.py +146 -0
  123. sensorium/ts/harness.py +314 -0
  124. sensorium/ts/ingest.py +380 -0
  125. sensorium/ts/invocation.py +252 -0
  126. sensorium/ts/pkg.py +167 -0
  127. sensorium/ts/redaction.py +64 -0
  128. sensorium/ts/spool.py +168 -0
  129. sensorium/ts/truncation.py +81 -0
  130. sensorium/ts/wrapper.py +255 -0
  131. sensorium_trace-0.18.2.dist-info/METADATA +245 -0
  132. sensorium_trace-0.18.2.dist-info/RECORD +135 -0
  133. sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
  134. sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
  135. sensorium_trace-0.18.2.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,618 @@
1
+ """Which frames the recorder decides to watch, and the identities it mints
2
+ for them.
3
+
4
+ Split out of `tracer.py` at that file's 800-line ceiling. Nothing here writes
5
+ an event: the whole file answers one question -- given a code object, a task
6
+ or a caller, is it traced, is it focused, and which fingerprint does it feed?
7
+ `Tracer` inherits the decisions as `_FrameDecisions`, so `self` is the same
8
+ object with the same locks and tables; these are one recorder's internals
9
+ across its files, not separate modules with surfaces of their own.
10
+
11
+ `_SENSORIUM_DIR` lives HERE because `_classify` is its only reader, and a
12
+ monkeypatch of the guard must therefore name THIS module -- see
13
+ `tests/test_tracer_serials.py::test_the_recorders_own_code_is_never_traced`.
14
+ """
15
+
16
+ import gc
17
+ import inspect
18
+ import sys
19
+ import time
20
+ import weakref
21
+ from fnmatch import fnmatch
22
+ from pathlib import Path
23
+
24
+ from sensorium import redact_values as rv
25
+ from sensorium.record.capture import capture_exc, plain_str
26
+ from sensorium.record.fingerprint import Fingerprint
27
+
28
+ _SENSORIUM_DIR = str(Path(__file__).resolve().parent.parent)
29
+ _CO_GENERATOR, _CO_COROUTINE, _CO_ASYNC_GENERATOR = 0x20, 0x80, 0x200
30
+ # Derived, never restated: the suspendable flag set is written down ONCE, and
31
+ # `_frame_kind` -- its only reader -- ladders over the same three flags. A flag
32
+ # added to one and not the other would silently label a new suspendable kind
33
+ # "generator".
34
+ _GENLIKE = _CO_GENERATOR | _CO_COROUTINE | _CO_ASYNC_GENERATOR
35
+
36
+
37
+ def _frame_kind(code) -> str:
38
+ """Which kind of frame this code opens (frames.kind): every traced code
39
+ object opens one -- arc 2 -- so this is a label, not a gate."""
40
+ flags = code.co_flags
41
+ if not flags & _GENLIKE:
42
+ return "function"
43
+ if flags & _CO_ASYNC_GENERATOR:
44
+ return "async_generator"
45
+ if flags & _CO_COROUTINE:
46
+ return "coroutine"
47
+ return "generator"
48
+
49
+
50
+ def module_name_for(file: str, root: Path) -> str | None:
51
+ try:
52
+ rel = Path(file).resolve().relative_to(root)
53
+ except ValueError:
54
+ return None
55
+ parts = list(rel.with_suffix("").parts)
56
+ if parts and parts[-1] == "__init__":
57
+ parts.pop()
58
+ return ".".join(parts) if parts else None
59
+
60
+
61
+ class FocusSpec:
62
+ def __init__(self, entries: list[str]) -> None:
63
+ self._entries = []
64
+ for e in entries:
65
+ mod, _, qual = e.partition(":")
66
+ self._entries.append((e, mod, qual or None))
67
+
68
+ def __bool__(self) -> bool:
69
+ return bool(self._entries)
70
+
71
+ def _hit(self, mod, qual, module, qualname) -> bool:
72
+ if module != mod:
73
+ return False
74
+ return qual is None or qualname == qual or qualname.startswith(qual + ".")
75
+
76
+ def matches(self, module: str | None, qualname: str) -> bool:
77
+ if module is None:
78
+ return False
79
+ return any(self._hit(m, q, module, qualname) for _e, m, q in self._entries)
80
+
81
+ def entries_matching(self, module: str | None, qualname: str) -> list[str]:
82
+ """Every entry, as the user wrote it, that this code satisfies."""
83
+ if module is None:
84
+ return []
85
+ return [e for e, m, q in self._entries if self._hit(m, q, module, qualname)]
86
+
87
+
88
+ class WindowSpec:
89
+ """The one function whose activations bound line-level capture.
90
+
91
+ Accepts `module:qualname` to name it unambiguously, or a bare `qualname`
92
+ that matches that name in ANY module. The bare form is why two same-named
93
+ functions across a `--focus` set could share a window: the old matcher was
94
+ `qual == self.window`, a bare-string equality that a `module:qualname`
95
+ target could never satisfy (so it silently matched nothing) and that a bare
96
+ name matched in every module at once. `key()` still resolves bare vs
97
+ `module:qualname` matching; its non-None result marks the window TARGET,
98
+ whose descendants are in the window by ANCESTRY. Nothing is counted.
99
+ """
100
+ def __init__(self, spec: str | None) -> None:
101
+ if spec is None:
102
+ self._mod, self._qual = None, None
103
+ else:
104
+ mod, sep, qual = spec.partition(":")
105
+ self._mod, self._qual = (mod, qual) if sep else (None, mod)
106
+
107
+ def __bool__(self) -> bool:
108
+ return self._qual is not None
109
+
110
+ def key(self, module: str | None, qualname: str):
111
+ """The window key for this code, or None if it is not the window."""
112
+ if self._qual is None or qualname != self._qual:
113
+ return None
114
+ if self._mod is not None and module != self._mod:
115
+ return None
116
+ return (module, qualname)
117
+
118
+
119
+ class _FrameDecisions:
120
+ """`Tracer`'s classification half. Never instantiated on its own:
121
+ every attribute it reads is bound by `Tracer.__init__`."""
122
+
123
+ # -- classification ----------------------------------------------------
124
+ def _decide(self, code):
125
+ d = self._decisions.get(id(code))
126
+ if d is None:
127
+ d = self._classify(code)
128
+ self._decisions[id(code)] = d
129
+ self._seen_codes.append(code)
130
+ return d
131
+
132
+ def _classify(self, code):
133
+ file = code.co_filename
134
+ untraced = (False, None, None, False, "function", None)
135
+ if not file.startswith("/") or file.startswith(_SENSORIUM_DIR):
136
+ return untraced
137
+ p = str(Path(file).resolve())
138
+ rootp = str(self.root)
139
+ if not p.startswith(rootp + "/"):
140
+ return untraced
141
+ if ("/site-packages/" in p or "/.venv/" in p
142
+ or p.startswith(sys.prefix) or p.startswith(sys.base_prefix)):
143
+ return untraced
144
+ rel = p[len(rootp) + 1:]
145
+ if self.include and not any(fnmatch(rel, g) for g in self.include):
146
+ return untraced
147
+ if any(fnmatch(rel, g) for g in self.exclude):
148
+ return untraced
149
+ module = module_name_for(p, self.root)
150
+ focused = self.focus.matches(module, code.co_qualname)
151
+ win_key = self.window.key(module, code.co_qualname)
152
+ return (True, rel, code.co_qualname, focused, _frame_kind(code),
153
+ win_key)
154
+
155
+ def _fp(self, tid: int) -> Fingerprint:
156
+ # `tid` is a per-thread SERIAL (see `_TLS.thread_serial`), the same
157
+ # identity events and frames carry, so two short-lived threads that
158
+ # recycle one OS id still key here to distinct fingerprints.
159
+ with self._fp_lock:
160
+ fp = self._fps.get(tid)
161
+ if fp is None:
162
+ fp = self._fps[tid] = Fingerprint()
163
+ return fp
164
+
165
+ def _fp_for(self, tid: int, task) -> Fingerprint:
166
+ """The fingerprint this event belongs to: the task's when it ran in
167
+ an asyncio task, else the thread's (spec D6). One event, one
168
+ fingerprint -- the thread's covers exactly the events with
169
+ task_id NULL, which is what makes the two rows comparable
170
+ separately.
171
+
172
+ The task's entry is normally already there: `_task_serial` creates
173
+ it when it mints the serial, so that a task minted at a YIELD,
174
+ RESUME or LINE -- none of which reach this function -- still has a
175
+ row. The get-or-create stays because this is the only path that
176
+ needs the object, and a task whose serial predates that rule would
177
+ otherwise silently lose its events.
178
+
179
+ A thread that runs a causal event gets a row even when every one of
180
+ them ran inside a task, so its COUNT may be 0. That zero is a fact
181
+ with content -- "this thread ran traced code, all of it inside
182
+ asyncio tasks" -- and it is not the same fact as having no row,
183
+ which every reader here takes to mean the thread ran no traced code
184
+ at all. A loop thread entered through stdlib
185
+ (`Thread(target=asyncio.run, ...)`) is exactly that case: without
186
+ this, it would vanish from `fingerprints()` and be counted among the
187
+ threads that did nothing.
188
+ """
189
+ if task is None:
190
+ return self._fp(tid)
191
+ if tid not in self._fps: # unlocked probe; the create is locked
192
+ self._fp(tid)
193
+ with self._fp_lock:
194
+ fp = self._task_fps.get(task)
195
+ if fp is None:
196
+ fp = self._task_fps[task] = Fingerprint()
197
+ return fp
198
+
199
+ def _parent_of(self, tls, caller):
200
+ """The live entry for `caller`, or None -- and None is an answer.
201
+
202
+ A hit requires the address to be live AND the code to match. Arc 2
203
+ opens frames for suspendable code too; while one is suspended its
204
+ entry is not here but in `_parked` (see `_park`/`_adopt`), and a
205
+ caller is by definition running, so this map is the right place to
206
+ look. The code check is what keeps a recycled address from answering
207
+ for a frame that is not the caller's."""
208
+ if caller is None:
209
+ return None
210
+ entry = tls.live.get(id(caller))
211
+ if entry is None or entry[1] is not caller.f_code:
212
+ return None
213
+ return entry
214
+
215
+ def _park(self, tls, frame, entry) -> None:
216
+ """Hand a just-suspended frame's entry to whatever thread resumes it.
217
+
218
+ It MOVES the entry out of the suspending thread's map rather than
219
+ copying it. A copy left behind is a second owner of one mutable
220
+ entry, and on the very shape this exists for -- a frame opened on one
221
+ thread and closed on another -- the copy is never removed again,
222
+ because the thread that closes the frame can only reach its own map.
223
+ Published after the YIELD row is written, so no other thread can
224
+ record this frame's RESUME before the YIELD it answers.
225
+ """
226
+ key = id(frame)
227
+ tls.live.pop(key, None)
228
+ displaced = None
229
+ with self._parked_lock:
230
+ prev = self._parked.get(key)
231
+ # A new frame can be born at an address whose previous owner was
232
+ # closed without PY_UNWIND (see `detect_silent_generator_close`).
233
+ # The previous entry has to be reconciled BEFORE this write
234
+ # replaces it, or that activation is gone and the reader keeps
235
+ # calling it suspended.
236
+ if (prev is not None and prev is not entry
237
+ and getattr(self, "_silent_gen_close", False)):
238
+ displaced = prev
239
+ self._parked[key] = entry
240
+ if displaced is not None:
241
+ self._reconcile_if_closed(displaced, tls)
242
+
243
+ def _adopt(self, tls, frame, code):
244
+ """The parked entry for this activation, moved into THIS thread's
245
+ live map -- or None, which is an answer.
246
+
247
+ `entry[1] is code` is the same identity guard `_parent_of` uses, and
248
+ it is what keeps `id(frame)` sound across the hand-off: a parked
249
+ frame is alive (whatever suspended it holds it), so its address
250
+ cannot be recycled while its entry waits here. `depth` and the
251
+ parent stay exactly as the frame was opened. That is why a frame's
252
+ rows can name two threads and both be true: the frames row keeps the
253
+ thread that OPENED it, each event carries the thread that produced
254
+ THAT event.
255
+ """
256
+ key = id(frame)
257
+ stale = None
258
+ with self._parked_lock:
259
+ entry = self._parked.get(key)
260
+ if entry is None or entry[1] is not code:
261
+ return None
262
+ # Same guard as the overwrite in `_park`: a parked entry whose
263
+ # owner no longer holds THIS frame is a closed generator's
264
+ # leftover, not the activation being resumed.
265
+ if (getattr(self, "_silent_gen_close", False)
266
+ and not _owner_holds(entry, frame)):
267
+ del self._parked[key]
268
+ stale = entry
269
+ else:
270
+ del self._parked[key]
271
+ if stale is not None:
272
+ self._reconcile_if_closed(stale, tls)
273
+ return None
274
+ tls.live[key] = entry
275
+ return entry
276
+
277
+ def _live_entry(self, tls, frame, code):
278
+ """This activation's open-frame entry, or None: this thread's live
279
+ map first, then the parked table for a frame another thread opened.
280
+
281
+ A live hit whose code does not match is a stale entry at a recycled
282
+ address, not an answer -- it must not shadow a parked entry for the
283
+ frame that is actually running here, so it is treated as a miss."""
284
+ entry = tls.live.get(id(frame))
285
+ if entry is not None and entry[1] is code:
286
+ return entry
287
+ return self._adopt(tls, frame, code)
288
+
289
+ def _note_caller(self, payload, caller) -> None:
290
+ """When there is no parent frame, record WHO called instead of
291
+ guessing: the caller's interned code if it is traced (code that
292
+ started before recording did, so it never opened a frame), or the
293
+ literal "untraced" (the event loop, a C callback's Python caller in a
294
+ library, sensorium's own boot). No caller at all writes nothing,
295
+ which is distinct from both."""
296
+ if caller is None:
297
+ return
298
+ ccode = caller.f_code
299
+ traced, _rel, cqual, _f, _kind, _w = self._decide(ccode)
300
+ if traced:
301
+ payload["caller_code"] = self.writer.intern_code(
302
+ ccode.co_filename, cqual, ccode.co_firstlineno)
303
+ else:
304
+ payload["caller"] = "untraced"
305
+
306
+ def _bind_asyncio(self):
307
+ """(`_get_running_loop`, `current_task`) from the asyncio the PROGRAM
308
+ imported, or None if it is not (fully) there yet. Both are C
309
+ functions (`_asyncio`) on 3.12-3.14; `_get_running_loop` returns
310
+ None outside a loop instead of raising, which is why it is the gate.
311
+
312
+ Guarded because `sys.modules["asyncio"]` is a slot the PROGRAM can
313
+ write: a stand-in module's `__getattr__` is program code, and
314
+ `getattr(..., None)` swallows only AttributeError, so anything else
315
+ it raises would come out of a monitoring callback. A failed bind is
316
+ not counted and not remembered -- the next event simply retries, the
317
+ same way it does while a real asyncio is still half-imported."""
318
+ try:
319
+ mod = sys.modules.get("asyncio")
320
+ events = getattr(mod, "events", None)
321
+ get_loop = getattr(events, "_get_running_loop", None)
322
+ cur_task = getattr(mod, "current_task", None)
323
+ except BaseException:
324
+ return None
325
+ if get_loop is None or cur_task is None:
326
+ return None
327
+ self._asyncio = (get_loop, cur_task)
328
+ return self._asyncio
329
+
330
+ def _count_task_error(self) -> None:
331
+ with self._task_lock:
332
+ self.task_errors += 1
333
+
334
+ def _task_serial(self, tls):
335
+ """The minted serial of the asyncio task running on this thread right
336
+ now, or None: no asyncio, no running loop, no current task, or a task
337
+ object that broke the lookup (counted in `task_errors`, never raised
338
+ into the program). Only IDENTITY failures are counted: a task whose
339
+ `get_name` raises still gets its serial and still attributes its
340
+ events, and is recorded as a task with no name, not as an error.
341
+ Must be called inside an `in_hook` region: a Task subclass's
342
+ `get_name` is program code.
343
+
344
+ Minting is also where the task's `Fingerprint` is created, so that
345
+ every `tasks` row has a `task_fingerprints` row whatever kind of
346
+ event brought the task into view (spec D6). A task that is minted
347
+ here and never reaches `_fp_for` ends with a zero-count row, which
348
+ says it ran no causal event while traced -- a different fact from
349
+ having no row at all."""
350
+ if "asyncio" not in sys.modules:
351
+ return None
352
+ fns = self._asyncio or self._bind_asyncio()
353
+ if fns is None:
354
+ return None
355
+ get_loop, cur_task = fns
356
+ try:
357
+ if get_loop() is None:
358
+ return None
359
+ task = cur_task()
360
+ except BaseException:
361
+ self._count_task_error()
362
+ return None
363
+ if task is None:
364
+ return None
365
+ cache = tls.task_cache
366
+ if cache is not None and cache[0] is task:
367
+ return cache[1]
368
+ try:
369
+ with self._task_lock:
370
+ serial = self._task_serials.get(task)
371
+ minted = serial is None
372
+ if minted:
373
+ self._next_task += 1
374
+ serial = self._next_task
375
+ self._task_serials[task] = serial
376
+ except BaseException: # hostile __hash__/__eq__ on a subclass
377
+ self._count_task_error()
378
+ return None
379
+ if minted:
380
+ try:
381
+ name = plain_str(task.get_name())
382
+ except BaseException:
383
+ name = None
384
+ self.writer.add_task(serial, name, tls.thread_serial)
385
+ # Every `tasks` row gets its `task_fingerprints` row, HERE and
386
+ # not in `_fp_for`, because a serial is minted at any event with
387
+ # a current task -- YIELD, RESUME and LINE included -- and
388
+ # `_fp_for` only ever runs on a causal one. A task whose only
389
+ # traced frames are a RESUMEd generator otherwise had a row in
390
+ # one table and none in the other, which every reader of the
391
+ # pair takes for a lossy recording. A zero-count row means "this
392
+ # task ran no causal event while traced"; no row at all means
393
+ # the task was never recorded.
394
+ #
395
+ # The `_task_lock` block above is CLOSED by this point -- it is
396
+ # the `with` inside the `try` further up -- so `_fp_lock` is
397
+ # taken with no other tracer lock held, as everywhere else.
398
+ with self._fp_lock:
399
+ self._task_fps.setdefault(serial, Fingerprint())
400
+ tls.task_cache = (task, serial)
401
+ return serial
402
+
403
+ def _arm_silent_owner(self, entry, frame) -> None:
404
+ """Remember who owns a frame that just parked, when closes can be silent.
405
+
406
+ Slot 7 is the yield line. Slot 8 is a weak reference to the
407
+ generator, coroutine, or async generator. A strong reference would
408
+ keep the generator alive and stop the program from closing it. The
409
+ frame itself cannot be weak-referenced. Created here, outside
410
+ `_parked_lock`: allocating a weak reference can collect another
411
+ generator, and a callback that took the lock from inside `_park`
412
+ would deadlock.
413
+ """
414
+ if not getattr(self, "_silent_gen_close", False):
415
+ return
416
+ owner = _owner_of(frame)
417
+ try:
418
+ wref = weakref.ref(owner) if owner is not None else None
419
+ except TypeError:
420
+ wref = None
421
+ while len(entry) < 9:
422
+ entry.append(None)
423
+ entry[7] = frame.f_lineno
424
+ entry[8] = wref
425
+
426
+ def _reconcile_if_closed(self, entry, tls) -> bool:
427
+ """Record an abandoned close for a parked entry whose owner is gone.
428
+
429
+ Returns whether the entry is finished (already reconciled, or
430
+ reconciled now). A still-suspended owner is left parked: that is
431
+ the residual state the reader derives from the last YIELD.
432
+ """
433
+ if not getattr(self, "_silent_gen_close", False):
434
+ return False
435
+ done = self._silent_closed
436
+ fid = entry[0]
437
+ if fid in done:
438
+ return True
439
+ if _owner_status(_entry_owner(entry)) != "closed":
440
+ return False
441
+ self._write_abandoned(entry, tls)
442
+ done.add(fid)
443
+ return True
444
+
445
+ def _write_abandoned(self, entry, tls) -> None:
446
+ """The RESUME plus unwind a fixed interpreter would have emitted.
447
+
448
+ One `GeneratorExit`, one serial, the yield line saved at park. No
449
+ RAISE row: a control-flow exception is not one, which is the same
450
+ rule `_on_throw` already follows. Not fingerprinted, because a
451
+ RESUME is not a causal event.
452
+ """
453
+ was = tls.in_hook
454
+ tls.in_hook = True
455
+ try:
456
+ exc = GeneratorExit()
457
+ serial = tls.cf_exc.identify(exc)
458
+ payload = {"thrown": rv.exc(capture_exc(exc, serial))}
459
+ rv.stats["values"] += rv.count(payload)
460
+ line = entry[7] if len(entry) > 7 else None
461
+ self.writer.add_event(
462
+ time.monotonic_ns(), tls.thread_serial, "RESUME",
463
+ entry[0], entry[2], line, payload,
464
+ task_id=self._task_serial(tls))
465
+ unwind = rv.exc(capture_exc(exc, serial))
466
+ rv.stats["values"] += rv.count_capture(unwind)
467
+ self.writer.close_frame(entry[0], None, "unwind", unwind)
468
+ finally:
469
+ tls.in_hook = was
470
+
471
+ def _finish_silent_parked(self) -> None:
472
+ """Close parked frames whose owners died before uninstall.
473
+
474
+ Runs with monitoring already off, so nothing else will unpark
475
+ these entries. An owner that is still suspended stays parked and
476
+ is dropped with the table, which is what "suspended at end of
477
+ recording" is.
478
+ """
479
+ if not getattr(self, "_silent_gen_close", False):
480
+ return
481
+ with self._parked_lock:
482
+ items = list(self._parked.items())
483
+ tls = self._tls
484
+ for key, entry in items:
485
+ if self._reconcile_if_closed(entry, tls):
486
+ with self._parked_lock:
487
+ if self._parked.get(key) is entry:
488
+ del self._parked[key]
489
+
490
+
491
+ def detect_silent_generator_close() -> bool:
492
+ """Whether closing a suspended generator emits no `PY_UNWIND`.
493
+
494
+ Some CPython point releases (3.13.5 among them) drop a simple
495
+ generator without `PY_THROW` or `PY_UNWIND`. Later point releases and
496
+ 3.12 and 3.15 do emit them. The difference is measured here, once,
497
+ with a tool id this recorder does not keep, rather than read off
498
+ `sys.version`. A probe that cannot take a tool id reports the fixed
499
+ behavior, so a busy debugger is not turned into a second close.
500
+ """
501
+ def probe():
502
+ yield 1
503
+
504
+ code = probe.__code__
505
+ saw = {"unwind": False}
506
+
507
+ def on_unwind(seen, _offset, _exc):
508
+ if seen is code:
509
+ saw["unwind"] = True
510
+
511
+ M = sys.monitoring
512
+ E = M.events
513
+ tool = None
514
+ for candidate in (M.DEBUGGER_ID, M.COVERAGE_ID, M.OPTIMIZER_ID):
515
+ try:
516
+ M.use_tool_id(candidate, "sensorium-gen-probe")
517
+ except ValueError:
518
+ continue
519
+ tool = candidate
520
+ break
521
+ if tool is None:
522
+ return False
523
+ try:
524
+ M.register_callback(tool, E.PY_UNWIND, on_unwind)
525
+ M.set_events(tool, E.PY_UNWIND)
526
+ M.restart_events()
527
+ gen = probe()
528
+ try:
529
+ next(gen)
530
+ except StopIteration:
531
+ return False
532
+ gen.close()
533
+ finally:
534
+ for fn in (
535
+ lambda: M.set_events(tool, 0),
536
+ lambda: M.register_callback(tool, E.PY_UNWIND, None),
537
+ lambda: M.free_tool_id(tool),
538
+ ):
539
+ try:
540
+ fn()
541
+ except Exception:
542
+ pass
543
+ return not saw["unwind"]
544
+
545
+
546
+ def _owner_of(frame):
547
+ """The generator-like object whose frame this is, or None."""
548
+ for obj in gc.get_referrers(frame):
549
+ if _frame_of(obj) is frame:
550
+ return obj
551
+ return None
552
+
553
+
554
+ def _frame_of(obj):
555
+ for attr in ("gi_frame", "cr_frame", "ag_frame"):
556
+ try:
557
+ owned = getattr(obj, attr, None)
558
+ except Exception:
559
+ continue
560
+ if owned is not None:
561
+ return owned
562
+ return None
563
+
564
+
565
+ def _entry_owner(entry):
566
+ return entry[8] if len(entry) > 8 else None
567
+
568
+
569
+ def _owner_holds(entry, frame) -> bool:
570
+ """True when this parked entry is still the activation `frame` is.
571
+
572
+ No owner recorded means the probe did not find one; keep the old
573
+ identity rule rather than dropping a resume we cannot check.
574
+ """
575
+ wref = _entry_owner(entry)
576
+ if wref is None:
577
+ return True
578
+ obj = wref()
579
+ if obj is None:
580
+ return False
581
+ return _frame_of(obj) is frame
582
+
583
+
584
+ _CLOSED_STATES = frozenset({"GEN_CLOSED", "CORO_CLOSED", "AGEN_CLOSED"})
585
+ _SUSPENDED_STATES = frozenset({
586
+ "GEN_SUSPENDED", "CORO_SUSPENDED", "AGEN_SUSPENDED"})
587
+
588
+
589
+ def _owner_status(wref) -> str:
590
+ """`closed`, `suspended`, `running`, or `unknown`.
591
+
592
+ A dead weak reference is `closed`: a generator object is collected
593
+ only after its finalizer has closed it, and on a silent interpreter
594
+ that close left no event.
595
+ """
596
+ if wref is None:
597
+ return "unknown"
598
+ obj = wref()
599
+ if obj is None:
600
+ return "closed"
601
+ state = _genlike_state(obj)
602
+ if state in _CLOSED_STATES:
603
+ return "closed"
604
+ if state in _SUSPENDED_STATES:
605
+ return "suspended"
606
+ if state is None:
607
+ return "unknown"
608
+ return "running"
609
+
610
+
611
+ def _genlike_state(obj):
612
+ if inspect.isgenerator(obj):
613
+ return inspect.getgeneratorstate(obj)
614
+ if inspect.iscoroutine(obj):
615
+ return inspect.getcoroutinestate(obj)
616
+ if inspect.isasyncgen(obj):
617
+ return inspect.getasyncgenstate(obj)
618
+ return None