NAME
Developer::Dashboard::CollectorRunner - collector execution and loop management
SYNOPSIS
my $runner = Developer::Dashboard::CollectorRunner->new(...);
my $result = $runner->run_once($job);DESCRIPTION
This module runs collector jobs on demand and as managed background loops. It handles scheduling, timeout enforcement, process naming, persisted loop state, shell-command collectors, Perl-code collectors, and TT-backed collector indicator icon rendering from stdout JSON. Collector working directories resolve built-in accessors and configured path aliases, followed by skill-qualified aliases provided by installed lib/Folder.pm modules.
CRON SCHEDULING
Managed loops infer cron mode from a non-empty cron property or accept the explicit schedule => 'cron' setting. The expression must contain exactly five fields: minute, hour, day of month, month, and day of week. The parser supports numeric values, comma-separated lists, ranges, range steps, */step, and case-insensitive month and weekday names. Sunday may be 0 or 7. When both date fields are restricted, either a day-of-month or day-of-week match makes the date due. The loop evaluates machine-local time once per second and persists the last matching minute to prevent duplicate runs.
Missing, empty, malformed, out-of-range, or overlong expressions are rejected before a loop process is spawned. This keeps a bad configuration from turning into an every-second job. See the user-facing dashboard documentation for the config/config.json example and accepted syntax.
METHODS
new, run_once, start_loop, stop_loop, running_loops, loop_state
Construct and manage collector execution.
PURPOSE
This module manages live collector execution. It turns stored collector jobs into processes, captures their output, updates collector state files, renders TT-backed collector indicator icons from stdout JSON when configured, tracks pid ownership, and exposes the start/stop/restart/run/status lifecycle used by the CLI and web-facing status features.
WHY IT EXISTS
It exists because collector process control is more than a single system() call. The dashboard needs a single owner for pid validation, output capture, environment preparation, enabled/disabled state, and restart behavior so the prompt and browser status strip can trust the result.
WHEN TO USE
Use this file when changing collector process spawning, pid validation, restart semantics, background job cleanup, TT-backed indicator icon rendering, the contract between collector execution and persisted collector state, or how the collector's cwd value resolves from path aliases.
HOW TO USE
Construct it with the path registry and collector store, then call the lifecycle methods for one collector name. Keep process-management behavior and TT-backed collector icon rendering here; the CLI wrappers should only parse arguments and print the returned state.
For run_once, a relative cwd first checks built-in directory accessors, then configured aliases from merged dashboard config, then a qualified skill Folder.pm method (for example collectorpaths.workspace). If no alias applies, an existing relative directory remains valid. Config aliases win over skill methods with the same name; skill aliases are read-only.
WHAT USES IT
It is used by the dashboard collector ... command family, by runtime restart/stop flows that manage collectors together with the web process, and by collector/runtimemanager regression tests.
EXAMPLES
Example 1:
perl -Ilib -MDeveloper::Dashboard::CollectorRunner -e 1Do a direct compile-and-load check against the module from a source checkout.
Example 2:
prove -lv t/02-indicator-collector.tRun the focused regression tests that most directly exercise this module's behavior.
Example 3:
HARNESS_PERL_SWITCHES=-MDevel::Cover prove -lr tRecheck the module under the repository coverage gate rather than relying on a load-only probe.
Example 4:
prove -lr tPut any module-level change back through the entire repository suite before release.