MeasurementDir

Documentation for the MeasurementDir component within the booblik-benchmark module, focusing on its role in ensuring measurement integrity by preventing volatile filesystems and providing environmental context.

Diagram

What this module is responsible for

The MeasurementDir object is responsible for ensuring that any directory used for benchmarking is backed by physical storage rather than volatile memory. It prevents the "false speed" trap where fsync operations return instantly because they are only hitting RAM, as seen in the failure where a probe reported 0.01 ms fsync on tmpfs (MeasurementDir.kt:10-13).

MeasurementDir

The core object responsible for creating valid measurement environments. It acts as a guard against invalid measurement mediums, ensuring that the results reflect disk performance rather than memory speed (MeasurementDir.kt:27-49).

Volatile Filesystem Refusal

The mechanism that prevents measurements on tmpfs or ramfs to avoid measuring memory instead of disk. The module defines a set of VOLATILE filesystems (tmpfs, ramfs) (MeasurementDir.kt:32) and will refuse to return a directory if the FileStore type matches these, as a measurement on such a medium is considered "fiction" (MeasurementDir.kt:33-47).

The create Lifecycle

The process of resolving the base directory via booblik.bench.dir and validating the FileStore type. The create function first checks for the booblik.bench.dir system property (MeasurementDir.kt:40); if absent, it defaults to build/measurements (MeasurementDir.kt:40). After creating the base directories (MeasurementDir.kt:41), it validates the FileStore to ensure the medium is not volatile before returning a new temporary directory with the provided prefix (MeasurementDir.kt:41-49).

Filesystem Description

The describe function and its role in providing the medium's identity in report headers. This function attempts to retrieve the FileStore for a given path to return a string containing the filesystem type and name (MeasurementDir.kt:58-62), which is used in probe reports to ensure results are comparable across different hosts (MeasurementDir.kt:54-56).

Key files

Behaviour that surprises

• The create function will throw an IllegalStateException rather than issuing a warning if a volatile filesystem is detected, because a warning is often ignored after the number has already been believed (MeasurementDir.kt:24-25).
• The default measurement directory is not the system's temporary directory (java.io.tmpdir), but build/measurements, to ensure measurements land on a real filesystem where the source tree lives (MeasurementDir.kt:22-23).