# scope_profiler.perf_events

*module*

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``).

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/perf_events.py#L1-L1)

## scope_profiler.perf_events.EVENTS

*attribute* · *module attribute*

```python
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)}
```

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/perf_events.py#L21-L32)

## scope_profiler.perf_events.PerfEventError

*class*

```python
class PerfEventError(RuntimeError)
```

Bases: `RuntimeError`

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

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/perf_events.py#L15-L16)

## scope_profiler.perf_events.PerfEventGroup

*class*

```python
class PerfEventGroup
```

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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/perf_events.py#L143-L214)

### scope_profiler.perf_events.PerfEventGroup.events

*attribute* · *instance attribute*

```python
events = events
```

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/perf_events.py#L154-L154)

### scope_profiler.perf_events.PerfEventGroup.fds

*attribute* · *instance attribute*

```python
fds: list[int] = []
```

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/perf_events.py#L155-L155)

### scope_profiler.perf_events.PerfEventGroup.close

*method*

```python
def close() -> None
```

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/perf_events.py#L207-L214)

### scope_profiler.perf_events.PerfEventGroup.start

*method*

```python
def start() -> None
```

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/perf_events.py#L158-L175)

### scope_profiler.perf_events.PerfEventGroup.stop

*method*

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

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/perf_events.py#L177-L205)

## scope_profiler.perf_events.PerfEventTotals

*class* · *dataclass*

```python
class PerfEventTotals
```

Aggregated counts for one region.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/perf_events.py#L75-L80)

### scope_profiler.perf_events.PerfEventTotals.calls

*attribute* · *instance attribute*

```python
calls: int
```

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/perf_events.py#L79-L79)

### scope_profiler.perf_events.PerfEventTotals.values

*attribute* · *instance attribute*

```python
values: dict[str, int]
```

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/perf_events.py#L80-L80)

## scope_profiler.perf_events.validate_events

*function*

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

Normalize requested event names and reject unsupported names early.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/perf_events.py#L48-L72)