PerfCheckerLinuxPerf full API

This reference renders actual Julia docstrings from PerfCheckerLinuxPerf 1.0.1, including any documented private bindings. Undocumented internal functions are not presented as documented APIs. Start with the public API.

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

Index

• PerfCheckerLinuxPerf.PerfCheckerLinuxPerf
• PerfCheckerLinuxPerf.CounterRecord
• PerfCheckerLinuxPerf.CounterResult
• PerfCheckerLinuxPerf._counter_checker_result
• PerfCheckerLinuxPerf.counter_bundle
• PerfCheckerLinuxPerf.counter_command
• PerfCheckerLinuxPerf.counter_executor
• PerfCheckerLinuxPerf.measure_counters
• PerfCheckerLinuxPerf.run_counter_suite

Docstrings

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_checker_result Method

_counter_checker_result(bundle::RunBundle, tags)

Convert completed provider evidence to a qualified PerfChecker.CheckerResult. Retain its raw payload and copied worker qualification without running counters. Unavailable, invalid and blocked states raise their existing typed failures; other incomplete states raise an error rather than becoming successful results.

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