Skip to main content

Module check

Module check 

Source
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. Without timestamps, 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 /proc and /sys are 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 /proc or /sys is 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 at recorded_at_nanos, with the file system, concurrently on the worker pool of states, hashing through states. With timestamps, the times of what the step read, ran, listed, or checked are compared too. Recorded extended attributes are read again through the attribute query of tracer.