testflows.machine 0.1.0__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.
Potentially problematic release.
This version of testflows.machine might be problematic. Click here for more details.
- testflows/machine/v1/__init__.py +278 -0
- testflows/machine/v1/_args.py +528 -0
- testflows/machine/v1/_requires.py +103 -0
- testflows/machine/v1/_service.py +109 -0
- testflows/machine/v1/_version.py +16 -0
- testflows/machine/v1/_when.py +55 -0
- testflows/machine/v1/client.py +1924 -0
- testflows/machine/v1/disks.py +669 -0
- testflows/machine/v1/errors.py +255 -0
- testflows/machine/v1/login.py +107 -0
- testflows/machine/v1/ping.py +70 -0
- testflows/machine/v1/results.py +3231 -0
- testflows/machine/v1/runs.py +7648 -0
- testflows/machine/v1/sessions.py +751 -0
- testflows_machine-0.1.0.dist-info/METADATA +116 -0
- testflows_machine-0.1.0.dist-info/RECORD +20 -0
- testflows_machine-0.1.0.dist-info/WHEEL +5 -0
- testflows_machine-0.1.0.dist-info/licenses/LICENSE +203 -0
- testflows_machine-0.1.0.dist-info/licenses/NOTICE +7 -0
- testflows_machine-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -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
|
+
)
|