Metadata-Version: 2.4
Name: asv_bench_tachyon
Version: 0.1.2
Summary: Tachyon sampling benchmark type for ASV (sample_* metrics via profiling.sampling)
Project-URL: Source, https://github.com/HaoZeke/asv_bench_tachyon
Project-URL: Issues, https://github.com/HaoZeke/asv_bench_tachyon/issues
Author-email: Rohit Goswami <rgoswami@ieee.org>
Maintainer-email: Rohit Goswami <rgoswami@ieee.org>
License: MIT
License-File: LICENSE
Keywords: asv,benchmark,profiling,sampling,tachyon
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: System :: Benchmark
Requires-Python: >=3.15
Requires-Dist: asv-runner>=0.2.1
Provides-Extra: test
Requires-Dist: asv>=0.6.4; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# asv_bench_tachyon

ASV **benchmark type** plugin (same contract as
[asv_bench_memray](https://pypi.org/project/asv-bench-memray/)).

Defines `sample_*` / `Sample*` benchmarks. `asv run` stores a **number**
(estimated exclusive time per call from Python 3.15 Tachyon samples) in results
for history, compare, and graphs.

There is no separate CLI package. Install this into the benchmark environment
and write `sample_*` functions.

## Related packages (metric plugin vs web UI)

| Package | Role |
|---------|------|
| **[asv](https://asv.readthedocs.io/)** | Run benchmarks, write results, `asv publish` |
| **[asv-runner](https://github.com/airspeed-velocity/asv_runner)** | Discovers builtin + external `asv_bench*` types |
| **asv_bench_tachyon** (this package) | **`sample_*` metric plugin** — a number in ASV results |
| **[asv-tachyon](https://github.com/HaoZeke/asv_tachyon)** | **Modern web UI** over published ASV HTML (not this package) |
| **[asv-spyglass](https://github.com/airspeed-velocity/asv_spyglass)** | CLI compare + SBOM-style `env-diff` |
| **[asv-perch](https://github.com/HaoZeke/asv-perch)** | PR comment tables (CI) |
| **[asv_bench_memray](https://pypi.org/project/asv-bench-memray/)** | `ray_*` peak-memory metric plugin (same discovery contract) |

**asv_bench_tachyon is not the asv-tachyon web UI.** Installing this package does
not serve or replace the results site. It only registers a new benchmark
*type* so `sample_hot_loop` is measured via Tachyon sampling and written into
the usual ASV result JSON. Pair with asv-tachyon only if you want the modern
dashboard over `asv publish` output.

## Install

```bash
pip install asv_bench_tachyon
```

Python **>= 3.15** (needs stdlib `profiling.sampling`). The package must be
importable **inside each ASV benchmark environment**, not only on the host that
runs `asv`. Put it on the ASV matrix:

```json
{
  "matrix": {
    "req": {
      "pip+asv_bench_tachyon": [""]
    }
  }
}
```

Editable / local checkout during development:

```json
{
  "matrix": {
    "req": {
      "pip+asv_bench_tachyon": ["../asv_bench_tachyon"]
    }
  }
}
```

If an environment was created before the matrix change:

```bash
rm -rf .asv/env
asv run --bench sample_
```

## Benchmark attributes

Name the function `sample_*` or `Sample*` so the type is selected. Optional
attributes (also accepted on the class or module, first wins via
`asv_runner`):

| Attribute | Default | Meaning |
|-----------|---------|---------|
| `sample_mode` | `"wall"` | Tachyon sampling mode: `"wall"`, `"cpu"`, or `"gil"` |
| `sample_duration` | `0.25` | Seconds of sampling (clamped to ≥ 0.05) |
| `sample_interval_usec` | `1000` | Sample interval in microseconds (clamped to ≥ 100) |

### `sample_mode`

| Mode | Use when |
|------|----------|
| `"wall"` | Wall-clock inclusive sampling (default). Good general exclusive-time estimate under load. |
| `"cpu"` | CPU-time sampling. Prefer for pure compute loops that should ignore I/O wait. |
| `"gil"` | GIL-oriented sampling. Prefer when contention / hold time is the signal of interest. |

Invalid values raise `ValueError` at run time.

### `sample_duration`

How long the sampler and the call loop run. Longer duration → more stack
samples → stabler exclusive-time estimate, at the cost of wall time per
benchmark. Values below `0.05` are raised to `0.05`.

### Metric returned

Estimated **seconds per call**:

```text
(self_samples * sample_interval_s) / n_calls
```

Self samples are counted for the benchmark function name when present;
otherwise all collector direct-call counts are summed. Unit is `seconds`,
type is `time`, so stock ASV history / compare / graphs work unchanged.

## Example

```python
class Suite:
    def sample_hot_loop(self):
        s = 0
        for i in range(200_000):
            s += i * i
        return s

    sample_hot_loop.sample_mode = "cpu"     # wall | cpu | gil
    sample_hot_loop.sample_duration = 0.25  # seconds of sampling
```

```bash
asv run --bench sample_hot_loop
```

A full mini-suite (two `sample_*` functions, matrix install, `asv.conf.json`)
lives under [`examples/`](examples/).

## Discovery contract

`asv_runner` loads external types the same way as memray:

1. Distribution / package **name starts with** `asv_bench`
2. Package has a `benchmarks/` subpackage
3. Each submodule may export `export_as_benchmark = [SomeBenchmark, ...]`

This package:

- Distribution name: `asv_bench_tachyon`
- Module: `asv_bench_tachyon.benchmarks.sampletime`
- Export: `export_as_benchmark = [SampleTimeBenchmark]`
- Name regex: `^(Sample[A-Z_].+)|(sample_.+)$`

No `asv profile` GUI, no standalone CLI, no HTML UI. Metrics only.

## License

MIT.
