testflows.machine 0.1.4__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.
@@ -0,0 +1,3231 @@
1
+ # Copyright 2026 Katteli Inc.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ """What the SDK's calls return: plain records, each with `as_json`."""
15
+
16
+ from __future__ import annotations
17
+
18
+ import dataclasses
19
+ import datetime
20
+ from dataclasses import dataclass, field
21
+ from typing import Any, Optional, overload
22
+
23
+ from testflows.machine._core import fs as _fs
24
+ from testflows.machine._core import branches as _branches
25
+ from testflows.machine._core import breakpoints as _breakpoints
26
+ from testflows.machine._core import branching as _branching
27
+ from testflows.machine._core import control as _control
28
+ from testflows.machine._core import debugger as _debugger
29
+ from testflows.machine._core import hashes as _hashes
30
+ from testflows.machine._core import ipc as _ipc
31
+ from testflows.machine._core import machines as _machines
32
+ from testflows.machine._core import stepping as _stepping
33
+ from testflows.machine._core import variables as _variables
34
+ from testflows.machine._core import timespec as _timespec
35
+
36
+ from .errors import InvalidArgument
37
+
38
+ _BYTES_PER_MB = 1024 * 1024
39
+
40
+
41
+ class _Record:
42
+ """A record's `as_json`, written once."""
43
+
44
+ def as_json(self) -> dict[str, Any]:
45
+ """The fields as a JSON-serializable dict.
46
+
47
+ Returns:
48
+ dict[str, Any]: One key per attribute.
49
+ """
50
+ # Every subclass is a dataclass; this base is not, so say so to the
51
+ # type checker rather than to `asdict`.
52
+ record: Any = self
53
+ return dataclasses.asdict(record)
54
+
55
+
56
+ @dataclass(frozen=True, order=True, init=False)
57
+ class Point(_Record):
58
+ """A time in a run's history: the machine's clock, in nanoseconds.
59
+
60
+ A point means the same time on every run. Each run resolves it to its
61
+ own entry, the first one at the last time at or before the point. Add
62
+ or subtract a duration to move it: an int of nanoseconds, a str such as
63
+ `"10ms"`, or a `timedelta`. Subtract one point from another for the
64
+ nanoseconds between them.
65
+
66
+ Example:
67
+ >>> booted = run.checkpoint("booted")
68
+ >>> later = booted.place.point + "10ms"
69
+ >>> branch = run.fork(at=later)
70
+ >>> str(Point("1.5s") - "500ms")
71
+ '1.000000000s'
72
+
73
+ Args:
74
+ vtime (int or str): Nanoseconds, or a time such as `"1.194s"`.
75
+
76
+ Attributes:
77
+ vtime (int): The machine's clock, in nanoseconds.
78
+ """
79
+
80
+ vtime: int
81
+
82
+ def __init__(self, vtime: "int | str") -> None:
83
+ if isinstance(vtime, str):
84
+ if vtime.startswith("-"):
85
+ raise InvalidArgument(
86
+ f"A point is a time of the run, never before 0: {vtime}."
87
+ )
88
+ ns = _nanoseconds(vtime)
89
+ elif isinstance(vtime, int) and not isinstance(vtime, bool):
90
+ ns = vtime
91
+ else:
92
+ raise InvalidArgument(
93
+ f"A point is nanoseconds or a time such as '1.194s', got {vtime!r}."
94
+ )
95
+ if ns < 0:
96
+ raise InvalidArgument(f"A point is never before 0: {ns} ns.")
97
+ object.__setattr__(self, "vtime", ns)
98
+
99
+ def __add__(self, duration: "int | str | datetime.timedelta") -> "Point":
100
+ return Point(self.vtime + _nanoseconds(duration))
101
+
102
+ def __radd__(self, duration: "int | str | datetime.timedelta") -> "Point":
103
+ return self + duration
104
+
105
+ @overload
106
+ def __sub__(self, other: "Point") -> int: ...
107
+
108
+ @overload
109
+ def __sub__(self, other: "int | str | datetime.timedelta") -> "Point": ...
110
+
111
+ def __sub__(self, other: "Point | int | str | datetime.timedelta") -> "Point | int":
112
+ if isinstance(other, Point):
113
+ return self.vtime - other.vtime
114
+ return Point(self.vtime - _nanoseconds(other))
115
+
116
+ def __str__(self) -> str:
117
+ return _timespec.render_vtime(self.vtime)
118
+
119
+
120
+ def _nanoseconds(duration: "int | str | datetime.timedelta") -> int:
121
+ """A duration in nanoseconds, signed: an int is nanoseconds already, a
122
+ str is a duration such as `"10ms"` or `"-1.5s"`."""
123
+ if isinstance(duration, datetime.timedelta):
124
+ return (duration // datetime.timedelta(microseconds=1)) * _timespec.NS_PER_US
125
+ if isinstance(duration, str):
126
+ try:
127
+ ns = _timespec.parse_duration(duration)
128
+ except _timespec.SpecError as exc:
129
+ raise InvalidArgument(str(exc)) from None
130
+ return -ns if duration.startswith("-") else ns
131
+ if isinstance(duration, int) and not isinstance(duration, bool):
132
+ return duration
133
+ raise InvalidArgument(
134
+ "A duration is nanoseconds, a str such as '10ms' or a timedelta,"
135
+ f" got {duration!r}."
136
+ )
137
+
138
+
139
+ @dataclass(frozen=True)
140
+ class Place(_Record):
141
+ """One entry of one run: where the run is, or where it was.
142
+
143
+ A method that takes a point takes a place on the run that recorded it
144
+ and on its branches forked after it. Anywhere else it is refused,
145
+ since past a fork another run's entry of that id is another state. An
146
+ entry a branch replayed is the branch's own: the branch recorded it
147
+ again, and another run's place for it is refused there too. Use
148
+ `place.point` to take the same time on another run.
149
+
150
+ Attributes:
151
+ run_id (str): The run that recorded the entry: this run, or for an
152
+ entry before it was forked an ancestor.
153
+ entry_id (int): The entry.
154
+ point (Point): Its time.
155
+ vtime_offset (int): Orders the entries that share one time, from 0.
156
+ """
157
+
158
+ run_id: str
159
+ entry_id: int
160
+ point: Point
161
+ vtime_offset: int
162
+
163
+
164
+ @dataclass(frozen=True)
165
+ class Checkpoint(_Record):
166
+ """A saved machine state a run can be started, forked or detached from.
167
+
168
+ A checkpoint is named by `^name` wherever a point is taken, such as
169
+ `run.fork(at="^boot")`, and is taken itself in place of the name. A
170
+ branch lists its ancestors' checkpoints as its own, since its history is
171
+ theirs up to where it was forked.
172
+
173
+ Attributes:
174
+ name (str): The checkpoint's name; an unnamed one is named by its
175
+ entry id.
176
+ place (Place): The entry the state was saved at, and the run that
177
+ recorded it: this run, or for an inherited checkpoint an
178
+ ancestor.
179
+ date (int): When it was taken, in Unix seconds.
180
+ durable (bool): Whether it is in shared storage, so another session
181
+ can start from it.
182
+ """
183
+
184
+ name: str
185
+ place: Place
186
+ date: int
187
+ durable: bool
188
+
189
+
190
+ @dataclass(frozen=True)
191
+ class Entry(_Record):
192
+ """Where one vCPU stopped at the end of a `Run.run`.
193
+
194
+ Attributes:
195
+ vcpu (int): The vCPU.
196
+ entry_id (int): The entry it recorded when it stopped.
197
+ exit (str): Why it stopped, by its exit name: `INSTR_LIMIT` when
198
+ the dispatch ran its instructions, `IO`, `MMIO`, `HLT`,
199
+ `PAUSE`, `HYPERCALL`, `SHUTDOWN` and so on. When the log recorded a
200
+ different event, it follows in parentheses: `IO (EXIT_SHUTDOWN)`
201
+ for a guest that reset through the keyboard controller.
202
+ rip (int): The guest instruction address it stopped at.
203
+ """
204
+
205
+ vcpu: int
206
+ entry_id: int
207
+ exit: str
208
+ rip: int
209
+
210
+
211
+ @dataclass(frozen=True)
212
+ class Clause(_Record):
213
+ """One clause a drive drew from, and how often it applied.
214
+
215
+ Attributes:
216
+ clause (str): The clause as text, such as `when /app:on mode step`.
217
+ matched (int): The iterations the clause applied to. The rest of
218
+ the drive's iterations ran free of it.
219
+ """
220
+
221
+ clause: str
222
+ matched: int
223
+
224
+
225
+ @dataclass(frozen=True)
226
+ class RunResult(_Record):
227
+ """What `Run.run`, `Run.plan` or `Run.play` did.
228
+
229
+ Attributes:
230
+ iterations (int): The iterations that ran. With `until`, the count
231
+ it took for the predicate to hold.
232
+ entry_id (int): The newest entry recorded; 0 when none was.
233
+ entries (tuple[Entry, ...]): Where each vCPU stopped.
234
+ reached (bool): Whether the drive got what it was asked for. False
235
+ only when `until` was given with an `iters` bound and the
236
+ iterations ran out first; True whenever no predicate was named.
237
+ vtime_elapsed (int): How far the run's virtual time moved, in
238
+ nanoseconds. An iteration has no fixed length, so this is the
239
+ measure of how far the drive went; 0 for `Run.play`.
240
+ clauses (tuple[Clause, ...]): The clauses the drive drew from, each
241
+ with the iterations it applied to: the `when` of `Run.run`, or
242
+ the clauses of a plan. Empty for a drive that named none.
243
+ hits (tuple[Breakpoint, ...]): The breakpoints and watchpoints the
244
+ run ended at. Empty when none ended it.
245
+ printed (tuple[str, ...]): The lines the stops that print printed,
246
+ in the order they hit.
247
+ """
248
+
249
+ iterations: int
250
+ entry_id: int
251
+ entries: tuple[Entry, ...]
252
+ reached: bool = True
253
+ vtime_elapsed: int = 0
254
+ clauses: tuple[Clause, ...] = ()
255
+ hits: tuple["Breakpoint", ...] = ()
256
+ printed: tuple[str, ...] = ()
257
+
258
+
259
+ @dataclass(frozen=True)
260
+ class Miss(_Record):
261
+ """One crossing of an entry that did not reproduce it.
262
+
263
+ Attributes:
264
+ entry_id (int): The entry the crossing missed.
265
+ rip (int): Where the machine stood when it stopped.
266
+ rcb (int): The branches it had retired.
267
+ regs_hash (int): Its registers, hashed.
268
+ """
269
+
270
+ entry_id: int
271
+ rip: int
272
+ rcb: int
273
+ regs_hash: int
274
+
275
+
276
+ @dataclass(frozen=True)
277
+ class ReplayResult(_Record):
278
+ """Whether `Run.replay` reproduced what the line it followed recorded.
279
+
280
+ A replay that does not reproduce the recording is a result, not an
281
+ exception: check `converged`, then `diverged` for what differs and
282
+ `Run.diff` for detail.
283
+
284
+ Attributes:
285
+ converged (bool): Whether every replayed entry matched.
286
+ entry_id (int): Where the replay stopped.
287
+ replayed (int): The entries it re-executed.
288
+ diverged (tuple[dict[str, str], ...]): One `{section, a, b}` object
289
+ per machine component whose state differs, such as registers or
290
+ memory; empty when it converged.
291
+ misses (tuple[Miss, ...]): Every crossing that missed, first to
292
+ last, including one a retry then crossed; empty when every entry
293
+ reproduced the first time.
294
+ retry_stopped (str): Why a retry that `retry` allowed did not
295
+ happen: the run could not go back to retry from, and may have
296
+ been stopped or rebuilt trying. Empty when every retry ran.
297
+ overshoot (str): How far the replay passed the recorded stop, and
298
+ the margin it was armed with, when a margin too small for the
299
+ counter's skid is why it diverged. Empty otherwise. A larger
300
+ `limit_margin` or `instr_margin` replays it.
301
+ """
302
+
303
+ converged: bool
304
+ entry_id: int
305
+ replayed: int
306
+ diverged: tuple[dict[str, str], ...]
307
+ misses: tuple[Miss, ...] = ()
308
+ retry_stopped: str = ""
309
+ overshoot: str = ""
310
+
311
+
312
+ @dataclass(frozen=True)
313
+ class Diff(_Record):
314
+ """Two machine states compared at an entry, as `Run.diff` compared them.
315
+
316
+ Attributes:
317
+ converged (bool): Whether the two states match.
318
+ entry_id (int): The entry compared.
319
+ diverged (tuple[dict[str, str], ...]): One `{section, a, b}` object
320
+ per machine component whose state differs; empty when they
321
+ match. `section` names the component: `regs` the registers,
322
+ `mem_hash` the guest memory, `rcb` the retired branch count,
323
+ and the rest a device or a part of the vCPU's state.
324
+ memory_compared (bool): Whether the guest memory was compared.
325
+ False when one entry hashed it and the other did not; then
326
+ `converged` says nothing about memory.
327
+ disk_compared (bool): Whether the guest's disk was compared, on the
328
+ same terms as `memory_compared`.
329
+ """
330
+
331
+ converged: bool
332
+ entry_id: int
333
+ diverged: tuple[dict[str, str], ...]
334
+ memory_compared: bool
335
+ disk_compared: bool
336
+
337
+
338
+ @dataclass(frozen=True)
339
+ class File(_Record):
340
+ """One entry of a directory on a run's disk, as `Fs.ls` lists it.
341
+
342
+ Attributes:
343
+ name (str): The entry's name in its directory.
344
+ kind (str): `file`, `dir`, `link` or `other`.
345
+ size (int): The size in bytes.
346
+ mode (int): The POSIX mode bits.
347
+ mtime (int): The modification time, in Unix seconds.
348
+ """
349
+
350
+ name: str
351
+ kind: str
352
+ size: int
353
+ mode: int
354
+ mtime: int
355
+
356
+
357
+ @dataclass(frozen=True)
358
+ class Listing(_Record):
359
+ """A run as the `runs` listing showed it: a snapshot, not a live read.
360
+
361
+ `Client.runs` fills `Run.listing` with one; a run reached any other way
362
+ has none. `Run.describe` and `Run.state` read the run again.
363
+
364
+ Attributes:
365
+ state (str): The run's state when listed: `running`, `paused`,
366
+ `halted` once the guest shut itself down, `stopped`, `unsaved`,
367
+ `killed`, `died`, `terminated` and so on.
368
+ cpus (int): vCPUs.
369
+ mem (int): Guest memory in MB.
370
+ disk (str): The disk it boots.
371
+ created_at (int): When it was created, in Unix seconds.
372
+ depth (int, optional): Forks from its root; 0 for a root. None in a
373
+ `roots=True` listing.
374
+ running (int, optional): In a `roots=True` listing, how many of the
375
+ tree's runs are running; None otherwise.
376
+ runs (int, optional): In a `roots=True` listing, how many runs the
377
+ tree has; None otherwise.
378
+ disk_bytes (int, optional): With `size=True`, bytes on the
379
+ session's disk; None when the run is not there or unmeasured.
380
+ ram_bytes (int, optional): With `size=True`, bytes resident in its
381
+ machine; None when it is not running or unmeasured.
382
+ local (str, optional): With `size=True`, the state of the session's
383
+ copy: `offloadable`, `in use`, `preloading`, `offloading` or
384
+ `not synced`.
385
+ """
386
+
387
+ state: str
388
+ cpus: int
389
+ mem: int
390
+ disk: str
391
+ created_at: int
392
+ depth: Optional[int]
393
+ running: Optional[int]
394
+ runs: Optional[int]
395
+ disk_bytes: Optional[int]
396
+ ram_bytes: Optional[int]
397
+ local: Optional[str]
398
+
399
+
400
+ @dataclass(frozen=True)
401
+ class State(_Record):
402
+ """What a run's machine is doing, as `Run.state` read it.
403
+
404
+ Attributes:
405
+ state (str): `running`, `paused`, `halted`, `read-only` and so on.
406
+ A `halted` guest shut itself down: the machine still reads and
407
+ forks, and a drive is refused until `start` at a checkpoint.
408
+ A run with no machine reads as the run list shows it, `stopped`
409
+ for one that was stopped.
410
+ activity (str): What it is busy with: `idle`, `running`,
411
+ `checkpointing`, `replaying` and so on. Empty for a run with no
412
+ machine.
413
+ cpus (int): vCPUs.
414
+ vcpu (int): The vCPU that recorded the newest entry.
415
+ mem (int): Guest memory in MB.
416
+ entry_id (int): The newest entry.
417
+ vtime (int): The run's virtual time there, in nanoseconds.
418
+ vtime_offset (int): Orders the entries that share one `vtime`.
419
+ host_cpu (int): The host CPU the machine is on; -1 before it is
420
+ placed.
421
+ switch_prev_tid (int): At a guest scheduling decision, the task
422
+ leaving the CPU; 0 when the machine is not at one.
423
+ switch_next_tid (int): The task taking the CPU there.
424
+ plan (tuple[str, ...]): The clauses the last drive drew from, one
425
+ line each.
426
+ plan_tally (tuple[str, ...]): How many dispatches each clause
427
+ matched, in the order of `plan`.
428
+ """
429
+
430
+ state: str
431
+ activity: str
432
+ cpus: int
433
+ vcpu: int
434
+ mem: int
435
+ entry_id: int
436
+ vtime: int
437
+ vtime_offset: int
438
+ host_cpu: int
439
+ switch_prev_tid: int
440
+ switch_next_tid: int
441
+ plan: tuple[str, ...]
442
+ plan_tally: tuple[str, ...]
443
+
444
+
445
+ @dataclass(frozen=True)
446
+ class RunInfo(_Record):
447
+ """How a run was created, and where it came from, as `Run.describe`
448
+ read it.
449
+
450
+ The options are named as `Client.create` takes them, so a program can
451
+ pass them back, or pass the run as `like`.
452
+
453
+ Attributes:
454
+ id (str): The run's id.
455
+ name (str): The run's name; a branch's is `root/branch`.
456
+ state (str): The state when read, as `Listing.state` names it.
457
+ cpus (int): vCPUs.
458
+ mem (int): Guest memory in MB.
459
+ mem_type (str): Guest memory backing: `auto` or `hugepages`.
460
+ mem_mode (str): How a cold restore maps memory: `auto`, `map` or
461
+ `lazy`.
462
+ disk_id (str): The content hash of the disk it boots, which stays
463
+ the same when the disk is renamed. `Listing.disk` and
464
+ `Client.create` take the NAME; this is what the run holds.
465
+ fs_sync (bool): Whether the root filesystem is mounted `sync`.
466
+ fs_dirsync (bool): Whether it is mounted `dirsync`.
467
+ rng (bool): Whether the guest has a virtio RNG.
468
+ rng_seed (int): The RNG's seed.
469
+ limit (int): Conditional branches a fast dispatch may run, steps in
470
+ step mode; 0 for no limit.
471
+ vtime_base (int): The guest's clock at boot, in Unix seconds.
472
+ vtime_rate (str): How fast virtual time runs against instructions,
473
+ `n/d`.
474
+ vtime_io_cost (int): Virtual nanoseconds each I/O exit costs.
475
+ vtime_rdtsc_cost (int): Virtual nanoseconds each RDTSC exit costs.
476
+ vtime_pause_cost (int): Virtual nanoseconds each PAUSE costs.
477
+ auto_checkpoints (int): Checkpoints every this many entries; 0 for
478
+ never.
479
+ side_dump (bool, optional): Whether each entry records a state dump,
480
+ which `Run.dump(entry=...)` reads; None when the log does not
481
+ say.
482
+ side_trace (bool, optional): Whether each entry records a trace.
483
+ mem_hash (bool, optional): Whether each entry hashes the machine's
484
+ memory; None when the session does not say.
485
+ disk_hash (bool, optional): Whether each entry hashes the machine's
486
+ disk; None when the session does not say.
487
+ parent_id (str): The run a branch was forked from; empty for a root.
488
+ parent_entry_id (int): The entry it was forked at; 0 for a root.
489
+ labels (dict[str, str]): The run's labels.
490
+ keep_output (list[str]): The names of output the run stores though
491
+ its directory drops it.
492
+ drop_output (list[str]): The names of output the run does not
493
+ store.
494
+ rdtsc_exit (bool): Whether every RDTSC is recorded as an entry.
495
+ repeatable (bool): Whether the run records so that recording it
496
+ again repeats it entry by entry.
497
+ repeats_to (int, optional): A repeatable run's first entry whose
498
+ stop another recording need not make, where recording it again
499
+ from the start stops repeating; None when it repeats to its tip
500
+ or is not repeatable.
501
+ host_breaks (tuple[int, ...]): The entries among those that the
502
+ host's clock placed, a dispatch bound or an immediate cancel:
503
+ no recording of the same state stops there again.
504
+ limit_margin (int): How many branches short of each stop the branch
505
+ counter interrupts; 0 for the host's.
506
+ timer_slack (int): How late, in nanoseconds, a timer may be in code
507
+ that takes no exit.
508
+ instr_margin (int): How many instructions short of a stop placed by
509
+ an instruction count the instruction counter interrupts; 0 for
510
+ the host's.
511
+ dispatch_bound (int): The host time, in nanoseconds, a fast
512
+ dispatch may run before it stops; 0 for the default, 1s.
513
+ fast_backstop (int): How many instructions a fast dispatch may run
514
+ with no other stop; 0 for the default, 100,000,000.
515
+ irq_wait (int): How many branches a dispatch runs while an
516
+ interrupt waits for the guest to take it; 0 for the default, 200.
517
+ guest_kernel (str): The version of the kernel the run boots;
518
+ empty for a run that boots firmware.
519
+ machine_abi (int, optional): The oldest machine ABI the run's
520
+ entries were recorded under, fixed when the run was created;
521
+ None when it was not read.
522
+ machine_abi_max (int, optional): The newest machine ABI the run's
523
+ entries were recorded under; a machine replays the run only if
524
+ it supports every ABI from `machine_abi` to this one. None when
525
+ it was not read.
526
+ """
527
+
528
+ id: str
529
+ name: str
530
+ state: str
531
+ cpus: int
532
+ mem: int
533
+ mem_type: str
534
+ mem_mode: str
535
+ disk_id: str
536
+ fs_sync: bool
537
+ fs_dirsync: bool
538
+ rng: bool
539
+ rng_seed: int
540
+ limit: int
541
+ vtime_base: int
542
+ vtime_rate: str
543
+ vtime_io_cost: int
544
+ vtime_rdtsc_cost: int
545
+ vtime_pause_cost: int
546
+ auto_checkpoints: int
547
+ side_dump: Optional[bool]
548
+ side_trace: Optional[bool]
549
+ mem_hash: Optional[bool]
550
+ disk_hash: Optional[bool]
551
+ parent_id: str
552
+ parent_entry_id: int
553
+ labels: dict[str, str] = field(default_factory=dict)
554
+ keep_output: list[str] = field(default_factory=list)
555
+ drop_output: list[str] = field(default_factory=list)
556
+ rdtsc_exit: bool = False
557
+ repeatable: bool = False
558
+ repeats_to: Optional[int] = None
559
+ host_breaks: tuple[int, ...] = ()
560
+ limit_margin: int = 0
561
+ timer_slack: int = 0
562
+ instr_margin: int = 0
563
+ dispatch_bound: int = 0
564
+ fast_backstop: int = 0
565
+ irq_wait: int = 0
566
+ guest_kernel: str = ""
567
+ machine_abi: Optional[int] = None
568
+ machine_abi_max: Optional[int] = None
569
+
570
+
571
+ @dataclass(frozen=True)
572
+ class Mark(_Record):
573
+ """A mark on a run, as `Marks.list` lists it.
574
+
575
+ A mark is a short second name, unique in its run's tree, that reads as
576
+ `%name` wherever a run or a point is taken.
577
+
578
+ Attributes:
579
+ name (str): The mark, without the `%`.
580
+ run_id (str): The run that carries it.
581
+ run_name (str): That run's name.
582
+ """
583
+
584
+ name: str
585
+ run_id: str
586
+ run_name: str
587
+
588
+
589
+ @dataclass(frozen=True)
590
+ class Command(_Record):
591
+ """One command issued to a run, as `Control.log` lists it.
592
+
593
+ Every command that drove or changed the machine is recorded in its log
594
+ with the entries it covered, whichever program issued it.
595
+
596
+ Attributes:
597
+ text (str): The command as the control REPL spells it, such as
598
+ `/s 5` or `/checkpoint booted`.
599
+ start_entry_id (int): The first entry it recorded.
600
+ entry_id (int): The last entry it recorded.
601
+ vcpu (str): For a drive, the vCPU it dispatched, `*` for every
602
+ vCPU; empty for any other command.
603
+ """
604
+
605
+ text: str
606
+ start_entry_id: int
607
+ entry_id: int
608
+ vcpu: str
609
+
610
+
611
+ @dataclass(frozen=True)
612
+ class Exit(_Record):
613
+ """A guest task that has exited, as `Tasks.exits` lists it.
614
+
615
+ `exit_code` is the kernel's encoding, with `signal` and `status` beside
616
+ it: code checking for a crash reads the pair, code checking a program's
617
+ own status reads `status`.
618
+
619
+ Attributes:
620
+ tid (int): The thread that exited.
621
+ tgid (int): Its process.
622
+ exit_code (int): The kernel's wait status, as the guest reports it.
623
+ signal (int): The signal that killed it, 0 if none did.
624
+ status (int): The status it exited with, 0 when a signal killed it.
625
+ outcome (str): How it ended, as `wait` reports it: `status 0`,
626
+ `status 1`, `killed by SIGSEGV`.
627
+ comm (str): The task's name, as the task listing showed it while
628
+ the task was alive.
629
+ """
630
+
631
+ tid: int
632
+ tgid: int
633
+ exit_code: int
634
+ signal: int
635
+ status: int
636
+ outcome: str
637
+ comm: str = ""
638
+
639
+
640
+ @dataclass(frozen=True)
641
+ class OutputMatch(_Record):
642
+ """One match of a pattern in a run's output, as `Output.search`
643
+ yields it.
644
+
645
+ Attributes:
646
+ entry_id (int): The entry that printed the first byte of the match.
647
+ last_entry_id (int): The entry that printed its last byte, where
648
+ the match is complete.
649
+ line (int): The line the match is on, counted from 1.
650
+ offset (int): The offset of its first byte in the output, counted
651
+ from 0.
652
+ length (int): Its length in bytes.
653
+ text (str): The line it is on, the whole of it even where the line
654
+ goes on past the end of the search.
655
+ column (int): The character of `text` the match begins at.
656
+ column_end (int): The character of `text` it ends before.
657
+ in_range (int): How many characters of `text` were printed inside
658
+ the search's range: all of them but for a line its end cuts.
659
+ source (str): The source that printed it, such as `ttyS0`. The line
660
+ and the offset count within the sources that were searched.
661
+ place (Place): `entry_id` as a place, with its time:
662
+ `run.go(match.place)` stands where the match began to be
663
+ printed.
664
+ """
665
+
666
+ entry_id: int
667
+ last_entry_id: int
668
+ line: int
669
+ offset: int
670
+ length: int
671
+ text: str
672
+ column: int
673
+ column_end: int
674
+ in_range: int
675
+ source: str
676
+ place: Place
677
+
678
+
679
+ def output_match(found: Any) -> OutputMatch:
680
+ """The public form of one match the search reported."""
681
+ return OutputMatch(
682
+ entry_id=found.entry_id,
683
+ last_entry_id=found.last_entry_id,
684
+ line=found.line,
685
+ offset=found.offset,
686
+ length=found.length,
687
+ text=found.text,
688
+ column=found.column,
689
+ column_end=found.column_end,
690
+ in_range=found.in_range,
691
+ source=found.source.name,
692
+ place=Place(
693
+ found.recorder, found.entry_id, Point(found.vtime), found.vtime_offset
694
+ ),
695
+ )
696
+
697
+
698
+ @dataclass(frozen=True)
699
+ class OutputSource(_Record):
700
+ """One source that printed in a run, as `Output.sources` returns it.
701
+
702
+ Attributes:
703
+ name (str): The source, such as `ttyS1`: what `source=` takes.
704
+ bytes (int): How many bytes it printed.
705
+ lines (int): How many lines, counted in its own output, an
706
+ unfinished last line included.
707
+ entry_id (int): The entry that printed its first byte; 0 when
708
+ nothing is stored.
709
+ last_entry_id (int): The entry that printed its last byte; 0 when
710
+ nothing is stored.
711
+ stored (bool): Whether the run stored any byte of it. An output
712
+ file the run drops, or one that was not written, is listed
713
+ with nothing stored: its name is what `keep_output` takes.
714
+ """
715
+
716
+ name: str
717
+ bytes: int
718
+ lines: int
719
+ entry_id: int
720
+ last_entry_id: int
721
+ stored: bool
722
+
723
+
724
+ @dataclass(frozen=True)
725
+ class OutputWrite(_Record):
726
+ """Bytes one entry wrote to one source, as `Output.writes` returns it.
727
+
728
+ Attributes:
729
+ entry_id (int): The entry that wrote them.
730
+ source (str): The source they were written to, such as
731
+ `/output/keep/app/core.bin`.
732
+ offset (int): Where the bytes begin in what the source printed,
733
+ counted from 0. Each file of a directory is counted on its own.
734
+ data (bytes): The bytes, exactly as written.
735
+ tgid (int): The process that wrote them, as the guest numbers it;
736
+ 0 for bytes no task wrote, as a device's are.
737
+ tid (int): The thread that wrote them; 0 for no task.
738
+ task (str): The name the task had when it wrote, such as
739
+ `postgres`; empty for no task.
740
+ """
741
+
742
+ entry_id: int
743
+ source: str
744
+ offset: int
745
+ data: bytes
746
+ tgid: int
747
+ tid: int
748
+ task: str
749
+
750
+
751
+ def output_write(write: Any) -> OutputWrite:
752
+ """The public form of one write."""
753
+ return OutputWrite(
754
+ entry_id=write.entry_id,
755
+ source=write.source.name,
756
+ offset=write.offset,
757
+ data=write.data,
758
+ tgid=write.tgid,
759
+ tid=write.tid,
760
+ task=write.task,
761
+ )
762
+
763
+
764
+ def output_source(printed: Any) -> OutputSource:
765
+ """The public form of what one source printed."""
766
+ return OutputSource(
767
+ name=printed.source.name,
768
+ bytes=printed.size,
769
+ lines=printed.lines,
770
+ entry_id=printed.entry_id,
771
+ last_entry_id=printed.last_entry_id,
772
+ stored=printed.stored,
773
+ )
774
+
775
+
776
+ @dataclass(frozen=True)
777
+ class OutputLine(_Record):
778
+ """One line of a run's output, as `Output.lines` returns it.
779
+
780
+ Attributes:
781
+ text (str): The line, without its newline.
782
+ source (str): The source that printed it, such as `ttyS0`.
783
+ line (int): Its number, counted from 1 within the sources that were
784
+ read.
785
+ entry_id (int): The entry that printed its first byte. A point:
786
+ `run.go(f"#{line.entry_id}")` stands there.
787
+ last_entry_id (int): The entry that printed its last byte, where
788
+ the line is complete.
789
+ """
790
+
791
+ text: str
792
+ source: str
793
+ line: int
794
+ entry_id: int
795
+ last_entry_id: int
796
+
797
+
798
+ def output_lines(
799
+ lines: list[str],
800
+ ranges: list[tuple[int, int]],
801
+ sources: list[Any],
802
+ first_line: int,
803
+ ) -> list[OutputLine]:
804
+ """The public form of lines read with the entries and the source of
805
+ each, numbered from `first_line`."""
806
+ return [
807
+ OutputLine(
808
+ text=text.rstrip("\r"),
809
+ source=source.name,
810
+ line=first_line + index,
811
+ entry_id=first,
812
+ last_entry_id=last,
813
+ )
814
+ for index, (text, (first, last), source) in enumerate(
815
+ zip(lines, ranges, sources)
816
+ )
817
+ ]
818
+
819
+
820
+ @dataclass(frozen=True)
821
+ class Sent(_Record):
822
+ """What a send queued, as `Run.send` returns it.
823
+
824
+ Attributes:
825
+ queued (int): How many bytes were queued.
826
+ device (str): The device they are for, or the path of the file.
827
+ process (str or None): For a path, the id of the process that
828
+ writes the file: `Run.process` says whether the bytes were
829
+ written. None for a device.
830
+ """
831
+
832
+ queued: int
833
+ device: str
834
+ process: Optional[str]
835
+
836
+
837
+ @dataclass(frozen=True)
838
+ class ProfileStack(_Record):
839
+ """One stack a profile sampled.
840
+
841
+ Attributes:
842
+ frames (list[str]): The name of the program, then its frames, the
843
+ outermost first. A frame of the kernel ends in `_[k]`.
844
+ count (int): How many samples had this stack.
845
+ """
846
+
847
+ frames: list[str]
848
+ count: int
849
+
850
+
851
+ @dataclass(frozen=True)
852
+ class ProfileFunction(_Record):
853
+ """One function of a profile.
854
+
855
+ Attributes:
856
+ name (str): The function.
857
+ own (int): The samples the function itself was running in.
858
+ total (int): The samples it was anywhere on the stack of.
859
+ """
860
+
861
+ name: str
862
+ own: int
863
+ total: int
864
+
865
+
866
+ @dataclass(frozen=True)
867
+ class Profile(_Record):
868
+ """What `Run.profile` sampled.
869
+
870
+ Attributes:
871
+ samples (int): How many samples were taken. 0 for a run that was
872
+ idle.
873
+ hz (int): Samples a second on each CPU.
874
+ stacks (list[ProfileStack]): Every stack, the most sampled first.
875
+ functions (list[ProfileFunction]): Every function, the one most
876
+ run in first.
877
+ folded (list[str]): The stacks as text, `a;b;c <count>` a line:
878
+ what flame graph tools read.
879
+ left (bool): Whether the stretch had more samples than one profile
880
+ takes. The profile is then of the first of them.
881
+ """
882
+
883
+ samples: int
884
+ hz: int
885
+ stacks: list[ProfileStack]
886
+ functions: list[ProfileFunction]
887
+ folded: list[str]
888
+ left: bool
889
+
890
+
891
+ @dataclass(frozen=True)
892
+ class Container(_Record):
893
+ """One container of a run, as `Run.containers` lists it.
894
+
895
+ Attributes:
896
+ name (str): The name of the container.
897
+ service (str): The Compose service it is of, or an empty str for a
898
+ container no service started.
899
+ project (str): The Compose project of that service, or an empty
900
+ str.
901
+ state (str): `running`, `exited`, `created` or `paused`.
902
+ status (str): The state with how long, such as `Up 2 minutes`.
903
+ image (str): The image it runs.
904
+ id (str): The id of the container.
905
+ addresses (tuple[str, ...]): Its address on each network it is on;
906
+ empty for a container that does not run.
907
+ links (tuple[str, ...]): The interface of the machine at the other
908
+ end of each of its links, which a capture names with `-i`;
909
+ empty for a container that does not run, or one on the
910
+ machine's network, on none or on another container's.
911
+ cpus (float): The CPUs its cgroup allows, as `throttle` sets them;
912
+ 0 for no limit.
913
+ memory_mb (int): The megabytes of memory its cgroup allows, as
914
+ `memory` sets them; 0 for no limit.
915
+ memory_soft_mb (int): The megabytes past which its cgroup reclaims
916
+ and slows it, as `memory --soft` sets them; 0 for none.
917
+ pids (int): The processes and threads it may have, as `pids` sets
918
+ them; 0 for no limit.
919
+ ports (str): The ephemeral ports of its network, as `ports` sets
920
+ them, such as `40000-40009`; "" for the kernel's own range.
921
+ files (int): The files each process may hold open, as `files` sets
922
+ them; 0 for the container's own limit.
923
+ """
924
+
925
+ name: str
926
+ service: str
927
+ project: str
928
+ state: str
929
+ status: str
930
+ image: str
931
+ id: str
932
+ addresses: tuple[str, ...] = ()
933
+ links: tuple[str, ...] = ()
934
+ cpus: float = 0.0
935
+ memory_mb: int = 0
936
+ memory_soft_mb: int = 0
937
+ pids: int = 0
938
+ ports: str = ""
939
+ files: int = 0
940
+
941
+
942
+ @dataclass(frozen=True)
943
+ class ContainerFault(_Record):
944
+ """A fault put on a container, as the methods of `Run.containers`
945
+ return it.
946
+
947
+ Attributes:
948
+ verb (str): `stop`, `kill`, `crash`, `start`, `pause`, `resume`,
949
+ `throttle` or `memory`.
950
+ container (Container): The container as it was found, before the
951
+ fault.
952
+ after (int or None): Nanoseconds of the machine's time until what
953
+ ends the fault acts: a start, a thaw, a limit set back. 0 when
954
+ it acted at once, None when nothing ends it.
955
+ process (str or None): The id of the process that ends it later,
956
+ to read with `Run.process`; None when nothing waits.
957
+ volumes (tuple of str): The volumes a crash cut, by name; empty
958
+ for any other fault.
959
+ """
960
+
961
+ verb: str
962
+ container: Container
963
+ after: Optional[int]
964
+ process: Optional[str]
965
+ volumes: tuple[str, ...] = ()
966
+
967
+
968
+ def container(one: Any) -> Container:
969
+ """A container, from the engine's."""
970
+ return Container(
971
+ name=one.name,
972
+ service=one.service,
973
+ project=one.project,
974
+ state=one.state,
975
+ status=one.status,
976
+ image=one.image,
977
+ id=one.id,
978
+ addresses=one.addresses,
979
+ links=one.links,
980
+ cpus=one.cpus,
981
+ memory_mb=one.memory_mb,
982
+ memory_soft_mb=one.memory_soft_mb,
983
+ pids=one.pids,
984
+ ports=one.ports,
985
+ files=one.files,
986
+ )
987
+
988
+
989
+ def container_fault(acted: Any) -> ContainerFault:
990
+ """A fault put on a container, from the engine's."""
991
+ return ContainerFault(
992
+ verb=acted.verb,
993
+ container=container(acted.container),
994
+ after=acted.after_ns,
995
+ process=acted.later.id if acted.later else None,
996
+ volumes=tuple(acted.volumes),
997
+ )
998
+
999
+
1000
+ @dataclass(frozen=True)
1001
+ class Got(_Record):
1002
+ """A file read out of a run, as `Run.get` returns it.
1003
+
1004
+ Attributes:
1005
+ size (int): How many bytes the file has.
1006
+ mode (int): The mode of the file, such as 0o644.
1007
+ uid (int): The user that owns it, as a number.
1008
+ gid (int): The group that owns it, as a number.
1009
+ data (bytes or None): The bytes of the file, when no destination
1010
+ was given. None when they were written to one.
1011
+ process (Process): The process that read the file in the run.
1012
+ """
1013
+
1014
+ size: int
1015
+ mode: int
1016
+ uid: int
1017
+ gid: int
1018
+ data: Optional[bytes]
1019
+ process: "Process"
1020
+
1021
+
1022
+ def sent(queued: Any) -> Sent:
1023
+ """The public form of what a send queued."""
1024
+ return Sent(
1025
+ queued=queued.queued,
1026
+ device=queued.device,
1027
+ process=queued.process_id or None,
1028
+ )
1029
+
1030
+
1031
+ @dataclass(frozen=True)
1032
+ class ProcessEvent(_Record):
1033
+ """One event of a process: a line it printed, or a change of its state.
1034
+
1035
+ Attributes:
1036
+ stream (str): `stdout` or `stderr` for a line the command printed,
1037
+ `status` for a change of state.
1038
+ text (str): The line. A status line is `command <arguments>`,
1039
+ `started <pid>`, `exited <code>`, `killed <signal>` or
1040
+ `refused <reason>`.
1041
+ entry_id (int): The entry that recorded its first byte. A point:
1042
+ `run.go(f"#{event.entry_id}")` stands there.
1043
+ last_entry_id (int): The entry that recorded its last byte.
1044
+ """
1045
+
1046
+ stream: str
1047
+ text: str
1048
+ entry_id: int
1049
+ last_entry_id: int
1050
+
1051
+
1052
+ @dataclass(frozen=True)
1053
+ class Process(_Record):
1054
+ """A command executed in a run, as `Run.exec` returns it.
1055
+
1056
+ A process is read from what the run recorded, so it is a value: read it
1057
+ again with `Run.process` after the run has executed further.
1058
+
1059
+ Attributes:
1060
+ id (str): The id of the process, which `Run.process` takes.
1061
+ state (str): `pending` until the run has taken the command, then
1062
+ `running`, and `exited`, `killed` or `refused` once it ended.
1063
+ command (str): The command and its arguments.
1064
+ pid (int or None): Its process id in the machine; None until it
1065
+ started.
1066
+ exit_code (int or None): Its exit status; None unless it exited.
1067
+ signal (int or None): The signal that ended it; None unless one did.
1068
+ reason (str): Why the command was refused; empty unless it was.
1069
+ started_entry (int or None): The entry that recorded its start.
1070
+ ended_entry (int or None): The entry that recorded its end.
1071
+ stdout (list[str]): The lines it printed on its standard output.
1072
+ stderr (list[str]): The lines it printed on its standard error.
1073
+ events (list[ProcessEvent]): Every line it printed and every change
1074
+ of its state, in the order recorded.
1075
+ """
1076
+
1077
+ id: str
1078
+ state: str
1079
+ command: str
1080
+ pid: Optional[int]
1081
+ exit_code: Optional[int]
1082
+ signal: Optional[int]
1083
+ reason: str
1084
+ started_entry: Optional[int]
1085
+ ended_entry: Optional[int]
1086
+ stdout: list[str]
1087
+ stderr: list[str]
1088
+ events: list[ProcessEvent]
1089
+
1090
+ @property
1091
+ def exits(self) -> list[ProcessEvent]:
1092
+ """list[ProcessEvent]: The event that ended the process, in a list;
1093
+ empty until it ended."""
1094
+ if self.ended_entry is None:
1095
+ return []
1096
+ return [event for event in self.events if event.stream == "status"][-1:]
1097
+
1098
+ def exited_by(self, entry_id: int) -> bool:
1099
+ """Whether the process had ended at or before an entry.
1100
+
1101
+ Args:
1102
+ entry_id (int): The entry to ask about.
1103
+
1104
+ Returns:
1105
+ bool: True when the process ended at or before `entry_id`.
1106
+ """
1107
+ return self.ended_entry is not None and self.ended_entry <= entry_id
1108
+
1109
+
1110
+ def process(found: Any) -> Process:
1111
+ """The public form of a process the engine read."""
1112
+ events = [
1113
+ ProcessEvent(
1114
+ stream=event.stream,
1115
+ text=event.text,
1116
+ entry_id=event.entry_id,
1117
+ last_entry_id=event.last_entry_id,
1118
+ )
1119
+ for event in found.events
1120
+ ]
1121
+ return Process(
1122
+ id=found.id,
1123
+ state=found.state,
1124
+ command=found.command,
1125
+ pid=found.pid,
1126
+ exit_code=found.exit_code,
1127
+ signal=found.signal,
1128
+ reason=found.reason,
1129
+ started_entry=found.started_entry,
1130
+ ended_entry=found.ended_entry,
1131
+ stdout=[event.text for event in events if event.stream == "stdout"],
1132
+ stderr=[event.text for event in events if event.stream == "stderr"],
1133
+ events=events,
1134
+ )
1135
+
1136
+
1137
+ def exit_row(row: dict[str, Any]) -> Exit:
1138
+ """The public form of one exit the machine reported."""
1139
+ return Exit(
1140
+ tid=int(row["tid"]),
1141
+ tgid=int(row["tgid"]),
1142
+ exit_code=int(row["exit_code"]),
1143
+ signal=int(row["signal"]),
1144
+ status=int(row["status"]),
1145
+ outcome=str(row["outcome"]),
1146
+ comm=str(row["comm"]),
1147
+ )
1148
+
1149
+
1150
+ #: A directory entry's file type -> the word `File.kind` says it with.
1151
+ _KINDS: dict[int, str] = {
1152
+ _fs.FT_REG: "file",
1153
+ _fs.FT_DIR: "dir",
1154
+ _fs.FT_LNK: "link",
1155
+ }
1156
+
1157
+
1158
+ def file(entry: _ipc.FsEntry) -> File:
1159
+ """The public form of a directory entry."""
1160
+ return File(
1161
+ name=_fs.decode_name(entry.name),
1162
+ kind=_KINDS.get(entry.file_type, "other"),
1163
+ size=entry.size,
1164
+ mode=entry.mode,
1165
+ mtime=entry.mtime,
1166
+ )
1167
+
1168
+
1169
+ def replay_result(done: _control.ReplayResult) -> ReplayResult:
1170
+ """The public form of a replay's result."""
1171
+ return ReplayResult(
1172
+ converged=done.converged,
1173
+ entry_id=done.entry_id,
1174
+ replayed=done.replayed,
1175
+ diverged=tuple(dict(row) for row in done.diverged),
1176
+ misses=tuple(
1177
+ Miss(entry_id=m.entry_id, rip=m.rip, rcb=m.rcb, regs_hash=m.regs_hash)
1178
+ for m in done.misses
1179
+ ),
1180
+ retry_stopped=done.retry_stopped,
1181
+ overshoot=done.overshoot,
1182
+ )
1183
+
1184
+
1185
+ def run_result(done: _control.RunResult, *, reached: bool = True) -> RunResult:
1186
+ """The public form of a drive's result."""
1187
+ entries = tuple(
1188
+ Entry(vcpu=e.vcpu_id, entry_id=e.entry_id, exit=e.exit_reason_str, rip=e.rip)
1189
+ for e in done.entries
1190
+ )
1191
+ return RunResult(
1192
+ iterations=done.iterations_done,
1193
+ entry_id=max((e.entry_id for e in entries), default=0),
1194
+ entries=entries,
1195
+ reached=reached,
1196
+ vtime_elapsed=done.run_vtime,
1197
+ clauses=tuple(
1198
+ Clause(clause=c.clause, matched=c.matched) for c in done.plan_clauses
1199
+ ),
1200
+ hits=tuple(breakpoint(one) for one in done.hits),
1201
+ printed=tuple(done.printed),
1202
+ )
1203
+
1204
+
1205
+ def checkpoint(cp: _branches.CheckpointEntry, run_id: str) -> Checkpoint:
1206
+ """The public form of a listed checkpoint of `run_id`."""
1207
+ return Checkpoint(
1208
+ name=cp.name,
1209
+ place=Place(
1210
+ cp.ancestor_run_id or run_id, cp.entry_id, Point(cp.vtime), cp.vtime_offset
1211
+ ),
1212
+ date=cp.date,
1213
+ durable=cp.durable,
1214
+ )
1215
+
1216
+
1217
+ @dataclass(frozen=True)
1218
+ class VcpuHashes(_Record):
1219
+ """One vCPU's state hashes, as `Run.hash` reads them.
1220
+
1221
+ Attributes:
1222
+ vcpu (int): The vCPU.
1223
+ state (int): The hash of the whole machine, with this vCPU's state.
1224
+ regs_hash (int): Its general registers and flags: the hash a replay
1225
+ converges on.
1226
+ parts (dict[str, int]): Each part of its state by name: regs,
1227
+ events, xsave, debug, msrs, lapic, timers, pic and ioapic.
1228
+ """
1229
+
1230
+ vcpu: int
1231
+ state: int
1232
+ regs_hash: int
1233
+ parts: dict[str, int]
1234
+
1235
+
1236
+ @dataclass(frozen=True)
1237
+ class Hashes(_Record):
1238
+ """The state hashes of a machine as it stood, as `Run.hash` reads them.
1239
+
1240
+ Each hash compares with another machine's read at the same point,
1241
+ such as a recording's and its replay's. It does not compare with a
1242
+ recorded entry's: an entry hashes the machine before its exit is
1243
+ handled.
1244
+
1245
+ Attributes:
1246
+ entry_id (int): The newest entry when the hashes were read.
1247
+ mem (int): All of guest memory.
1248
+ disk (int): The disk.
1249
+ devices (dict[str, int]): Each device by name: serial, i8042, rtc,
1250
+ rng, blk, console, pci and vesa.
1251
+ irq_pending (int): The interrupts `irq_delay` holds, with when
1252
+ each is due. 0 when it holds none.
1253
+ vcpus (tuple[VcpuHashes, ...]): Each vCPU's.
1254
+ vcpu_now (bool): The vCPU hashes are of each vCPU now. False on a
1255
+ host whose kernel cannot compute them: they are of each vCPU's
1256
+ last exit.
1257
+ """
1258
+
1259
+ entry_id: int
1260
+ mem: int
1261
+ disk: int
1262
+ devices: dict[str, int]
1263
+ irq_pending: int
1264
+ vcpus: tuple[VcpuHashes, ...]
1265
+ vcpu_now: bool
1266
+
1267
+
1268
+ def hashes(h: _ipc.MachineHashes) -> Hashes:
1269
+ """The public form of a machine's state hashes."""
1270
+ return Hashes(
1271
+ entry_id=h.entry_id,
1272
+ mem=h.mem_hash,
1273
+ disk=h.disk_hash,
1274
+ devices=dict(zip(_hashes.DEVICES, h.devices)),
1275
+ irq_pending=h.irq_pending,
1276
+ vcpus=tuple(
1277
+ VcpuHashes(
1278
+ vcpu=v.vcpu,
1279
+ state=v.state_hash,
1280
+ regs_hash=v.regs_hash,
1281
+ parts=dict(zip(_hashes.KERNEL, v.kernel)),
1282
+ )
1283
+ for v in h.vcpus
1284
+ ),
1285
+ vcpu_now=h.vcpu_now,
1286
+ )
1287
+
1288
+
1289
+ def place(p: _branching.Place) -> Place:
1290
+ """The public form of an entry of a run's line."""
1291
+ return Place(p.run_id, p.entry_id, Point(p.vtime), p.vtime_offset)
1292
+
1293
+
1294
+ def place_of(p: "Place | Checkpoint") -> _branching.Place:
1295
+ """The engine's form of a place, or of the place a checkpoint is at."""
1296
+ at = p.place if isinstance(p, Checkpoint) else p
1297
+ return _branching.Place(at.run_id, at.entry_id, at.point.vtime, at.vtime_offset)
1298
+
1299
+
1300
+ def listing(row: _machines.RunRootRow | _machines.RunTreeRow) -> Listing:
1301
+ """The public form of a `runs` listing row."""
1302
+ if isinstance(row, _machines.RunRootRow):
1303
+ depth, running, runs = None, row.running_count, row.total_count
1304
+ else:
1305
+ depth, running, runs = row.depth, None, None
1306
+ return Listing(
1307
+ state=row.state,
1308
+ cpus=row.nrcpus,
1309
+ mem=row.ram_size // _BYTES_PER_MB,
1310
+ disk=row.disk,
1311
+ created_at=row.created_at,
1312
+ depth=depth,
1313
+ running=running,
1314
+ runs=runs,
1315
+ disk_bytes=row.disk_bytes,
1316
+ ram_bytes=row.ram_bytes,
1317
+ local=row.local,
1318
+ )
1319
+
1320
+
1321
+ def state(info: _machines.MachineState) -> State:
1322
+ """The public form of a machine's state."""
1323
+ return State(
1324
+ state=info.state,
1325
+ activity=info.activity,
1326
+ cpus=info.nrcpus,
1327
+ vcpu=info.current_vcpu,
1328
+ mem=info.ram_size // _BYTES_PER_MB,
1329
+ entry_id=info.entry_id,
1330
+ vtime=info.vtime,
1331
+ vtime_offset=info.vtime_offset,
1332
+ host_cpu=info.pinned_cpu,
1333
+ switch_prev_tid=info.switch_prev_tid,
1334
+ switch_next_tid=info.switch_next_tid,
1335
+ plan=tuple(info.plan),
1336
+ plan_tally=tuple(info.plan_tally),
1337
+ )
1338
+
1339
+
1340
+ def run_info(d: _ipc.DescribeInfo) -> RunInfo:
1341
+ """The public form of a run's description."""
1342
+ fs_sync, fs_dirsync = _machines.fs_flags_from_cmdline(d.kernel_cmdline)
1343
+ return RunInfo(
1344
+ id=d.run_id,
1345
+ name=d.name,
1346
+ state=d.state,
1347
+ cpus=d.nrcpus,
1348
+ mem=d.ram_size // _BYTES_PER_MB,
1349
+ mem_type=d.mem_type,
1350
+ mem_mode=d.mem_mode,
1351
+ disk_id=d.disk,
1352
+ fs_sync=fs_sync,
1353
+ fs_dirsync=fs_dirsync,
1354
+ rng=d.virtio_rng,
1355
+ rng_seed=d.rng_seed,
1356
+ limit=d.instruction_limit,
1357
+ vtime_base=d.vtime_base,
1358
+ vtime_rate=f"{d.vtime_rate_num}/{d.vtime_rate_den}",
1359
+ vtime_io_cost=d.vtime_io_cost,
1360
+ vtime_rdtsc_cost=d.vtime_rdtsc_cost,
1361
+ vtime_pause_cost=d.vtime_pause_cost,
1362
+ auto_checkpoints=d.auto_checkpoint_interval,
1363
+ side_dump=d.side_dump,
1364
+ side_trace=d.side_trace,
1365
+ mem_hash=d.mem_hash,
1366
+ disk_hash=d.disk_hash,
1367
+ parent_id=d.parent_run_id,
1368
+ parent_entry_id=d.parent_entry_id,
1369
+ labels=_machines.user_labels(d.labels),
1370
+ keep_output=list(d.output.keep),
1371
+ drop_output=list(d.output.drop),
1372
+ rdtsc_exit=d.rdtsc_exit,
1373
+ repeatable=d.repeatable,
1374
+ repeats_to=d.repeats_to if d.repeatable else None,
1375
+ host_breaks=d.host_breaks,
1376
+ limit_margin=d.limit_margin,
1377
+ timer_slack=d.timer_slack,
1378
+ instr_margin=d.instr_margin,
1379
+ dispatch_bound=d.dispatch_bound,
1380
+ fast_backstop=d.fast_backstop,
1381
+ irq_wait=d.irq_wait,
1382
+ guest_kernel=d.guest_kernel,
1383
+ machine_abi=d.machine_abi,
1384
+ machine_abi_max=d.machine_abi_max,
1385
+ )
1386
+
1387
+
1388
+ @dataclass(frozen=True)
1389
+ class TaskInfo(_Record):
1390
+ """One guest task, as `Tasks.__call__` lists it.
1391
+
1392
+ A task is what the guest kernel schedules: a thread of a program, or
1393
+ the kernel's own. Its tgid names its thread group, the process it
1394
+ belongs to, so a program of one task has one row with both equal.
1395
+
1396
+ Attributes:
1397
+ tid (int): The task's id.
1398
+ tgid (int): Its thread group's id.
1399
+ comm (str): The name the kernel knows it by.
1400
+ exe (str): The program it runs, as a path.
1401
+ cgroup (str): The cgroup it is in.
1402
+ start (int): When it started, in nanoseconds since the guest
1403
+ booted, by the guest's own clock. A tid is reused once its task
1404
+ exits; `tid` and `start` name one task.
1405
+ kernel (bool): Whether it is the kernel's own, which has no program
1406
+ and is never focused.
1407
+ focused (bool): Whether the focus covers it.
1408
+ held (bool): Whether a hold keeps it off the runqueue.
1409
+ yielded (bool): Whether a yield puts it behind its peers.
1410
+ pinned (bool): Whether it is pinned to a vCPU set.
1411
+ slice_ns (int): The slice it runs for, in nanoseconds; 0 for the
1412
+ kernel's own.
1413
+ on_cpu (bool): Whether it is on a vCPU right now.
1414
+ cpu (int, optional): Which vCPU, when it is on one.
1415
+ running (str, optional): `user` or `kernel`, when it is on one.
1416
+ """
1417
+
1418
+ tid: int
1419
+ tgid: int
1420
+ comm: str
1421
+ exe: str
1422
+ cgroup: str
1423
+ start: int
1424
+ kernel: bool
1425
+ focused: bool
1426
+ held: bool
1427
+ yielded: bool
1428
+ pinned: bool
1429
+ slice_ns: int
1430
+ on_cpu: bool
1431
+ cpu: Optional[int]
1432
+ running: Optional[str]
1433
+
1434
+
1435
+ @dataclass(frozen=True)
1436
+ class Cgroup(_Record):
1437
+ """One cgroup of the guest's tasks, as `Tasks.cgroups` lists it.
1438
+
1439
+ Attributes:
1440
+ path (str): The cgroup's path.
1441
+ tids (tuple[int, ...]): The threads in it.
1442
+ comms (tuple[str, ...]): Their names, sorted.
1443
+ """
1444
+
1445
+ path: str
1446
+ tids: tuple[int, ...]
1447
+ comms: tuple[str, ...]
1448
+
1449
+
1450
+ @dataclass(frozen=True)
1451
+ class Op(_Record):
1452
+ """One operation of the session on a run, as `ops` lists it.
1453
+
1454
+ An operation is a checkpoint, a branch or a switch: work the session
1455
+ carried out on a run, with how it ended.
1456
+
1457
+ Attributes:
1458
+ op_id (int): The operation's id, unique in the session.
1459
+ type (str): `checkpoint`, `branch`, `switch` and so on.
1460
+ state (str): `running`, `unfinished`, `done` or `failed`.
1461
+ run_id (str): The run it acted on.
1462
+ target (str): What it produced, in its own words: the branch a fork
1463
+ created, the checkpoint a checkpoint named, the run a switch
1464
+ moved away from.
1465
+ entry_id (int): The entry it anchored at; 0 before that is known.
1466
+ started_at (int): When it started, in Unix seconds.
1467
+ error (str): Why it failed; empty when it did not.
1468
+ """
1469
+
1470
+ op_id: int
1471
+ type: str
1472
+ state: str
1473
+ run_id: str
1474
+ target: str
1475
+ entry_id: int
1476
+ started_at: int
1477
+ error: str
1478
+
1479
+
1480
+ @dataclass(frozen=True)
1481
+ class StorageOp(_Record):
1482
+ """One operation on the account's storage, as `Storage.ops` lists it.
1483
+
1484
+ A storage operation is a measurement, a prune, the check of one disk or
1485
+ the check of every stored object. It acts on the account, so it names no
1486
+ run.
1487
+
1488
+ Attributes:
1489
+ op_id (int): The operation's id.
1490
+ type (str): `measure`, `prune`, `verify` or `check`.
1491
+ state (str): `pending`, `running`, `done` or `failed`.
1492
+ started_at (int): When it started, in Unix seconds.
1493
+ error (str): Why it failed; empty when it did not.
1494
+ progress (str): How far a running check has got, as
1495
+ `checked/objects`; empty for anything else.
1496
+ """
1497
+
1498
+ op_id: int
1499
+ type: str
1500
+ state: str
1501
+ started_at: int
1502
+ error: str
1503
+ progress: str = ""
1504
+
1505
+
1506
+ @dataclass(frozen=True)
1507
+ class FocusInfo(_Record):
1508
+ """The tasks a run steers, as `Focus.__call__` reads them.
1509
+
1510
+ Attributes:
1511
+ entries (tuple[str, ...]): What is focused: a program's `/path`, a
1512
+ `cgroup=P`, a `comm=NAME`, or a process `tgid=N`.
1513
+ counting (tuple[tuple[str, ...], ...]): What each entry counts, in the
1514
+ order of `entries`: "+syscalls", "+ints", both or neither.
1515
+ tgids (tuple[int, ...]): The processes the entries matched.
1516
+ held (tuple[int, ...]): The threads a hold keeps off the runqueue.
1517
+ yielded (tuple[int, ...]): The threads a yield puts behind.
1518
+ sliced (tuple[dict[str, int], ...]): The threads with a slice, each
1519
+ `{tid, units}`.
1520
+ pinned (tuple[int, ...]): The threads with a vCPU set to run on.
1521
+ marks (dict[str, int]): How many threads each mark is on, `held`,
1522
+ `yield` and `sliced`, counted by the machine. It includes threads
1523
+ that have exited, which the lists above no longer name.
1524
+ switches (int): Guest scheduling decisions seen while focused.
1525
+ io_blocks (int): Times a focused task blocked on I/O.
1526
+ generation (int): Rises whenever the focus changes, so two reads
1527
+ that agree can be told from two scans that happened to.
1528
+ truncated (bool): Whether more tasks matched than the machine can
1529
+ carry.
1530
+ """
1531
+
1532
+ entries: tuple[str, ...]
1533
+ counting: tuple[tuple[str, ...], ...]
1534
+ tgids: tuple[int, ...]
1535
+ held: tuple[int, ...]
1536
+ yielded: tuple[int, ...]
1537
+ sliced: tuple[dict[str, int], ...]
1538
+ pinned: tuple[int, ...]
1539
+ marks: dict[str, int]
1540
+ switches: int
1541
+ io_blocks: int
1542
+ generation: int
1543
+ truncated: bool
1544
+
1545
+
1546
+ @dataclass(frozen=True)
1547
+ class VtimeInfo(_Record):
1548
+ """The guest's virtual clock, as `Vtime.__call__` read it.
1549
+
1550
+ Attributes:
1551
+ vtime (int): The clock now, in nanoseconds since `base`.
1552
+ base (int): Where the clock started, in Unix seconds.
1553
+ rate_num (int): The rate's numerator.
1554
+ rate_den (int): The rate's denominator, so the rate is num/den of
1555
+ real time.
1556
+ io_cost (int): Nanoseconds an I/O, MMIO or hypercall exit adds to
1557
+ the clock.
1558
+ rdtsc_cost (int): Nanoseconds an RDTSC adds: the I/O cost while it
1559
+ follows it.
1560
+ pause_cost (int): Nanoseconds each PAUSE of a spin loop adds.
1561
+ rdtsc_follows_io (bool): Whether the RDTSC cost is the I/O cost.
1562
+ vcpu_rates (dict[int, tuple[int, int]]): Each vCPU that has its own
1563
+ rate, to that rate as (num, den); empty when all run at the
1564
+ machine's.
1565
+ """
1566
+
1567
+ vtime: int
1568
+ base: int
1569
+ rate_num: int
1570
+ rate_den: int
1571
+ io_cost: int = 0
1572
+ rdtsc_cost: int = 0
1573
+ pause_cost: int = 0
1574
+ rdtsc_follows_io: bool = True
1575
+ vcpu_rates: dict[int, tuple[int, int]] = field(default_factory=dict)
1576
+
1577
+
1578
+ @dataclass(frozen=True)
1579
+ class RngInfo(_Record):
1580
+ """The machine's RNG device, as `Rng.__call__` read it.
1581
+
1582
+ Attributes:
1583
+ seed (int): The seed the device's generator is from: the run's
1584
+ `rng_seed`, or the last seed given since.
1585
+ guest_reseeds (bool): Whether the guest kernel reseeds its own
1586
+ generator from a seed at once. A guest kernel that does not
1587
+ takes it at its own next reseed.
1588
+ """
1589
+
1590
+ seed: int
1591
+ guest_reseeds: bool
1592
+
1593
+
1594
+ @dataclass(frozen=True)
1595
+ class Vcpu(_Record):
1596
+ """Where a vCPU stopped, as `Run.vcpu` read it.
1597
+
1598
+ `Run.state` answers what the machine is doing; this answers where one
1599
+ vCPU is and what the last drive did.
1600
+
1601
+ Attributes:
1602
+ vcpu (int): The vCPU this describes.
1603
+ entry_id (int): The entry it recorded last.
1604
+ exit (str): Why it stopped, such as `INSTR_LIMIT` or `IO`.
1605
+ rip (int): The instruction address there.
1606
+ rcx (int): RCX there, which a REP loop counts down.
1607
+ cs_base (int): The code segment's base there.
1608
+ ic (int): Instructions in that dispatch.
1609
+ rcb (int): Retired conditional branches in it.
1610
+ total_ic (int): Instructions since the run began.
1611
+ regs_hash (int): The register hash replay compares.
1612
+ vtime (int): The virtual time there, in nanoseconds.
1613
+ vtime_offset (int): Orders the entries that share one `vtime`.
1614
+ iteration (int): The dispatch number within the last drive.
1615
+ iterations_done (int): Iterations the last drive ran.
1616
+ iterations_total (int): Iterations it was asked for.
1617
+ running (bool): Whether a drive is in flight now.
1618
+ ready (bool): Whether the machine accepts commands.
1619
+ checkpointing (bool): Whether a checkpoint is being written.
1620
+ until_satisfied (bool): Whether the last drive's predicate held.
1621
+ halted (bool): Whether the guest has shut itself down.
1622
+ synced (bool): Whether the tip is checkpointed, so it can be
1623
+ restored rather than replayed to.
1624
+ """
1625
+
1626
+ vcpu: int
1627
+ entry_id: int
1628
+ exit: str
1629
+ rip: int
1630
+ rcx: int
1631
+ cs_base: int
1632
+ ic: int
1633
+ rcb: int
1634
+ total_ic: int
1635
+ regs_hash: int
1636
+ vtime: int
1637
+ vtime_offset: int
1638
+ iteration: int
1639
+ iterations_done: int
1640
+ iterations_total: int
1641
+ running: bool
1642
+ ready: bool
1643
+ checkpointing: bool
1644
+ until_satisfied: bool
1645
+ halted: bool
1646
+ synced: bool
1647
+
1648
+
1649
+ @dataclass(frozen=True)
1650
+ class Syscall(_Record):
1651
+ """One system call the guest kernel has, as `Run.syscalls` lists them.
1652
+
1653
+ Attributes:
1654
+ number (int): Its number in the guest's table.
1655
+ name (str): Its name, such as `openat`.
1656
+ """
1657
+
1658
+ number: int
1659
+ name: str
1660
+
1661
+
1662
+ @dataclass(frozen=True)
1663
+ class Vector(_Record):
1664
+ """One interrupt vector the guest kernel has, as `Run.ints` lists them.
1665
+
1666
+ Attributes:
1667
+ number (int): The vector, 32-255.
1668
+ name (str): What arrives on it, such as `preempt`.
1669
+ """
1670
+
1671
+ number: int
1672
+ name: str
1673
+
1674
+
1675
+ @dataclass(frozen=True)
1676
+ class PendingInterrupt(_Record):
1677
+ """One interrupt raised and not yet delivered, as `Irq.pending` lists them.
1678
+
1679
+ Attributes:
1680
+ type (str): `PIN`, `MSI`, `TIMER_LAPIC`, `INIT`, `SIPI` or `IPI`.
1681
+ source (str): What raised it, as an `irq_delay` target names it:
1682
+ `timer`, `ipi`, `init`, `blk`, `rng`, `console`, `serial` or
1683
+ `keyboard`.
1684
+ vcpu (int): The vCPU it goes to.
1685
+ gsi (int): A pin's line, else 0.
1686
+ level (int): A pin's level, else 0.
1687
+ vector (int): An MSI's, an IPI's or a SIPI's vector, else 0.
1688
+ held (bool): Held by `irq_delay` until `due`. Otherwise it is
1689
+ delivered at the next dispatch.
1690
+ due (int): The machine time it is delivered at, in nanoseconds;
1691
+ 0 when it is not held.
1692
+ """
1693
+
1694
+ type: str
1695
+ source: str
1696
+ vcpu: int
1697
+ gsi: int
1698
+ level: int
1699
+ vector: int
1700
+ held: bool
1701
+ due: int
1702
+
1703
+
1704
+ @dataclass(frozen=True)
1705
+ class ClockJitter(_Record):
1706
+ """A jitter of the guest's date or a container's, as `Clock.jitter` set it.
1707
+
1708
+ Attributes:
1709
+ choices (str): The choices, as `Clock.jitter` takes them.
1710
+ every (int): The machine time between two steps, in nanoseconds.
1711
+ seed (int): The seed the steps are drawn from.
1712
+ draws (int): The steps drawn so far.
1713
+ now (int): The draw in force, in nanoseconds from the date without it.
1714
+ """
1715
+
1716
+ choices: str
1717
+ every: int
1718
+ seed: int
1719
+ draws: int
1720
+ now: int
1721
+
1722
+
1723
+ @dataclass(frozen=True)
1724
+ class ClockContainer(_Record):
1725
+ """A container whose date is off the guest's, as `ClockInfo` lists it.
1726
+
1727
+ Attributes:
1728
+ id (str): The container's id, as `docker ps` prints it.
1729
+ name (str): The container's name; its id until the name is known.
1730
+ date (int): The container's date now, in nanoseconds since the epoch.
1731
+ date_text (str): The same, as `Clock.set` takes it.
1732
+ offset (int): How far its date is from the guest's, in nanoseconds.
1733
+ running (bool): Whether the container runs; a stopped one takes
1734
+ its offset again when it starts.
1735
+ pending (bool): Whether a `for_` undo is still to come.
1736
+ pending_vtime (int): The machine time it comes at; 0 for none.
1737
+ pending_offset (int): The offset it restores; 0 is the guest's date.
1738
+ jitter (ClockJitter, optional): Its jitter; None for none.
1739
+ drift (int): Its drift, in parts per billion of machine time.
1740
+ slew (int): The rate a slew adds until it arrives, in parts per
1741
+ billion; 0 for none.
1742
+ slew_to (int): The offset the slew arrives at, in nanoseconds.
1743
+ slew_vtime (int): The machine time it arrives at; 0 for none.
1744
+ """
1745
+
1746
+ id: str
1747
+ name: str
1748
+ date: int
1749
+ date_text: str
1750
+ offset: int
1751
+ running: bool
1752
+ pending: bool
1753
+ pending_vtime: int
1754
+ pending_offset: int
1755
+ jitter: Optional[ClockJitter]
1756
+ drift: int
1757
+ slew: int
1758
+ slew_to: int
1759
+ slew_vtime: int
1760
+
1761
+
1762
+ @dataclass(frozen=True)
1763
+ class Link(_Record):
1764
+ """A container's link, as `Net.__call__` lists it: the faults on the
1765
+ packets the container sends to every peer, or on those a match takes.
1766
+
1767
+ Attributes:
1768
+ container (str): The container that sends.
1769
+ service (str): Its Compose service; "" for none.
1770
+ peer (str): The container the packets go to; "" for any.
1771
+ proto (str): The protocol of the packets, `tcp`, `udp` or `icmp`,
1772
+ or `arp` for ARP frames; "" for any.
1773
+ port (int): Their source or destination port; 0 for any.
1774
+ syn (bool): Whether the match takes the TCP SYNs that open a
1775
+ connection alone.
1776
+ delay (int): Nanoseconds each packet waits.
1777
+ jitter (int): Nanoseconds each packet's delay differs by, at most.
1778
+ loss (int): The share of the packets lost, in parts per billion.
1779
+ duplicate (int): The share sent twice, in parts per billion.
1780
+ corrupt (int): The share with a bit changed, in parts per billion.
1781
+ reorder (int): The share sent ahead of delayed ones, in parts per
1782
+ billion.
1783
+ rate (int): Bits a second the link sends at most; 0 for no limit.
1784
+ held (bool): Whether the link holds its packets until a release.
1785
+ log (bool): Whether each decision of the fault goes to the
1786
+ container's file under `/output/drop/.machine/net`.
1787
+ seed (int): The seed the link draws from; 0 for a link with no
1788
+ fault that draws.
1789
+ unapplied (str): On a container's whole link, why its faults did
1790
+ not take when it last started; "" when they did.
1791
+ sent (int): The packets the fault sent on since it began, each
1792
+ duplicate counted once more.
1793
+ dropped (int): The packets it dropped since it began.
1794
+ queued (int): The packets it holds now, delayed or held: neither
1795
+ sent nor dropped yet.
1796
+ """
1797
+
1798
+ container: str
1799
+ service: str
1800
+ peer: str
1801
+ proto: str
1802
+ port: int
1803
+ syn: bool
1804
+ delay: int
1805
+ jitter: int
1806
+ loss: int
1807
+ duplicate: int
1808
+ corrupt: int
1809
+ reorder: int
1810
+ rate: int
1811
+ held: bool
1812
+ log: bool
1813
+ seed: int
1814
+ unapplied: str
1815
+ sent: int
1816
+ dropped: int
1817
+ queued: int
1818
+
1819
+
1820
+ def link(found: Any) -> Link:
1821
+ """The public form of a link."""
1822
+ return Link(
1823
+ container=found.container,
1824
+ service=found.service,
1825
+ peer=found.peer,
1826
+ proto=found.proto,
1827
+ port=found.port,
1828
+ syn=found.syn,
1829
+ delay=found.delay_ns,
1830
+ jitter=found.jitter_ns,
1831
+ loss=found.loss_ppb,
1832
+ duplicate=found.duplicate_ppb,
1833
+ corrupt=found.corrupt_ppb,
1834
+ reorder=found.reorder_ppb,
1835
+ rate=found.rate_bps,
1836
+ held=found.held,
1837
+ log=found.log,
1838
+ seed=found.seed,
1839
+ unapplied=found.unapplied,
1840
+ sent=found.sent,
1841
+ dropped=found.dropped,
1842
+ queued=found.queued,
1843
+ )
1844
+
1845
+
1846
+ @dataclass(frozen=True)
1847
+ class Neighbor(_Record):
1848
+ """An entry of a container's neighbour table, as `NetArp.show` lists it.
1849
+
1850
+ Attributes:
1851
+ container (str): The container whose table it is.
1852
+ interface (str): The interface the entry is on, such as `eth0`.
1853
+ address (str): The peer's address.
1854
+ mac (str): The MAC the address maps to; `-` for none yet.
1855
+ state (str): `reachable`, `stale`, `delay`, `probe`, `failed`,
1856
+ `incomplete`, `permanent`, `noarp`, or `none` for an entry the
1857
+ kernel keeps no state of.
1858
+ peer (str): The container the address belongs to; "" for none.
1859
+ """
1860
+
1861
+ container: str
1862
+ interface: str
1863
+ address: str
1864
+ mac: str
1865
+ state: str
1866
+ peer: str
1867
+
1868
+
1869
+ def neighbor(found: Any) -> Neighbor:
1870
+ """The public form of a neighbour table entry."""
1871
+ return Neighbor(
1872
+ container=found.container,
1873
+ interface=found.interface,
1874
+ address=found.address,
1875
+ mac=found.mac,
1876
+ state=found.state,
1877
+ peer=found.peer,
1878
+ )
1879
+
1880
+
1881
+ @dataclass(frozen=True)
1882
+ class LinkChange(_Record):
1883
+ """What a change of a link did, as `Net`'s methods return it.
1884
+
1885
+ Attributes:
1886
+ before (Link): The link as it was.
1887
+ after (Link): The link as it is.
1888
+ process (str, optional): The process that sets the link back after
1889
+ `for_`, which `Run.process` reads; None when it stays.
1890
+ for_ (int, optional): Nanoseconds of machine time until then.
1891
+ """
1892
+
1893
+ before: Link
1894
+ after: Link
1895
+ process: Optional[str] = None
1896
+ for_: Optional[int] = None
1897
+
1898
+
1899
+ def link_change(changed: Any) -> LinkChange:
1900
+ """The public form of a change of a link."""
1901
+ return LinkChange(
1902
+ before=link(changed.before),
1903
+ after=link(changed.after),
1904
+ process=changed.later.id if changed.later else None,
1905
+ for_=changed.for_ns,
1906
+ )
1907
+
1908
+
1909
+ @dataclass(frozen=True)
1910
+ class ClockRefused(_Record):
1911
+ """A clock change the guest kernel refused, as `Clock.__call__` names
1912
+ it. A change waits until the run next executes, so a refusal is read
1913
+ after the run that takes it.
1914
+
1915
+ Attributes:
1916
+ command (str): The change, as `machine clock` takes it, such as
1917
+ `clock set 1970-01-01T00:00:01Z`.
1918
+ error (str): The errno, such as `ERANGE`.
1919
+ reason (str): Why the guest kernel refused it.
1920
+ """
1921
+
1922
+ command: str
1923
+ error: str
1924
+ reason: str
1925
+
1926
+
1927
+ @dataclass(frozen=True)
1928
+ class ClockInfo(_Record):
1929
+ """The guest's date, as `Clock.__call__` reads it.
1930
+
1931
+ Attributes:
1932
+ date (int): The guest's date now, in nanoseconds since the epoch.
1933
+ date_text (str): The same, as `Clock.set` takes it, such as
1934
+ `2027-03-28T00:59:50Z`.
1935
+ offset (int): How far the date is from machine time, in nanoseconds.
1936
+ pending (bool): Whether a `for_` undo is still to come.
1937
+ pending_vtime (int): The machine time it comes at; 0 for none.
1938
+ pending_offset (int): The offset it restores.
1939
+ waiting (int): Changes requested that the guest takes when the run
1940
+ next executes.
1941
+ error (str): The errno of the last `for_` undo the guest kernel
1942
+ could not make, such as `ERANGE`; "" for none.
1943
+ refused (tuple[ClockRefused, ...]): The changes of the guest's last
1944
+ pass that it refused, oldest first.
1945
+ containers (tuple[ClockContainer, ...]): Each container whose date
1946
+ is off the guest's, or the one container asked for.
1947
+ jitter (ClockJitter, optional): The guest's jitter; None for none.
1948
+ leap (str, optional): The leap second pending, `insert` or
1949
+ `delete`; None for none.
1950
+ leap_at (int): The UTC midnight it falls at, in nanoseconds since
1951
+ the epoch; 0 for none.
1952
+ """
1953
+
1954
+ date: int
1955
+ date_text: str
1956
+ offset: int
1957
+ pending: bool
1958
+ pending_vtime: int
1959
+ pending_offset: int
1960
+ waiting: int
1961
+ error: str
1962
+ containers: tuple[ClockContainer, ...]
1963
+ jitter: Optional[ClockJitter]
1964
+ leap: Optional[str]
1965
+ leap_at: int
1966
+ refused: tuple[ClockRefused, ...] = ()
1967
+
1968
+
1969
+ @dataclass(frozen=True)
1970
+ class AxisDefault(_Record):
1971
+ """One default of the draw axes, as `Axis.__call__` lists them.
1972
+
1973
+ Attributes:
1974
+ number (int): Its place in the order drives draw them, from 1.
1975
+ clause (str): The clause, as a plan file writes it, such as
1976
+ `when /app:on task-sched hold`.
1977
+ axes (tuple[str, ...]): The axes it names, such as `task-sched`.
1978
+ conditional (bool): Whether it applies only where its `when` holds.
1979
+ """
1980
+
1981
+ number: int
1982
+ clause: str
1983
+ axes: tuple[str, ...]
1984
+ conditional: bool
1985
+
1986
+
1987
+ @dataclass(frozen=True)
1988
+ class Fault(_Record):
1989
+ """One syscall fault of a machine, as `Faults.__call__` lists them.
1990
+
1991
+ Attributes:
1992
+ number (int): Its number in the list, from 1, which
1993
+ `Faults.delete` takes.
1994
+ site (str): The kernel site it fails, such as `disk`; "" for a
1995
+ syscall fault.
1996
+ syscall (str): The system call, as the guest kernel names it; ""
1997
+ for a site fault.
1998
+ nr (int): The system call's number, or the site's.
1999
+ errors (tuple[str, ...]): The errors its calls return, such as
2000
+ `ENOENT`, one drawn for each call it fires on; empty for a
2001
+ fault that only delays.
2002
+ errs (tuple[int, ...]): The errors' numbers.
2003
+ tid (int): The task whose calls it acts on; 0 for any.
2004
+ tgid (int): The tgid whose tasks' calls it acts on; 0 for any.
2005
+ path (str): The program whose tasks' calls it acts on; "" for any.
2006
+ comm (str): The comm whose tasks' calls it acts on; "" for any.
2007
+ after (int): How many matching calls go through first.
2008
+ times (int): How many calls it fires on at most; 0 for no end.
2009
+ prob (float): The chance a matching call fires it.
2010
+ seed (int): The seed of its draws.
2011
+ delay_ns (tuple[int, int]): The span a call is held for before
2012
+ its error, low and high nanoseconds; (0, 0) for none.
2013
+ matched (int): The calls it matched.
2014
+ fired (int): The calls it fired on: held, failed, or both.
2015
+ op (str): A disk fault's operation, `read` or `write`; "" for both.
2016
+ sectors (tuple[int, int] | None): A disk fault's sectors, the first
2017
+ and the last; None for the whole disk.
2018
+ file (str): A disk fault's file pattern; "" for any file.
2019
+ bytes (int): How many bytes of a request a `disk-corrupt` fault
2020
+ changes; 0 for another fault.
2021
+ on_ms (int): How long a cycling fault is active in each cycle, in
2022
+ milliseconds of machine time; 0 for a fault that does not cycle.
2023
+ off_ms (int): How long it then rests.
2024
+ active (bool): Whether a cycling fault is in an active window now;
2025
+ True for a fault that does not cycle.
2026
+ left_ns (int): The machine time left in that window, in
2027
+ nanoseconds; 0 for a fault that does not cycle.
2028
+ function (str): A function fault's function; "" for another.
2029
+ returns (int or None): The value a function fault returns in place
2030
+ of running; None for another fault.
2031
+ """
2032
+
2033
+ number: int
2034
+ site: str
2035
+ syscall: str
2036
+ nr: int
2037
+ errors: tuple[str, ...]
2038
+ errs: tuple[int, ...]
2039
+ tid: int
2040
+ tgid: int
2041
+ path: str
2042
+ comm: str
2043
+ after: int
2044
+ times: int
2045
+ prob: float
2046
+ seed: int
2047
+ delay_ns: tuple[int, int]
2048
+ matched: int
2049
+ fired: int
2050
+ op: str
2051
+ sectors: Optional[tuple[int, int]]
2052
+ file: str
2053
+ bytes: int
2054
+ on_ms: int = 0
2055
+ off_ms: int = 0
2056
+ active: bool = True
2057
+ left_ns: int = 0
2058
+ function: str = ""
2059
+ returns: Optional[int] = None
2060
+
2061
+
2062
+ @dataclass(frozen=True)
2063
+ class PendingInterrupts(_Record):
2064
+ """Every interrupt a machine has raised and not yet delivered, as
2065
+ `Irq.pending` read them: the ones due at the next dispatch first, then
2066
+ the held ones in the order they were held.
2067
+
2068
+ Attributes:
2069
+ vtime (int): The machine time when they were read, in nanoseconds.
2070
+ interrupts (tuple[PendingInterrupt, ...]): Each one.
2071
+ """
2072
+
2073
+ vtime: int
2074
+ interrupts: tuple[PendingInterrupt, ...]
2075
+
2076
+
2077
+ @dataclass(frozen=True)
2078
+ class Count(_Record):
2079
+ """How often one system call or vector was taken, as the counts list it.
2080
+
2081
+ Attributes:
2082
+ number (int): The system call's number, or the vector.
2083
+ name (str): Its name.
2084
+ count (int): How many times it was taken.
2085
+ """
2086
+
2087
+ number: int
2088
+ name: str
2089
+ count: int
2090
+
2091
+
2092
+ @dataclass(frozen=True)
2093
+ class Counts(_Record):
2094
+ """What a task crossed, as `Syscalls.counts` and `Ints.counts` read it.
2095
+
2096
+ Counting is opt-in: focus the program with `syscalls=True` or
2097
+ `ints=True` before the drive, or both lists are empty.
2098
+
2099
+ Attributes:
2100
+ by_tgid (tuple[Count, ...]): The counts over every task of the
2101
+ tgid, most taken first.
2102
+ by_tid (tuple[Count, ...]): The counts of the one task, when a
2103
+ `tid` named it; empty otherwise.
2104
+ """
2105
+
2106
+ by_tgid: tuple[Count, ...]
2107
+ by_tid: tuple[Count, ...]
2108
+
2109
+
2110
+ @dataclass(frozen=True)
2111
+ class Injected(_Record):
2112
+ """An interrupt the machine queued, as `Run.irq` injected it.
2113
+
2114
+ Attributes:
2115
+ vector (int): The vector delivered.
2116
+ vcpu (int, optional): The vCPU it went to; None for every vCPU.
2117
+ nmi (bool): Whether it was delivered as a non-maskable interrupt.
2118
+ """
2119
+
2120
+ vector: int
2121
+ vcpu: Optional[int]
2122
+ nmi: bool
2123
+
2124
+
2125
+ @dataclass(frozen=True)
2126
+ class LogEntry(_Record):
2127
+ """One entry of a run's log, as `Run.entries` reads them.
2128
+
2129
+ An entry is one stop of a vCPU. The fields here are valid for every
2130
+ kind; what else an entry carries depends on its `event`, and `text` is
2131
+ the machine's own rendering of that detail.
2132
+
2133
+ Attributes:
2134
+ entry_id (int): The entry's id, rising through the run.
2135
+ event (int): The event's number.
2136
+ event_name (str): Its name, such as `RUN`, `IRQ` or `EXIT_SHUTDOWN`.
2137
+ vcpu (int): The vCPU that stopped.
2138
+ flags (int): The entry's flag bits.
2139
+ flag_names (tuple[str, ...]): Those bits by name.
2140
+ ic (int): Instructions in the dispatch.
2141
+ rcb (int): Retired conditional branches in it.
2142
+ total_ic (int): Instructions since the run began.
2143
+ vtime (int): The virtual time there, in nanoseconds.
2144
+ vtime_offset (int): Orders the entries that share one `vtime`.
2145
+ rip (int): The instruction address in force there.
2146
+ regs_hash (int): The register hash replay compares.
2147
+ iter (int): The dispatch number within its drive.
2148
+ data_len (int): Bytes of event detail behind `text`.
2149
+ text (str): The entry as the machine renders it.
2150
+ """
2151
+
2152
+ entry_id: int
2153
+ event: int
2154
+ event_name: str
2155
+ vcpu: int
2156
+ flags: int
2157
+ flag_names: tuple[str, ...]
2158
+ ic: int
2159
+ rcb: int
2160
+ total_ic: int
2161
+ vtime: int
2162
+ vtime_offset: int
2163
+ rip: int
2164
+ regs_hash: int
2165
+ iter: int
2166
+ data_len: int
2167
+ text: str
2168
+
2169
+
2170
+ @dataclass(frozen=True)
2171
+ class Cleanup(_Record):
2172
+ """What `Client.cleanup` found and cleared.
2173
+
2174
+ Attributes:
2175
+ cleaned (int): Runs whose stale state was cleared.
2176
+ orphans (int): Machines that were running with no run to own them.
2177
+ run_ids (tuple[str, ...]): The runs cleaned.
2178
+ """
2179
+
2180
+ cleaned: int
2181
+ orphans: int
2182
+ run_ids: tuple[str, ...]
2183
+
2184
+
2185
+ @dataclass(frozen=True)
2186
+ class Copy(_Record):
2187
+ """One run or disk a session holds, as `Offload.list` lists it.
2188
+
2189
+ Attributes:
2190
+ id (str): The run id, or the disk id.
2191
+ name (str): Its name; empty for a disk kept by id alone.
2192
+ disk_bytes (int): What it takes on the session's storage.
2193
+ state (str): `offloadable` when nothing needs it there, else why it
2194
+ is kept.
2195
+ """
2196
+
2197
+ id: str
2198
+ name: str
2199
+ disk_bytes: int
2200
+ state: str
2201
+
2202
+
2203
+ @dataclass(frozen=True)
2204
+ class Copies(_Record):
2205
+ """What a session holds, as `Offload.list` read it.
2206
+
2207
+ Attributes:
2208
+ runs (tuple[Copy, ...]): The run folders.
2209
+ disks (tuple[Copy, ...]): The disk files.
2210
+ """
2211
+
2212
+ runs: tuple[Copy, ...]
2213
+ disks: tuple[Copy, ...]
2214
+
2215
+
2216
+ @dataclass(frozen=True)
2217
+ class Rewound(_Record):
2218
+ """Where a run stands after `Run.rewind`, and what it discarded.
2219
+
2220
+ Attributes:
2221
+ entry_id (int): The entry the run is back at, and its tip now.
2222
+ entries_dropped (int): Entries the discarded tail held.
2223
+ """
2224
+
2225
+ entry_id: int
2226
+ entries_dropped: int
2227
+
2228
+
2229
+ @dataclass(frozen=True)
2230
+ class Prune(_Record):
2231
+ """A prune of the account's storage, as `Storage.prune` reports it.
2232
+
2233
+ Attributes:
2234
+ op_id (int): The operation carrying it out.
2235
+ state (str): `requested`, `running`, `done` or `failed`.
2236
+ freed_bytes (int): What it freed, once it is done.
2237
+ started_at (str, optional): When it started, ISO 8601.
2238
+ error (str): Why it failed; empty when it did not.
2239
+ """
2240
+
2241
+ op_id: int
2242
+ state: str
2243
+ freed_bytes: int
2244
+ started_at: Optional[str]
2245
+ error: str
2246
+
2247
+
2248
+ @dataclass(frozen=True)
2249
+ class StorageCheck(_Record):
2250
+ """A check of every object in the account's storage, as `Storage.check`
2251
+ reports it.
2252
+
2253
+ Each stored object is read back and compared with its name, which is the
2254
+ SHA-256 of what it holds. The counts are filled in as the check goes.
2255
+
2256
+ Attributes:
2257
+ op_id (int): The operation carrying it out.
2258
+ state (str): `requested`, `running`, `done` or `failed`.
2259
+ objects (int): The objects the storage listed.
2260
+ checked (int): Of those, the ones read so far.
2261
+ gone (int): The ones deleted while the check ran, which were not read.
2262
+ failed (int): The ones that could not be read, or read as something
2263
+ else.
2264
+ bytes (int): The bytes read.
2265
+ unreadable (list[str]): Each failed object: its key, what was wrong,
2266
+ and the storage's id for the failed request.
2267
+ started_at (str, optional): When it started, ISO 8601.
2268
+ finished_at (str, optional): When it ended, ISO 8601; None while it
2269
+ runs.
2270
+ error (str): Why it failed; empty when it did not.
2271
+ """
2272
+
2273
+ op_id: int
2274
+ state: str
2275
+ objects: int
2276
+ checked: int
2277
+ gone: int
2278
+ failed: int
2279
+ bytes: int
2280
+ unreadable: list[str]
2281
+ started_at: Optional[str]
2282
+ finished_at: Optional[str]
2283
+ error: str
2284
+
2285
+
2286
+ @dataclass(frozen=True)
2287
+ class StorageInfo(_Record):
2288
+ """What the account stores, as `Storage.show` read it.
2289
+
2290
+ The sizes are what the last measurement found; `state` says whether one
2291
+ is under way.
2292
+
2293
+ Every size is in BYTES. `disks_bytes` is what the account's disks add
2294
+ up to; the rest is what the last measurement found in the store behind
2295
+ them, where a run and a disk share whatever content they have in common.
2296
+
2297
+ Attributes:
2298
+ state (str): `ready` once measured, `measuring` while it is, `stale`
2299
+ when the sizes are old and no measurement is running.
2300
+ quota_bytes (int): What the plan allows.
2301
+ disks_bytes (int): What the account's disks add up to.
2302
+ bytes (int): What the store holds in all.
2303
+ pack_bytes (int): Of that, what the packs hold.
2304
+ referenced_bytes (int): What a run or a disk still refers to.
2305
+ prunable_bytes (int): What a prune would free: the packs less what is
2306
+ referenced.
2307
+ run_bytes (int): What the runs refer to.
2308
+ disk_bytes (int): What the disks refer to.
2309
+ measured_at (str, optional): When it was measured, ISO 8601; None
2310
+ before the first measurement.
2311
+ op_id (int): The measurement's operation id.
2312
+ prune (Prune, optional): The prune under way, or the last one; None
2313
+ when there has been none.
2314
+ failed_at (str, optional): When the newest measurement failed, ISO
2315
+ 8601; None when the newest one did not fail. The sizes are then
2316
+ the last ones measured.
2317
+ failed_error (str): Why it failed; empty when it did not.
2318
+ """
2319
+
2320
+ state: str
2321
+ quota_bytes: int
2322
+ disks_bytes: int
2323
+ bytes: int
2324
+ pack_bytes: int
2325
+ referenced_bytes: int
2326
+ prunable_bytes: int
2327
+ run_bytes: int
2328
+ disk_bytes: int
2329
+ measured_at: Optional[str]
2330
+ op_id: int
2331
+ prune: Optional[Prune]
2332
+ failed_at: Optional[str] = None
2333
+ failed_error: str = ""
2334
+
2335
+
2336
+ @dataclass(frozen=True)
2337
+ class Transfer(_Record):
2338
+ """One disk transfer, as `Disks.transfers` lists it.
2339
+
2340
+ Attributes:
2341
+ transfer_id (str): The transfer's id.
2342
+ op (str): `upload`.
2343
+ name (str): The disk's name.
2344
+ sha256 (str): The disk's content hash.
2345
+ state (str): `reserving`, `transferring`, `committed`, `aborted` or
2346
+ `reclaiming`.
2347
+ size_bytes (int): The disk's size.
2348
+ bytes_done (int): Bytes transferred so far.
2349
+ rate_bps (int): The last measured rate, in bytes a second.
2350
+ created_at (str): When it started, ISO 8601.
2351
+ progress_at (str, optional): When it last advanced, ISO 8601.
2352
+ stopped_at (str, optional): When it ended, ISO 8601; None while it
2353
+ runs.
2354
+ error (str): Why it aborted; empty when it did not.
2355
+ """
2356
+
2357
+ transfer_id: str
2358
+ op: str
2359
+ name: str
2360
+ sha256: str
2361
+ state: str
2362
+ size_bytes: int
2363
+ bytes_done: int
2364
+ rate_bps: int
2365
+ created_at: str
2366
+ progress_at: Optional[str]
2367
+ stopped_at: Optional[str]
2368
+ error: str
2369
+
2370
+
2371
+ def task(row: dict[str, Any]) -> TaskInfo:
2372
+ """The public form of one task the machine reported."""
2373
+ cpu = row.get("cpu")
2374
+ running = row.get("next")
2375
+ return TaskInfo(
2376
+ tid=int(row["tid"]),
2377
+ tgid=int(row["tgid"]),
2378
+ comm=str(row["comm"]),
2379
+ exe=str(row.get("exe") or ""),
2380
+ cgroup=str(row.get("cgroup") or ""),
2381
+ start=int(row.get("start") or 0),
2382
+ kernel=bool(row.get("kernel")),
2383
+ focused=bool(row.get("focus")),
2384
+ held=bool(row.get("held")),
2385
+ yielded=bool(row.get("yield")),
2386
+ pinned=bool(row.get("pinned")),
2387
+ slice_ns=int(row.get("slice_ns") or 0),
2388
+ on_cpu=bool(row.get("on_cpu")),
2389
+ cpu=None if cpu is None else int(cpu),
2390
+ running=None if running is None else str(running),
2391
+ )
2392
+
2393
+
2394
+ def cgroup(row: dict[str, Any]) -> Cgroup:
2395
+ """The public form of one cgroup grouping."""
2396
+ return Cgroup(
2397
+ path=str(row["cgroup"]),
2398
+ tids=tuple(int(t) for t in row.get("tids") or ()),
2399
+ comms=tuple(str(c) for c in row.get("comms") or ()),
2400
+ )
2401
+
2402
+
2403
+ @dataclass(frozen=True)
2404
+ class Registers(_Record):
2405
+ """The user registers of a guest task, as `Task.registers` reads
2406
+ them, and where they were read.
2407
+
2408
+ Index it by a register's name for its value: `regs["rip"]`. The names
2409
+ are GDB's: rax to r15, rip, eflags, the segments and their bases,
2410
+ orig_rax, st0 to st7 and the x87 control registers, mxcsr, xmm0 to
2411
+ xmm15, and ymm0 to ymm15 on a guest with AVX. A value is unsigned.
2412
+
2413
+ Example:
2414
+ >>> regs = run.task(412).registers()
2415
+ >>> hex(regs["rip"]), regs.where
2416
+ ('0x401ac6', 'user')
2417
+
2418
+ Attributes:
2419
+ tid (int): The task.
2420
+ tgid (int): Its tgid.
2421
+ start (int): When it started, in nanoseconds since the guest
2422
+ booted, by the guest's own clock.
2423
+ where (str): `user` for a task on a vCPU in its own code,
2424
+ `kernel` for one on a vCPU in the kernel, whose user registers
2425
+ are the ones it entered with, and `saved` for a task off
2426
+ every vCPU, whose registers are the ones it saved.
2427
+ cpu (int, optional): The vCPU it is on, None when it is on none.
2428
+ values (dict[str, int]): Every register by its name.
2429
+ """
2430
+
2431
+ tid: int
2432
+ tgid: int
2433
+ start: int
2434
+ where: str
2435
+ cpu: Optional[int]
2436
+ values: dict[str, int]
2437
+
2438
+ def __getitem__(self, name: str) -> int:
2439
+ return self.values[name]
2440
+
2441
+
2442
+ def registers(found: _debugger.Registers) -> Registers:
2443
+ """The public form of a task's registers."""
2444
+ return Registers(
2445
+ tid=found.tid,
2446
+ tgid=found.tgid,
2447
+ start=found.start,
2448
+ where=found.where.name.lower(),
2449
+ cpu=None if found.where == _ipc.TaskWhere.SAVED else found.cpu,
2450
+ values={one.name: one.value for one in found.registers},
2451
+ )
2452
+
2453
+
2454
+ @dataclass(frozen=True)
2455
+ class Symbol(_Record):
2456
+ """A function or a variable of a tgid, at an address of it.
2457
+
2458
+ Attributes:
2459
+ address (int): The address asked about, or where the symbol begins.
2460
+ name (str): The symbol's name.
2461
+ offset (int): How far into the symbol `address` is.
2462
+ size (int): The symbol's size in bytes, 0 when its file says none.
2463
+ function (bool): A function, not a variable.
2464
+ path (str): The file that names it.
2465
+ source (str, optional): The source file `address` is in, None when
2466
+ the program was built without debug information.
2467
+ line (int, optional): The line of `source`.
2468
+ """
2469
+
2470
+ address: int
2471
+ name: str
2472
+ offset: int
2473
+ size: int
2474
+ function: bool
2475
+ path: str
2476
+ source: Optional[str]
2477
+ line: Optional[int]
2478
+
2479
+
2480
+ def symbol(found: _debugger.Symbol) -> Symbol:
2481
+ """The public form of a symbol."""
2482
+ return Symbol(
2483
+ address=found.addr,
2484
+ name=found.name,
2485
+ offset=found.offset,
2486
+ size=found.size,
2487
+ function=found.function,
2488
+ path=found.path,
2489
+ source=found.source,
2490
+ line=found.line,
2491
+ )
2492
+
2493
+
2494
+ @dataclass(frozen=True)
2495
+ class Frame(_Record):
2496
+ """One frame of a task's stack, as `Task.backtrace` lists them.
2497
+
2498
+ Attributes:
2499
+ level (int): 0 for the innermost frame, 1 for its caller, and on.
2500
+ address (int): The address the frame executes at.
2501
+ stack (int): Its stack pointer.
2502
+ function (str, optional): The function it is in, None where no file
2503
+ the tgid maps names it.
2504
+ offset (int, optional): How far into the function.
2505
+ path (str, optional): The file the function is in.
2506
+ source (str, optional): The source file the frame executes in, None
2507
+ when the program was built without debug information.
2508
+ line (int, optional): The line of `source`.
2509
+ """
2510
+
2511
+ level: int
2512
+ address: int
2513
+ stack: int
2514
+ function: Optional[str]
2515
+ offset: Optional[int]
2516
+ path: Optional[str]
2517
+ source: Optional[str]
2518
+ line: Optional[int]
2519
+
2520
+
2521
+ @dataclass(frozen=True)
2522
+ class Value(_Record):
2523
+ """The value of an expression in a frame of a task, as `Task.print`
2524
+ returns it.
2525
+
2526
+ Attributes:
2527
+ expression (str): The expression, as it was given.
2528
+ type (str): Its type, as C writes it.
2529
+ value (str): The value, printed by the type: a struct by its members,
2530
+ an array by its elements, a pointer in hex.
2531
+ address (int, optional): Where it is, None for a value in a register
2532
+ or one an `&` or a cast made.
2533
+ """
2534
+
2535
+ expression: str
2536
+ type: str
2537
+ value: str
2538
+ address: Optional[int] = None
2539
+
2540
+
2541
+ def value(found: _variables.Value) -> Value:
2542
+ """The public form of a value."""
2543
+ return Value(
2544
+ expression=found.expression,
2545
+ type=found.type.spelled,
2546
+ value=found.text,
2547
+ address=found.address,
2548
+ )
2549
+
2550
+
2551
+ @dataclass(frozen=True)
2552
+ class Variable(_Record):
2553
+ """A local variable or an argument of a frame, as `Task.locals` lists
2554
+ them.
2555
+
2556
+ Attributes:
2557
+ name (str): Its name.
2558
+ type (str): Its type, as C writes it.
2559
+ value (str): Its value, printed by the type, or why it is not read
2560
+ in angle brackets.
2561
+ """
2562
+
2563
+ name: str
2564
+ type: str
2565
+ value: str
2566
+
2567
+
2568
+ def frame(found: _debugger.Frame) -> Frame:
2569
+ """The public form of a stack frame."""
2570
+ return Frame(
2571
+ level=found.level,
2572
+ address=found.ip,
2573
+ stack=found.sp,
2574
+ function=found.function,
2575
+ offset=found.offset,
2576
+ path=found.path,
2577
+ source=found.source,
2578
+ line=found.line,
2579
+ )
2580
+
2581
+
2582
+ @dataclass(frozen=True)
2583
+ class Library(_Record):
2584
+ """The program or a library of a tgid, as `Task.libraries` lists
2585
+ them.
2586
+
2587
+ Attributes:
2588
+ start (int): The first address the file is mapped at.
2589
+ end (int): The address after its last.
2590
+ offset (int): Where in the file the mapping begins.
2591
+ path (str): The file's path.
2592
+ on_disk (bool): The machine's disk has the file, so its symbols
2593
+ are read.
2594
+ """
2595
+
2596
+ start: int
2597
+ end: int
2598
+ offset: int
2599
+ path: str
2600
+ on_disk: bool
2601
+
2602
+
2603
+ @dataclass(frozen=True)
2604
+ class Breakpoint(_Record):
2605
+ """A breakpoint or a watchpoint of a run, as `Run.breakpoints` lists
2606
+ them.
2607
+
2608
+ Attributes:
2609
+ number (int): Its number. A number names one stop for the life of
2610
+ the run.
2611
+ kind (str): `breakpoint`, `watch write` or `watch access`.
2612
+ address (int): The address it stops at, or the first byte it
2613
+ watches.
2614
+ size (int): The bytes it watches; 1 for a breakpoint.
2615
+ tgid (int): The tgid it stops.
2616
+ program (str): The tgid's program.
2617
+ location (str): The location as it was given.
2618
+ symbol (str, optional): The symbol at the address.
2619
+ source (str, optional): The source line at the address, as
2620
+ `FILE:LINE`.
2621
+ enabled (bool): The machine arms it.
2622
+ temporary (bool): Its first hit that counts deletes it.
2623
+ hits (int): The hits that counted.
2624
+ ignore (int): The hits it passes before one ends a run.
2625
+ condition (str): Where a hit counts; empty for everywhere.
2626
+ print (str): What a hit prints in place of ending a run; empty
2627
+ for a stop that ends it.
2628
+ tid (int): A catchpoint's task; 0 for any task of its tgid.
2629
+ comm (str): A catchpoint's comm, the tasks of that name; empty for
2630
+ any.
2631
+ names (tuple[str, ...]): What a catchpoint names: its system
2632
+ calls or signals, or its path.
2633
+ event (str): The event a catchpoint stopped a run at, as the run
2634
+ says it; empty in a listing.
2635
+ hit_tid (int): In a hit of a breakpoint or a watchpoint, the tid
2636
+ it hit in; 0 in a listing.
2637
+ error (str): In a hit, why its condition was not tested or its
2638
+ print not made, which ended the run there; empty when
2639
+ nothing failed.
2640
+ old (int, optional): In a hit of a watchpoint, the value it
2641
+ watched before the write; None where it kept none.
2642
+ new (int, optional): In a hit of a watchpoint, the value now.
2643
+ disable_after (int): The hits that count left before it is
2644
+ disabled, as `Breakpoints.enable(count=N)` sets them; 0 for none.
2645
+ unplaced (str): Why a breakpoint of a tgid is not in the program,
2646
+ such as "not placed: the address maps no file"; empty once it
2647
+ is, and before the run has run since it was added.
2648
+ """
2649
+
2650
+ number: int
2651
+ kind: str
2652
+ address: int
2653
+ size: int
2654
+ tgid: int
2655
+ program: str
2656
+ location: str
2657
+ symbol: Optional[str]
2658
+ source: Optional[str]
2659
+ enabled: bool = True
2660
+ temporary: bool = False
2661
+ hits: int = 0
2662
+ ignore: int = 0
2663
+ condition: str = ""
2664
+ print: str = ""
2665
+ tid: int = 0
2666
+ names: tuple[str, ...] = ()
2667
+ event: str = ""
2668
+ hit_tid: int = 0
2669
+ error: str = ""
2670
+ old: Optional[int] = None
2671
+ new: Optional[int] = None
2672
+ disable_after: int = 0
2673
+ comm: str = ""
2674
+ unplaced: str = ""
2675
+
2676
+
2677
+ @dataclass(frozen=True)
2678
+ class Stepped(_Record):
2679
+ """Where a step left a task, as `Task.step` and `Task.finish`
2680
+ return it.
2681
+
2682
+ Attributes:
2683
+ tid (int): The task.
2684
+ steps (int): The steps it made. Fewer than asked when a breakpoint
2685
+ ended the step.
2686
+ address (int): The instruction it is at.
2687
+ symbol (str, optional): The symbol of the address.
2688
+ source (str, optional): The source line of the address, as
2689
+ `FILE:LINE`.
2690
+ hits (tuple[Breakpoint, ...]): The breakpoints and watchpoints that
2691
+ ended the step. Empty when it made all its steps.
2692
+ printed (tuple[str, ...]): The lines the stops that print printed
2693
+ while it ran.
2694
+ returned (int, optional): After `Task.finish`, rax, the register
2695
+ a function returns an integer or a pointer in; None after a
2696
+ step.
2697
+ line (int, optional): The number of the source line it is at.
2698
+ text (str, optional): The text of that line, from the source file
2699
+ where it is on this machine; None where it is not.
2700
+ caught (bool): An exception left the frame the step waited to
2701
+ return to, and the task is at the catch that took it. A
2702
+ finish then returns no value.
2703
+ """
2704
+
2705
+ tid: int
2706
+ steps: int
2707
+ address: int
2708
+ symbol: Optional[str]
2709
+ source: Optional[str]
2710
+ hits: tuple["Breakpoint", ...] = ()
2711
+ printed: tuple[str, ...] = ()
2712
+ returned: Optional[int] = None
2713
+ line: Optional[int] = None
2714
+ text: Optional[str] = None
2715
+ caught: bool = False
2716
+
2717
+
2718
+ @dataclass(frozen=True)
2719
+ class Called(_Record):
2720
+ """What a call of a function in a task returned, as `Task.call`
2721
+ returns it.
2722
+
2723
+ Attributes:
2724
+ tid (int): The task.
2725
+ function (str): The function called.
2726
+ returned (str, optional): The value it returned, as GDB prints it
2727
+ by the function's return type. None for a void function, and
2728
+ for a call a breakpoint abandoned.
2729
+ hits (tuple[Breakpoint, ...]): The breakpoints and watchpoints that
2730
+ abandoned the call. Empty when it returned.
2731
+ """
2732
+
2733
+ tid: int
2734
+ function: str
2735
+ returned: Optional[str]
2736
+ hits: tuple["Breakpoint", ...]
2737
+
2738
+
2739
+ def called(found: _stepping.Called) -> Called:
2740
+ """The public form of a call."""
2741
+ return Called(
2742
+ tid=found.tid,
2743
+ function=found.function,
2744
+ returned=found.returned,
2745
+ hits=tuple(breakpoint(one) for one in found.hits),
2746
+ )
2747
+
2748
+
2749
+ def stepped(found: _stepping.Stepped) -> Stepped:
2750
+ """The public form of a step."""
2751
+ return Stepped(
2752
+ tid=found.tid,
2753
+ steps=found.steps,
2754
+ address=found.rip,
2755
+ symbol=found.symbol,
2756
+ source=found.source,
2757
+ hits=tuple(breakpoint(one) for one in found.hits),
2758
+ printed=tuple(found.printed),
2759
+ returned=found.returned,
2760
+ line=found.line_number,
2761
+ text=found.line_text,
2762
+ caught=found.caught,
2763
+ )
2764
+
2765
+
2766
+ @dataclass(frozen=True)
2767
+ class Hit(_Record):
2768
+ """A hit the run log keeps, as `Breakpoints.hits` lists them.
2769
+
2770
+ Attributes:
2771
+ entry_id (int): The entry the run it ended ended at.
2772
+ vtime (int): Its machine time, in nanoseconds.
2773
+ number (int): The stop that hit.
2774
+ kind (str): What it is: `breakpoint`, `watch write`, `catch fork`.
2775
+ event (str): The event a catchpoint among them stopped at; empty
2776
+ for none.
2777
+ """
2778
+
2779
+ entry_id: int
2780
+ vtime: int
2781
+ number: int
2782
+ kind: str
2783
+ event: str
2784
+
2785
+
2786
+ def hit(found: _breakpoints.RecordedHit) -> Hit:
2787
+ """The public form of a hit the run log keeps."""
2788
+ return Hit(
2789
+ entry_id=found.entry_id,
2790
+ vtime=found.vtime,
2791
+ number=found.number,
2792
+ kind=found.kind,
2793
+ event=found.event,
2794
+ )
2795
+
2796
+
2797
+ def breakpoint(found: _breakpoints.Breakpoint) -> Breakpoint:
2798
+ """The public form of a breakpoint or a watchpoint."""
2799
+ return Breakpoint(
2800
+ number=found.number,
2801
+ kind=found.kind,
2802
+ address=found.address,
2803
+ size=found.size,
2804
+ tgid=found.tgid,
2805
+ program=found.program,
2806
+ location=found.location,
2807
+ symbol=found.symbol,
2808
+ source=found.source,
2809
+ enabled=found.enabled,
2810
+ temporary=found.temporary,
2811
+ hits=found.hits,
2812
+ ignore=found.ignore,
2813
+ condition=found.condition,
2814
+ print=found.print,
2815
+ tid=found.tid,
2816
+ comm=found.comm,
2817
+ names=found.names,
2818
+ event=found.event,
2819
+ hit_tid=found.hit_tid,
2820
+ error=found.error,
2821
+ old=found.old,
2822
+ new=found.new,
2823
+ disable_after=found.disable_after,
2824
+ unplaced=found.unplaced,
2825
+ )
2826
+
2827
+
2828
+ def library(found: _debugger.Library) -> Library:
2829
+ """The public form of the program or a library of a tgid."""
2830
+ return Library(
2831
+ start=found.start,
2832
+ end=found.end,
2833
+ offset=found.offset,
2834
+ path=found.path,
2835
+ on_disk=found.on_disk,
2836
+ )
2837
+
2838
+
2839
+ def op(row: dict[str, Any]) -> Op:
2840
+ """The public form of one of the session's operations."""
2841
+ return Op(
2842
+ op_id=int(row["op_id"]),
2843
+ type=str(row["op_type"]),
2844
+ state=str(row["state"]),
2845
+ run_id=str(row.get("run_id") or ""),
2846
+ target=str(row.get("name") or ""),
2847
+ entry_id=int(row["entry"]) if row.get("entry") else 0,
2848
+ started_at=int(row.get("started_at") or 0),
2849
+ error=str(row.get("error") or ""),
2850
+ )
2851
+
2852
+
2853
+ def storage_op(row: dict[str, Any]) -> StorageOp:
2854
+ """The public form of one storage operation."""
2855
+ return StorageOp(
2856
+ op_id=int(row["op_id"]),
2857
+ type=str(row["op_type"]),
2858
+ state=str(row["state"]),
2859
+ started_at=int(row.get("started_at") or 0),
2860
+ error=str(row.get("error") or ""),
2861
+ progress=str(row.get("progress") or ""),
2862
+ )
2863
+
2864
+
2865
+ def focus(doc: dict[str, Any]) -> FocusInfo:
2866
+ """The public form of a run's focus."""
2867
+ return FocusInfo(
2868
+ entries=tuple(str(e) for e in doc.get("entries") or ()),
2869
+ counting=tuple(tuple(str(w) for w in c) for c in doc.get("counting") or ()),
2870
+ tgids=tuple(int(t) for t in doc.get("tgids") or ()),
2871
+ held=tuple(int(t) for t in doc.get("held") or ()),
2872
+ yielded=tuple(int(t) for t in doc.get("yield") or ()),
2873
+ sliced=tuple(dict(s) for s in doc.get("sliced") or ()),
2874
+ pinned=tuple(int(p) for p in doc.get("pinned") or ()),
2875
+ marks={str(k): int(v) for k, v in (doc.get("marks") or {}).items()},
2876
+ switches=int(doc.get("switches") or 0),
2877
+ io_blocks=int(doc.get("io_blocks") or 0),
2878
+ generation=int(doc.get("generation") or 0),
2879
+ truncated=bool(doc.get("truncated")),
2880
+ )
2881
+
2882
+
2883
+ def pending_interrupts(doc: dict[str, Any]) -> PendingInterrupts:
2884
+ """The public form of a machine's pending interrupts."""
2885
+ return PendingInterrupts(
2886
+ vtime=int(doc.get("vtime") or 0),
2887
+ interrupts=tuple(
2888
+ PendingInterrupt(
2889
+ type=str(i["type"]),
2890
+ source=str(i["source"]),
2891
+ vcpu=int(i["vcpu"]),
2892
+ gsi=int(i["gsi"]),
2893
+ level=int(i["level"]),
2894
+ vector=int(i["vector"]),
2895
+ held=bool(i["held"]),
2896
+ due=int(i["due"]),
2897
+ )
2898
+ for i in doc.get("pending") or ()
2899
+ ),
2900
+ )
2901
+
2902
+
2903
+ def clock(doc: dict[str, Any]) -> ClockInfo:
2904
+ """The public form of the guest's date."""
2905
+ return ClockInfo(
2906
+ date=int(doc["date"]),
2907
+ date_text=str(doc["date_text"]),
2908
+ offset=int(doc["offset"]),
2909
+ pending=bool(doc["pending"]),
2910
+ pending_vtime=int(doc["pending_vtime"]),
2911
+ pending_offset=int(doc["pending_offset"]),
2912
+ waiting=int(doc["requested"]) - int(doc["applied"]),
2913
+ error=str(doc["error"]),
2914
+ containers=tuple(
2915
+ ClockContainer(
2916
+ id=str(one["id"]),
2917
+ name=str(one["name"]),
2918
+ date=int(one["date"]),
2919
+ date_text=str(one["date_text"]),
2920
+ offset=int(one["offset"]),
2921
+ running=bool(one["running"]),
2922
+ pending=bool(one["pending"]),
2923
+ pending_vtime=int(one["pending_vtime"]),
2924
+ pending_offset=int(one["pending_offset"]),
2925
+ jitter=_clock_jitter(one["jitter"]),
2926
+ drift=int(one["drift"]),
2927
+ slew=int(one["slew"]),
2928
+ slew_to=int(one["slew_to"]),
2929
+ slew_vtime=int(one["slew_vtime"]),
2930
+ )
2931
+ for one in doc["containers"]
2932
+ ),
2933
+ jitter=_clock_jitter(doc["jitter"]),
2934
+ leap=doc["leap"],
2935
+ leap_at=int(doc["leap_at"]),
2936
+ refused=tuple(ClockRefused(**one) for one in doc["refused"]),
2937
+ )
2938
+
2939
+
2940
+ def _clock_jitter(doc: Optional[dict[str, Any]]) -> Optional[ClockJitter]:
2941
+ if doc is None:
2942
+ return None
2943
+ return ClockJitter(
2944
+ choices=str(doc["choices"]),
2945
+ every=int(doc["every"]),
2946
+ seed=int(doc["seed"]),
2947
+ draws=int(doc["draws"]),
2948
+ now=int(doc["now"]),
2949
+ )
2950
+
2951
+
2952
+ def axis_defaults(rows: list[dict[str, Any]]) -> tuple[AxisDefault, ...]:
2953
+ """The public form of a run's defaults of the draw axes."""
2954
+ return tuple(
2955
+ AxisDefault(
2956
+ number=int(r["number"]),
2957
+ clause=str(r["clause"]),
2958
+ axes=tuple(str(a) for a in r["axes"]),
2959
+ conditional=bool(r["conditional"]),
2960
+ )
2961
+ for r in rows
2962
+ )
2963
+
2964
+
2965
+ def faults(rows: list[dict[str, Any]]) -> tuple[Fault, ...]:
2966
+ """The public form of a machine's syscall faults."""
2967
+ return tuple(
2968
+ Fault(
2969
+ number=int(r["number"]),
2970
+ site=str(r["site"]),
2971
+ syscall=str(r["syscall"]),
2972
+ nr=int(r["nr"]),
2973
+ errors=tuple(str(e) for e in r["errors"]),
2974
+ errs=tuple(int(e) for e in r["errs"]),
2975
+ tid=int(r["tid"]),
2976
+ tgid=int(r["tgid"]),
2977
+ path=str(r["path"]),
2978
+ comm=str(r["comm"]),
2979
+ after=int(r["after"]),
2980
+ times=int(r["times"]),
2981
+ prob=float(r["prob"]),
2982
+ seed=int(r["seed"]),
2983
+ delay_ns=(int(r["delay_ns"][0]), int(r["delay_ns"][1])),
2984
+ matched=int(r["matched"]),
2985
+ fired=int(r["fired"]),
2986
+ op=str(r["op"]),
2987
+ sectors=(
2988
+ (int(r["sectors"][0]), int(r["sectors"][1]))
2989
+ if r["sectors"] is not None
2990
+ else None
2991
+ ),
2992
+ file=str(r["file"]),
2993
+ bytes=int(r["bytes"]),
2994
+ on_ms=int(r["on_ms"]),
2995
+ off_ms=int(r["off_ms"]),
2996
+ active=bool(r["active"]),
2997
+ left_ns=int(r["left_ns"]),
2998
+ function=str(r["function"]),
2999
+ returns=None if r["return"] is None else int(r["return"]),
3000
+ )
3001
+ for r in rows
3002
+ )
3003
+
3004
+
3005
+ def rng(doc: dict[str, Any]) -> RngInfo:
3006
+ """The public form of the RNG device's seed."""
3007
+ return RngInfo(
3008
+ seed=int(doc.get("seed") or 0), guest_reseeds=bool(doc.get("guest_reseeds"))
3009
+ )
3010
+
3011
+
3012
+ def vtime(doc: dict[str, Any]) -> VtimeInfo:
3013
+ """The public form of the guest's clock."""
3014
+ return VtimeInfo(
3015
+ vtime=int(doc.get("vtime") or 0),
3016
+ base=int(doc.get("vtime_base") or 0),
3017
+ rate_num=int(doc.get("rate_num") or 0),
3018
+ rate_den=int(doc.get("rate_den") or 0),
3019
+ io_cost=int(doc.get("io_cost") or 0),
3020
+ rdtsc_cost=int(doc.get("rdtsc_cost") or 0),
3021
+ pause_cost=int(doc.get("pause_cost") or 0),
3022
+ rdtsc_follows_io=bool(doc.get("rdtsc_follows_io", True)),
3023
+ vcpu_rates={
3024
+ int(r["vcpu"]): (int(r["num"]), int(r["den"]))
3025
+ for r in doc.get("vcpu_rates") or []
3026
+ },
3027
+ )
3028
+
3029
+
3030
+ def vcpu(doc: dict[str, Any]) -> Vcpu:
3031
+ """The public form of where a vCPU stopped."""
3032
+ one = dict(doc.get("vcpu") or {})
3033
+ machine = dict(doc.get("machine") or {})
3034
+ return Vcpu(
3035
+ vcpu=int(one.get("last_vcpu_id") or 0),
3036
+ entry_id=int(one.get("last_entry_id") or 0),
3037
+ exit=str(one.get("last_exit_reason_str") or ""),
3038
+ rip=int(one.get("last_rip") or 0),
3039
+ rcx=int(one.get("last_rcx") or 0),
3040
+ cs_base=int(one.get("last_cs_base") or 0),
3041
+ ic=int(one.get("last_instruction_count") or 0),
3042
+ rcb=int(one.get("last_retired_cond_branches") or 0),
3043
+ total_ic=int(one.get("last_total_ic") or 0),
3044
+ regs_hash=int(one.get("last_regs_hash") or 0),
3045
+ vtime=int(one.get("last_vtime") or 0),
3046
+ vtime_offset=int(one.get("last_vtime_offset") or 0),
3047
+ iteration=int(one.get("last_iteration") or 0),
3048
+ iterations_done=int(one.get("iterations_done") or 0),
3049
+ iterations_total=int(one.get("iterations_total") or 0),
3050
+ running=bool(one.get("run_pending")),
3051
+ ready=bool(one.get("ready")),
3052
+ checkpointing=bool(one.get("checkpoint_active")),
3053
+ until_satisfied=bool(one.get("until_satisfied")),
3054
+ halted=bool(machine.get("halted")),
3055
+ synced=bool(machine.get("synced")),
3056
+ )
3057
+
3058
+
3059
+ def syscall(row: dict[str, Any]) -> Syscall:
3060
+ """The public form of one of the guest kernel's system calls."""
3061
+ return Syscall(number=int(row["nr"]), name=str(row["name"]))
3062
+
3063
+
3064
+ def vector(row: dict[str, Any]) -> Vector:
3065
+ """The public form of one of the guest kernel's interrupt vectors."""
3066
+ return Vector(number=int(row["vector"]), name=str(row["name"]))
3067
+
3068
+
3069
+ def _count(row: dict[str, Any]) -> Count:
3070
+ """One row of a histogram."""
3071
+ return Count(
3072
+ number=int(row.get("number") or 0),
3073
+ name=str(row.get("name") or ""),
3074
+ count=int(row.get("count") or 0),
3075
+ )
3076
+
3077
+
3078
+ def counts(doc: dict[str, Any]) -> Counts:
3079
+ """The public form of what a task crossed."""
3080
+ return Counts(
3081
+ by_tgid=tuple(_count(r) for r in doc.get("by_tgid") or ()),
3082
+ by_tid=tuple(_count(r) for r in doc.get("by_tid") or ()),
3083
+ )
3084
+
3085
+
3086
+ def log_entry(record: Any) -> LogEntry:
3087
+ """The public form of one run log entry."""
3088
+ return LogEntry(
3089
+ entry_id=record.entry_id,
3090
+ event=record.event,
3091
+ event_name=record.event_name,
3092
+ vcpu=record.vcpu,
3093
+ flags=record.flags,
3094
+ flag_names=tuple(record.flag_names),
3095
+ ic=record.ic,
3096
+ rcb=record.rcb,
3097
+ total_ic=record.total_ic,
3098
+ vtime=record.vtime,
3099
+ vtime_offset=record.vtime_offset,
3100
+ rip=record.rip,
3101
+ regs_hash=record.regs_hash,
3102
+ iter=record.iter,
3103
+ data_len=record.data_len,
3104
+ text=record.text,
3105
+ )
3106
+
3107
+
3108
+ def cleanup(doc: dict[str, Any]) -> Cleanup:
3109
+ """The public form of a cleanup's outcome."""
3110
+ return Cleanup(
3111
+ cleaned=int(doc.get("cleaned") or 0),
3112
+ orphans=int(doc.get("orphans") or 0),
3113
+ run_ids=tuple(str(r) for r in doc.get("run_ids") or ()),
3114
+ )
3115
+
3116
+
3117
+ def _copy(row: dict[str, Any]) -> Copy:
3118
+ """One run or disk a session holds."""
3119
+ return Copy(
3120
+ id=str(row.get("run_id") or row.get("disk_id") or ""),
3121
+ name=str(row.get("name") or ""),
3122
+ disk_bytes=int(row.get("disk_bytes") or 0),
3123
+ state=str(row.get("local") or ""),
3124
+ )
3125
+
3126
+
3127
+ def copies(doc: dict[str, Any]) -> Copies:
3128
+ """The public form of what a session holds."""
3129
+ return Copies(
3130
+ runs=tuple(_copy(r) for r in doc.get("runs") or ()),
3131
+ disks=tuple(_copy(d) for d in doc.get("disks") or ()),
3132
+ )
3133
+
3134
+
3135
+ def prune(doc: dict[str, Any]) -> Prune:
3136
+ """The public form of a prune of the account's storage."""
3137
+ return Prune(
3138
+ op_id=int(doc.get("op_id") or 0),
3139
+ state=str(doc.get("state") or ""),
3140
+ freed_bytes=int(doc.get("freed_bytes") or 0),
3141
+ started_at=_str_or_none(doc.get("started_at")),
3142
+ error=str(doc.get("error") or ""),
3143
+ )
3144
+
3145
+
3146
+ def storage_check(doc: dict[str, Any]) -> StorageCheck:
3147
+ """The public form of a check of the account's storage."""
3148
+ return StorageCheck(
3149
+ op_id=int(doc.get("op_id") or 0),
3150
+ state=str(doc.get("state") or ""),
3151
+ objects=int(doc.get("objects") or 0),
3152
+ checked=int(doc.get("checked") or 0),
3153
+ gone=int(doc.get("gone") or 0),
3154
+ failed=int(doc.get("failed") or 0),
3155
+ bytes=int(doc.get("bytes") or 0),
3156
+ unreadable=[str(line) for line in doc.get("unreadable") or []],
3157
+ started_at=_str_or_none(doc.get("started_at")),
3158
+ finished_at=_str_or_none(doc.get("finished_at")),
3159
+ error=str(doc.get("error") or ""),
3160
+ )
3161
+
3162
+
3163
+ def storage(doc: dict[str, Any]) -> StorageInfo:
3164
+ """The public form of what the account stores."""
3165
+ running = doc.get("prune")
3166
+ return StorageInfo(
3167
+ state=str(doc.get("state") or ""),
3168
+ quota_bytes=int(doc.get("quota_bytes") or 0),
3169
+ disks_bytes=int(doc.get("disks_bytes") or 0),
3170
+ bytes=int(doc.get("bytes") or 0),
3171
+ pack_bytes=int(doc.get("packs") or 0),
3172
+ referenced_bytes=int(doc.get("referenced") or 0),
3173
+ prunable_bytes=int(doc.get("prunable") or 0),
3174
+ run_bytes=int(doc.get("runs") or 0),
3175
+ disk_bytes=int(doc.get("disks") or 0),
3176
+ measured_at=_str_or_none(doc.get("measured_at")),
3177
+ op_id=int(doc.get("op_id") or 0),
3178
+ prune=prune(running) if isinstance(running, dict) else None,
3179
+ failed_at=_str_or_none(doc.get("failed_at")),
3180
+ failed_error=str(doc.get("failed_error") or ""),
3181
+ )
3182
+
3183
+
3184
+ def transfer(row: dict[str, Any]) -> Transfer:
3185
+ """The public form of one disk transfer."""
3186
+ return Transfer(
3187
+ transfer_id=str(row.get("transfer_id") or ""),
3188
+ op=str(row.get("op") or ""),
3189
+ name=str(row.get("name") or ""),
3190
+ sha256=str(row.get("sha256") or ""),
3191
+ state=str(row.get("state") or ""),
3192
+ size_bytes=int(row.get("size_bytes") or 0),
3193
+ bytes_done=int(row.get("bytes_done") or 0),
3194
+ rate_bps=int(row.get("rate_bps") or 0),
3195
+ created_at=str(row.get("created_at") or ""),
3196
+ progress_at=_str_or_none(row.get("progress_at")),
3197
+ stopped_at=_str_or_none(row.get("stopped_at")),
3198
+ error=str(row.get("error") or ""),
3199
+ )
3200
+
3201
+
3202
+ def _str_or_none(value: Any) -> Optional[str]:
3203
+ """A string field that the service may leave out."""
3204
+ return None if value is None else str(value)
3205
+
3206
+
3207
+ @dataclass(frozen=True)
3208
+ class Recovery(_Record):
3209
+ """What `Delete.cleanup` resumed, as it reports it.
3210
+
3211
+ A delete that was interrupted leaves a marker; cleanup finishes those.
3212
+
3213
+ Attributes:
3214
+ recovered (int): Deletes it finished.
3215
+ skipped (int): Markers it left alone, such as one a live delete
3216
+ still owns.
3217
+ errors (tuple[str, ...]): What went wrong, one message each.
3218
+ """
3219
+
3220
+ recovered: int
3221
+ skipped: int
3222
+ errors: tuple[str, ...]
3223
+
3224
+
3225
+ def recovery(doc: dict[str, Any]) -> Recovery:
3226
+ """The public form of a cleanup's outcome."""
3227
+ return Recovery(
3228
+ recovered=int(doc.get("recovered") or 0),
3229
+ skipped=int(doc.get("skipped") or 0),
3230
+ errors=tuple(str(e) for e in doc.get("errors") or ()),
3231
+ )