Metadata-Version: 2.4
Name: asv_bench_tachyon
Version: 0.1.0
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: cli
Requires-Dist: asv>=0.6.4; extra == 'cli'
Requires-Dist: click>=8.1; extra == 'cli'
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

**Real ASV benchmark plugin** (same shape as [`asv_bench_memray`](https://pypi.org/project/asv-bench-memray/)): a new metric type discovered by `asv_runner`, stored in results, plotted and compared across commits.

Uses Python 3.15 **Tachyon** (`profiling.sampling`) to estimate **self-time per call** from stack samples.

## This is a metric plugin

| | `asv_bench_tachyon` | `asv profile` / flame graphs |
|--|--|--|
| ASV name | `sample_*` / `Sample*` | N/A |
| `asv run` stores a number | **yes** | no |
| Graphs / compare / regressions | **yes** | no |
| Discovery | package name `asv_bench*` | conf plugins / GUI |

## Install

```bash
# into the same env ASV uses for the project (Python >= 3.15)
pip install asv_bench_tachyon
```

`asv.conf.json`:

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

## Write a benchmark

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

Result unit: **seconds** (estimated exclusive time per call from sample counts × interval).

## How it works

1. A background thread samples **this process** via `profiling.sampling.sample(pid, ...)`.
2. The main thread runs your function in a loop for `sample_duration`.
3. Direct samples whose function name matches the benchmark are converted to time and divided by call count.

Same discovery contract as memray: `export_as_benchmark = [SampleTimeBenchmark]`.

## Optional CLI

```bash
asv-tachyon doctor
```

## License

MIT.
