Expand description
The cache check: comparing a step’s recorded observations with the file system.
check compares every recorded observation with the current state of its
path, concurrently, and lists every Difference. The step is a cache hit only
when there is none. The rules of “Cache check”:
- A regular file or a directory whose type, permission bits, or owner differ has changed, found without hashing, whatever its content: a command may check them. The permission bits are the low twelve bits of the mode, the set-user-ID, set-group-ID, and sticky bits included.
- A regular file that was read has a hash. A different size is a change, found without hashing. The same size and the same metadata (modification and change times, inode, device, mode, and owner) is unchanged. The same size, mode, and owner with different times, inode, or device is hashed: an equal hash means unchanged, and the check returns the new metadata so the record can store it.
- When the recorded modification time is within two seconds of when the record was written, or later, metadata cannot prove the file unchanged, so it is hashed even when the metadata matches, as git does for racily clean files.
- A regular file that was not read has no hash: any difference in size or metadata, the owner included, is a change.
- A directory’s mode and owner are always compared. A listed directory is listed again and compared by its entries, in the order the file system returns them: an equal listing hash is unchanged; otherwise an equal hash of the sorted entries means only the order changed, and a different one that the entries changed, naming those that appeared, disappeared, or changed type when both listings kept their entries.
- For a step run with
timestamps, a regular file that was read or run, or a directory that was read, listed, or checked, whose modification or change time differs has changed, found without hashing, after its permission bits and owner and, for a file, its size. A file that was only checked or written already compares its times with the rest of its metadata. Access times are never compared, and neither are the times of a symbolic link itself: its pointee follows the rule. Withouttimestamps, the bytes decide for a file that was read, and directory times are never compared. - A symbolic link is compared by its target, then by the state of what it points to.
- Devices, FIFOs, and sockets are compared by type.
- A path whose extended attributes were recorded is compared by them too, once the
rest of its state matches: they are read again through the attribute query of the
tracer interface (see
record_attributes), and an attribute that appeared, disappeared, or changed value, of the path itself or, for a symbolic link, of what it points to, is a change. - Untracked paths under
/procand/sysare never compared. Tracked ones are read and hashed again, without the cache of file states, because their metadata says nothing about their content. A symbolic link that leads into/procor/sysis compared by its target, and its untracked pointee is not compared.
Hashes of files that were not tracked go through the build’s FileStates, so a
file is hashed once per build.
Structs§
- Checked
- The result of comparing a step’s recorded observations with the file system.
Constants§
- RACY_
WINDOW_ NANOS - How close to when a record was written a recorded modification time must be, in nanoseconds, for metadata not to prove a file unchanged: two seconds.
Functions§
- check
- Compare every observation in
observations, recorded with the record written atrecorded_at_nanos, with the file system, concurrently on the worker pool ofstates, hashing throughstates. Withtimestamps, the times of what the step read, ran, listed, or checked are compared too. Recorded extended attributes are read again through the attribute query oftracer.