NAME

problem48-indicator-watch-benchmark - compare event and metadata validation

PURPOSE

Measures the integrated stable indicator-sync check with a real Linux inotify watch against the existing portable directory and high-resolution stat validator. It requires exact indicator inventory parity and verifies that an external status write invalidates the next check and is returned by full sync.

WHY IT EXISTS

An empty inotify poll is not evidence of a useful dashboard optimization by itself. This benchmark measures the actual IndicatorStore helper that otherwise enumerates indicator directories and stats persisted status files, using the same in-memory store and filesystem fixture in both arms.

WHEN TO USE

Run it after changing IndicatorStore::Watch, stable collector sync, or the portable freshness validator. It requires Linux, FFI::Platypus, and libc inotify support; the regular test suite does not require those optional pieces.

HOW TO USE

Install the optional test dependency and run inside the project Docker dev service:

cpanm FFI::Platypus
perl script/problem48-indicator-watch-benchmark --indicators 50 --iterations 100 --runs 21

The command creates a private temporary HOME for synthetic status files. It does not use or modify the real dashboard state.

WHAT USES IT

Problem 48 performance research uses this benchmark to decide whether Linux event notifications should remain in the production sync path. It is a measurement tool, not a dependency of dashboard startup.

EXAMPLES

Example 1: compare a 50-indicator setup with 21 alternating samples.

perl script/problem48-indicator-watch-benchmark

Example 2: scale the inventory and increase each timed sample.

perl script/problem48-indicator-watch-benchmark --indicators 500 --iterations 100 --runs 31

Example 3: inspect accepted options without installing FFI.

perl script/problem48-indicator-watch-benchmark --help

OUTPUT

The report includes median milliseconds per helper call, exact inventory parity, external-write freshness, and the portable-to-watcher speed ratio. Every timed call must return an unchanged result or the program exits with a visible error.

SAFETY

The benchmark writes only under its private temporary HOME, runs no shell commands, and uses generated collector names. It restores its original working directory before normal exit. All failed setup, parity, or freshness checks are fatal and visible.