Expand description
The state of every path a step touched, recorded when the step finishes.
observe turns the accesses a tracer reported into observations, recording
the paths concurrently. Paths that an ignore pattern matches are left out and
counted. Each other path gets the PathState that “Path states” specifies:
- absent paths:
PathState::Absent; - regular files: size, modification and change times in nanoseconds, inode, device,
mode, and owner, plus a BLAKE3 hash of the content only when the file was read or
run, hashed with several threads for large files, through the build’s
FileStates, so a file is hashed once per build; - directories: mode, owner, and modification and change times, and when they were
listed, also a hash of the entry names and types in the order the file system
returned them, a hash of the same entries sorted, and the entries in that order when
there are at most
MAX_LISTED_NAMES; entry inode numbers are not recorded; - symbolic links: the target, plus the state of what the link points to;
- devices, FIFOs, and sockets: type only.
A path whose extended attributes the step read or listed, the xattr kind, also
records them with its state (see record_attributes): each name with a BLAKE3
hash of its value, sorted by name, for the path itself and, for a symbolic link,
for what it points to. Kizz reads them only through the attribute query of the
tracer interface, Tracer::extended_attributes, because the standard library
cannot read them.
Paths under /proc and /sys are recorded as PathState::Untracked unless a
track pattern matches them; a tracked one gets its state, with the content of
a regular file read and hashed again whatever the access, never from the cache.
A path that symbolic links lead into /proc or /sys, such as /dev/fd/3 or
/dev/stdin, leaves only that final object untracked (see kernel_links): the
links on the way stay ordinary dependencies, each recorded with its target, so
retargeting, removing, or replacing one of them changes the step. A final link is
recorded as PathState::Symlink with an untracked pointee, and every other link
on the way is recorded as such a link too, as a probe.
changed_after_read compares the first-read metadata that the tracer noted
with the recorded states, to find the files that changed during the run after
the command first read them or ran them.
Structs§
- Hash
Counter - Counts the files whose content was hashed, so tests can observe hashing.
- Observed
- The observations of one step.
Functions§
- access_
bits - The access kinds
kindsas the store records them. - changed_
after_ read - The files that changed during a run after the command first read them or ran
them, sorted by path: each path in
first_readswhose recorded state inobservations, following a final symbolic link, is not a regular file with the noted device, inode, size, modification and change times, mode, and owner. No file, another type, and an inaccessible path are changes too. Each says whether the command wrote the path, as its access kinds show. - is_
kernel_ path - Whether
pathis under/procor/sys, or is one of them. - kernel_
links - The symbolic links outside
/procand/sys, each with its target, that leadpathinto/procor/sys, in the order a path lookup follows them;Nonewhenpathdoes not reach/procor/sys, and no links when it is under one of them already. - listing
- The listing of
entries, in the order given: the hash of their names and types in that order, the hash of the same entries sorted by name and type, and the entries in that order when there are at mostMAX_LISTED_NAMES. - observe
- Record the state of every path in
accesses, concurrently on the worker pool ofstates, leaving out and counting the paths thatignorematches, and hashing the/procand/syspaths thattrackmatches. Hashes go throughstates, and the extended attributes of the paths whose attributes were read or listed come from the attribute query oftracer. - path_
state - The state of
path, which a step touched withkinds, without following a final symbolic link. A regular file is hashed when it was read or run, through the cachestates, or whenforce_hashis set, read again without the cache. - reaches_
kernel - Whether
pathis under/procor/sys, or the symbolic links on the way to it lead there, as/dev/fdleads to/proc/self/fdand/dev/stdinto/proc/self/fd/0(seekernel_links). - record_
attributes - The extended attributes of
pathnow, as a path whose attributes were read or listed records them, read through the attribute query oftracer: those of the path itself, without following a final symbolic link, and, when the path is a symbolic link, those of what it points to. Each list holds every name with a BLAKE3 hash of its value, sorted by name, or isNonewhen the query fails, as it does when nothing is at the path; a file system without attributes has none.