PerfCheckerLIKWID public API

This reference uses the actual Julia docstrings of PerfCheckerLIKWID 1.0.1. These APIs are absent from the stable PerfChecker 1.0.0 source. Rendering documentation does not execute a counter window or qualify hardware availability.

The full API is the canonical reference. The companion requires an explicit Julia executor; it is not a native CLI, VS Code, Pluto or MCP selector.

PerfCheckerLIKWID.PerfCheckerLIKWID Module

Optional LIKWID CPU counters in explicitly prepared PerfChecker worker projects. This companion changes no permissions, libraries, thread affinity or CPU settings.

source

PerfCheckerLIKWID.CounterRecord Type

CounterRecord(event, counter, cpu_id, unit, value::Float64)

One raw native LIKWID record. event and counter are the exact custom event and FIXC/PMC names; cpu_id is the selected logical CPU ID. unit is the explicit event declaration (documented instruction/cycle events use count unit 1). value retains the backend's Float64 representation without scaling or an invented exact integer count. Attribution depends on the access mode and PID in CounterResult; a CPU ID alone does not imply whole-process attribution.

source

PerfCheckerLIKWID.CounterResult Type

CounterResult(status, reason, records, allowed_cpuids, cpuids,
              group_time_seconds, access_mode, perf_pid)

Evidence for a native selected-CPU backend window. status is :complete or :unavailable for native measurement; worker evidence can be :blocked for a blocking probe, :invalid for a failed oracle or :failed for an error. reason explains refusal/failure; records holds raw CounterRecords and is empty when unavailable. allowed_cpuids is inherited affinity; cpuids is the explicit selection. group_time_seconds is native group time in seconds, or nothing; enabled/running times are not exposed by this backend API.

access_mode records the native PERF/DIRECT/DAEMON mode; perf_pid records the optional own-process PID setting, or nothing. Direct/daemon windows can include unrelated CPU activity; PERF semantics depend on the installed library and PID setting, without a guarantee of counting all process threads. The six-argument constructor leaves mode "not_recorded" and PID nothing; it does not attest native attribution. No counts are converted into duration and no CPUs are pinned.

source

PerfCheckerLIKWID.counter_bundle Method

counter_bundle(result; case_id="counters", target_id="current") -> RunBundle

Preserve LIKWID's raw Float64 values with exact event, counter and CPU identity. Units come exclusively from the event declaration. Group time is separate in seconds; enabled/running fields are nothing with an explicit absence reason. Values are not converted to exact integers, scaled or interpreted as duration. Unavailable windows have no observations. This creates evidence only, without executing callbacks or writing files.

source

PerfCheckerLIKWID.counter_command Method

counter_command(id; source, environment, package, target_kind, target_version,
                target_source=nothing, oracle="", probes=[], event_set, cpuids, units,
                timeout_seconds=300) -> ExternalCommandSpec

Declare a bounded, isolated Julia counter worker. environment is an existing, explicitly prepared project containing this companion and the exact target. Release version and development source identities are verified before including the workload; this function installs nothing and executes nothing. source defines perf_setup(), perf_workload(state), optional perf_synchronize(state, result), perf_cleanup(state), and the declared oracle. The operation runs once; the two-argument oracle receives that actual result. Preparation/probes/oracle/cleanup are outside the counter window. A supplied perf_cleanup is attempted after preparation returns successfully, including measurement/oracle failures. If perf_setup throws before returning, it is responsible for releasing its partial resources. Subprocesses inherit the caller's affinity and environment; no CPUs are repinned.

source

PerfCheckerLIKWID.counter_executor Method

counter_executor(; bundle_sink=(planned, bundle)->nothing)

Return the explicit executor for run_suite(plan; executor=...). Each row uses ExternalCommandSpec and validates its actual worker target. The sink receives portable provider evidence even for unavailable/failed runs. Use run_counter_suite to retain this evidence in all suite qualifications. This companion specializes PerfChecker's current internal unavailable predicate only for its own exception type; ordinary executors and Pkg exceptions are unchanged.

source

PerfCheckerLIKWID.measure_counters Method

measure_counters(f; event_set, cpuids, units) -> CounterResult

Count one invocation using LIKWID 0.4.6's low-level PerfMon API. All arguments are explicit: custom CPU event/counter pairs (for example "INSTR_RETIRED_ANY:FIXC0,CPU_CLK_UNHALTED_CORE:FIXC1"), CPU IDs inside the calling thread's inherited affinity, and a unit dictionary keyed by exact event. Group aliases, event options and uncore counters are refused. Nothing is pinned.

The scope is a native backend window on selected CPUs. The actual access mode and optional LIKWID_PERF_PID are recorded; a foreign or invalid PID is refused. Direct/daemon modes may include unrelated CPU activity. PERF attribution depends on the installed native library and PID setting: this API does not guarantee all threads of a process. LIKWID itself may set its own PID at import. Preparation and oracle work must be outside f; asynchronous work must be synchronized inside f. Values retain the backend's Float64 representation, not an invented exact UInt64 count. No scaling is added. Group time is reported separately in seconds; enabled/running times are unavailable because this API does not expose them. Units are caller declarations, never inferred from names or values; cycles must not be declared as duration. A missing library/refused initialization returns :unavailable without calling f. Callback and stop/read errors propagate after owned native state is finalized. Pre-existing PerfMon/topology/NUMA state is refused rather than finalized. No kernel settings or capabilities are changed.

source

PerfCheckerLIKWID.run_counter_suite Method

run_counter_suite(plan::SuitePlan; strict=false, kwargs...) -> SoftwareSuiteResult

Run a declared :likwid suite through real isolated counter workers. Capture provider bundles and qualification/provenance for every attempted row, including unavailable rows. Targets/dependencies must already be prepared in each explicit counter_environment; no target installation is performed by this companion. strict=true raises for an execution failure after collecting evidence. Hardware unavailability remains visible and is never a successful measurement assertion.

source