PerfCheckerLinuxPerf public API

This reference uses the actual Julia docstrings of PerfCheckerLinuxPerf 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.

PerfCheckerLinuxPerf.PerfCheckerLinuxPerf Module

Optional Linux perf-event counters for explicitly configured PerfChecker workers. No capabilities, kernel settings, CPU affinity or installed libraries are changed.

source

PerfCheckerLinuxPerf.CounterRecord Type

CounterRecord(event, value::UInt64, enabled_ns::UInt64, running_ns::UInt64)

One raw Linux perf-event record. event is the exact canonical event name; value is an unscaled count (unit 1). enabled_ns and running_ns are the kernel's unsigned nanosecond times for that group window, not operation duration. The record covers the selected calling OS thread's user-space activity, excluding kernel, hypervisor, other threads and children. Cycles are counts, not seconds.

source

PerfCheckerLinuxPerf.CounterResult Type

CounterResult(status, reason, records, thread_id, allowed_cpuids)

Evidence for one calling-thread counter window. status is :complete or :unavailable for native measurement; the isolated worker also uses :blocked for a blocking probe, :invalid for a failed oracle and :failed for an error. reason explains refusal/failure; records holds raw CounterRecords and is empty when unavailable. thread_id is the measured Linux OS thread ID; zero means no thread identity was captured. allowed_cpuids records inherited affinity, not CPUs measured individually. No affinity is changed and callbacks that yield may run outside the measured thread. Enabled/running times are not used to scale counts or infer duration.

source

PerfCheckerLinuxPerf.counter_bundle Method

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

Project a measured window into PerfChecker's portable evidence. Count units are 1, including CPU cycles; this is never a duration. Exact raw UInt64 counts and enabled/running nanoseconds are preserved as decimal strings in the raw diagnostic. Numeric observations are emitted only up to 2^53-1, so consumers using IEEE Float64 cannot silently round larger counts. Such omitted observations carry a warning. Unavailable results have no numeric observations or fake zeros. No files are written and no callback is repeated.

source

PerfCheckerLinuxPerf.counter_command Method

counter_command(id; source, environment, package, target_kind, target_version,
                target_source=nothing, oracle="", probes=[], events=["instructions", "cpu-cycles"],
                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

PerfCheckerLinuxPerf.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

PerfCheckerLinuxPerf.measure_counters Method

measure_counters(f; events=["instructions", "cpu-cycles"]) -> CounterResult

Measure exactly one call to f with a fresh LinuxPerf 0.4.2 perf-event group. Little-endian Linux x86_64, i686 and aarch64 are supported at the syscall/ABI boundary; other architectures or a mismatched native layout return :unavailable before f. The scope is the calling OS thread, user space only, excluding the hypervisor; other threads, child processes and kernel execution are not counted. Callbacks that yield can execute elsewhere, so this is not a whole-process measurement. No affinity is changed. Counts are raw UInt64; enabled/running are raw kernel nanoseconds. Counts are never scaled and cycles are never converted to duration.

An accepted event unavailable at opening, an unsupported platform/ABI, or denied permissions returns :unavailable without calling f. counter_not_scheduled is different: the group was opened and f ran once, but its recorded running time was zero. That result is unavailable with no numeric counters, not a measured zero. Empty, duplicate or unaccepted event names throw ArgumentError. Callback, read and stop errors propagate after owned descriptors are closed. A successful window with zero running time is unavailable, not a measured zero. Loading this package changes no permissions.

source

PerfCheckerLinuxPerf.run_counter_suite Method

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

Run a declared :linuxperf 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