scope_profiler.perf_events

Small Linux perf_event_open wrapper used for region counter totals.

The wrapper intentionally uses only the stable hardware and software event types exposed by linux/perf_event.h. It has no third-party dependency and keeps counters attached to the calling thread (pid=0, cpu=-1).

Attributes

Name	Description
EVENTS	No description.

Classes

Name	Description
PerfEventError	A requested kernel performance event could not be opened or read.
PerfEventGroup	Counters opened for one active region invocation.
PerfEventTotals	Aggregated counts for one region.

Functions

Name	Description
validate_events	Normalize requested event names and reject unsupported names early.

EVENTSattributemodule attribute#

View source

EVENTS = {
  'cycles': (0, 0),
  'instructions': (0, 1),
  'cache-references': (0, 2),
  'cache-misses': (0, 3),
  'branches': (0, 4),
  'branch-misses': (0, 5),
  'cpu-clock': (1, 0),
  'task-clock': (1, 1),
  'page-faults': (1, 2),
  'context-switches': (1, 3)
}

Show moreShow less

PerfEventErrorclass#

View source

class PerfEventError(RuntimeError)

Bases: RuntimeError

A requested kernel performance event could not be opened or read.

PerfEventGroupclass#

View source

class PerfEventGroup(events: tuple[str, ...])

Counters opened for one active region invocation.

When the optional py-perf-event package can represent every requested event, its Rust implementation is used. It surfaces multiplexed/partial reads, avoiding understated counts on oversubscribed PMUs. The standard library syscall implementation remains the dependency-free fallback and also covers the software events not exposed by that package.

eventsattributeinstance attribute#

View source

events = events

fdsattributeinstance attribute#

View source

fds: list[int] = []

closemethod#

View source

def close() -> None

startmethod#

View source

def start() -> None

stopmethod#

View source

def stop() -> dict[str, int]

PerfEventTotalsclassdataclass#

View source

class PerfEventTotals(calls: int, values: dict[str, int])

Aggregated counts for one region.

callsattributeinstance attribute#

View source

calls: int

valuesattributeinstance attribute#

View source

values: dict[str, int]

validate_eventsfunction#

View source

def validate_events(events) -> tuple[str, ...]

Normalize requested event names and reject unsupported names early.