asv-tachyon 0.1.0__tar.gz

asv_tachyon-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+# Byte-compiled
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+src/asv_tachyon/_version.py
+
+# Testing / tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Envs
+.venv/
+venv/
+.env
+.env.*
+
+# ASV / tachyon artifacts
+.asv/
+*.tachyon.bin
+flamegraph*.html
+heatmap*/
+
+# Docs
+docs/build/
+docs/source/*.rst
+!docs/source/conf.py
+docs/source/tutorials/
+docs/source/howto/
+docs/source/reference/
+docs/source/explanation/
+docs/source/contributing/
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# uv / pixi
+uv.lock
+.pixi/

asv_tachyon-0.1.0/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+<!-- towncrier release notes start -->

asv_tachyon-0.1.0/CODEOWNERS

@@ -0,0 +1,13 @@
+# This is a comment.
+# Each line is a file pattern followed by one or more owners.
+
+# These owners will be the default owners for everything in
+# the repo. Unless a later match takes precedence,
+# @global-owner1 and @global-owner2 will be requested for
+# review when someone opens a pull request.
+*       @HaoZeke
+
+# Order is important; the last matching pattern takes the most
+# precedence. When someone opens a pull request that only
+# modifies JS files, for example, only @js-owner and not the global
+# owner(s) will be requested for a review.

asv_tachyon-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

asv_tachyon-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+MIT License Copyright (c) 2024 Rohit Goswami (HaoZeke) <rgoswami[at]ieee.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice (including the next
+paragraph) shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
+OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

asv_tachyon-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: asv-tachyon
+Version: 0.1.0
+Summary: Near-zero-overhead Tachyon sampling profiles for ASV benchmarks
+Project-URL: Documentation, https://haozeke.github.io/asv_tachyon/
+Project-URL: Issues, https://github.com/HaoZeke/asv_tachyon/issues
+Project-URL: Source, https://github.com/HaoZeke/asv_tachyon
+Project-URL: Changelog, https://github.com/HaoZeke/asv_tachyon/blob/main/CHANGELOG.md
+Author-email: Rohit Goswami <rgoswami@ieee.org>
+Maintainer-email: Rohit Goswami <rgoswami@ieee.org>
+License: MIT
+License-File: LICENSE
+Keywords: asv,benchmark,flamegraph,profiling,python-3.15,sampling,tachyon
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Benchmark
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: asv-runner>=0.2.1
+Requires-Dist: asv>=0.6.4
+Requires-Dist: click>=8.1
+Provides-Extra: docs
+Requires-Dist: shibuya>=2024.1; extra == 'docs'
+Requires-Dist: sphinx-sitemap>=2.5; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Provides-Extra: rel
+Requires-Dist: build>=1.0; extra == 'rel'
+Requires-Dist: tbump>=6.11; extra == 'rel'
+Requires-Dist: towncrier>=23.6; extra == 'rel'
+Requires-Dist: twine>=5.0; extra == 'rel'
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+![asv-tachyon](./branding/logo/asv_tachyon_logo.png)
+
+# asv-tachyon
+
+[![CI](https://github.com/HaoZeke/asv_tachyon/actions/workflows/ci.yml/badge.svg)](https://github.com/HaoZeke/asv_tachyon/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/asv-tachyon.svg)](https://pypi.org/project/asv-tachyon/)
+[![Python](https://img.shields.io/pypi/pyversions/asv-tachyon.svg)](https://pypi.org/project/asv-tachyon/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Near-zero-overhead [Tachyon](https://docs.python.org/3.15/library/profiling.sampling.html) sampling profiles for [Airspeed Velocity](https://asv.readthedocs.io/) benchmarks.
+
+Python 3.15 ships `profiling.sampling` (code-named **Tachyon**): an external statistical sampler that reads a process's call stack from outside, so the benchmark runs at full speed. **asv-tachyon** wires that sampler into ASV projects — flame graphs, heatmaps, gecko/Firefox Profiler exports, binary captures you can replay and diff, and an `asv profile --gui=tachyon` hook.
+
+## Why
+
+ASV's built-in `asv profile` path still uses deterministic `cProfile`. That is exact, but expensive, and it distorts cheap functions. Tachyon samples from a sibling process, so:
+
+- long benchmarks and production-like workloads keep realistic timings
+- wall / CPU / GIL / exception **modes** separate waiting from working
+- `--all-threads` and `--async-aware` cover real concurrency
+- outputs include interactive flame graphs and line-level heatmaps
+
+## Install
+
+```bash
+pip install asv-tachyon
+# or
+uv pip install asv-tachyon
+```
+
+Sampling itself needs a *target* interpreter with Python >= 3.15 (the host CLI runs on 3.10+). Install the package into the same environment ASV uses for the benchmark, for example via the matrix:
+
+```json
+{
+  "matrix": {
+    "req": {
+      "pip+asv-tachyon": [""]
+    }
+  },
+  "plugins": ["asv_tachyon.plugin"]
+}
+```
+
+## Quick start
+
+From an ASV project root (with `asv.conf.json` and `benchmarks/`):
+
+```bash
+# Flame graph for one benchmark (parameterized names use ASV's -N suffix)
+asv-tachyon sample benchmarks.TimeSuite.time_keys-0 --browser
+
+# CPU-only, all threads, binary capture for later replay
+asv-tachyon sample benchmarks.TimeSuite.time_keys-0 \
+  --mode cpu --all-threads --format binary -o slow.tachyon.bin
+
+# Replay binary -> heatmap
+asv-tachyon replay slow.tachyon.bin --format heatmap -o heat --browser
+
+# Differential flame graph after a fix
+asv-tachyon sample benchmarks.TimeSuite.time_keys-0 \
+  --format diff-flamegraph --baseline slow.tachyon.bin -o diff.html --browser
+
+# Sanity-check the target interpreter
+asv-tachyon doctor --python "$(which python3.15)"
+```
+
+Point at a specific 3.15 environment:
+
+```bash
+asv-tachyon sample benchmarks.TimeSuite.time_keys-0 \
+  -E "existing:$(pwd)/.asv/env/venv-py3.15/bin/python"
+# or
+asv-tachyon sample benchmarks.TimeSuite.time_keys-0 \
+  --python /path/to/python3.15
+```
+
+## ASV plugin GUI
+
+With `"plugins": ["asv_tachyon.plugin"]` in `asv.conf.json`:
+
+```bash
+asv profile --gui=list          # shows tachyon / flamegraph
+asv profile --gui=tachyon PATH  # opens HTML flamegraph/heatmap artifacts
+```
+
+Note: `asv profile` still *collects* cProfile dumps. For sampling profiles, use `asv-tachyon sample`. The Tachyon GUI opens Tachyon HTML artifacts and points you at `asv-tachyon sample` when handed a cProfile file.
+
+## CLI reference (summary)
+
+| Command | Purpose |
+|---------|---------|
+| `asv-tachyon sample BENCH` | Run BENCH under Tachyon |
+| `asv-tachyon replay BIN` | Convert a binary capture |
+| `asv-tachyon open PATH` | Open HTML / heatmap dir |
+| `asv-tachyon doctor` | Check 3.15 + imports |
+| `asv-tachyon formats` | List output formats |
+
+Useful `sample` flags: `--format`, `--mode`, `-r/--rate`, `--duration`, `--loops`, `-a/--all-threads`, `--native`, `--async-aware`, `--live`, `--browser`, `--baseline` (for diff flame graphs).
+
+## Development
+
+```bash
+git clone https://github.com/HaoZeke/asv_tachyon
+cd asv_tachyon
+uv venv -p 3.12 .venv && source .venv/bin/activate
+uv pip install -e '.[test]'
+pytest -q
+```
+
+Rebuild the README from orgmode:
+
+```bash
+./scripts/org_to_md.sh readme_src.org README.md
+```
+
+## Name and logo
+
+**Tachyon** is CPython's code name for `profiling.sampling` — a nod to the hypothetical faster-than-light particle, matching the profiler's near-zero-overhead external sampling. The logo is a sampling strobe catching a speed-blurred swallow (ASV's mascot) mid-flight.
+
+## License
+
+MIT. See `LICENSE`.

asv_tachyon-0.1.0/README.md

@@ -0,0 +1,122 @@
+![asv-tachyon](./branding/logo/asv_tachyon_logo.png)
+
+# asv-tachyon
+
+[![CI](https://github.com/HaoZeke/asv_tachyon/actions/workflows/ci.yml/badge.svg)](https://github.com/HaoZeke/asv_tachyon/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/asv-tachyon.svg)](https://pypi.org/project/asv-tachyon/)
+[![Python](https://img.shields.io/pypi/pyversions/asv-tachyon.svg)](https://pypi.org/project/asv-tachyon/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Near-zero-overhead [Tachyon](https://docs.python.org/3.15/library/profiling.sampling.html) sampling profiles for [Airspeed Velocity](https://asv.readthedocs.io/) benchmarks.
+
+Python 3.15 ships `profiling.sampling` (code-named **Tachyon**): an external statistical sampler that reads a process's call stack from outside, so the benchmark runs at full speed. **asv-tachyon** wires that sampler into ASV projects — flame graphs, heatmaps, gecko/Firefox Profiler exports, binary captures you can replay and diff, and an `asv profile --gui=tachyon` hook.
+
+## Why
+
+ASV's built-in `asv profile` path still uses deterministic `cProfile`. That is exact, but expensive, and it distorts cheap functions. Tachyon samples from a sibling process, so:
+
+- long benchmarks and production-like workloads keep realistic timings
+- wall / CPU / GIL / exception **modes** separate waiting from working
+- `--all-threads` and `--async-aware` cover real concurrency
+- outputs include interactive flame graphs and line-level heatmaps
+
+## Install
+
+```bash
+pip install asv-tachyon
+# or
+uv pip install asv-tachyon
+```
+
+Sampling itself needs a *target* interpreter with Python >= 3.15 (the host CLI runs on 3.10+). Install the package into the same environment ASV uses for the benchmark, for example via the matrix:
+
+```json
+{
+  "matrix": {
+    "req": {
+      "pip+asv-tachyon": [""]
+    }
+  },
+  "plugins": ["asv_tachyon.plugin"]
+}
+```
+
+## Quick start
+
+From an ASV project root (with `asv.conf.json` and `benchmarks/`):
+
+```bash
+# Flame graph for one benchmark (parameterized names use ASV's -N suffix)
+asv-tachyon sample benchmarks.TimeSuite.time_keys-0 --browser
+
+# CPU-only, all threads, binary capture for later replay
+asv-tachyon sample benchmarks.TimeSuite.time_keys-0 \
+  --mode cpu --all-threads --format binary -o slow.tachyon.bin
+
+# Replay binary -> heatmap
+asv-tachyon replay slow.tachyon.bin --format heatmap -o heat --browser
+
+# Differential flame graph after a fix
+asv-tachyon sample benchmarks.TimeSuite.time_keys-0 \
+  --format diff-flamegraph --baseline slow.tachyon.bin -o diff.html --browser
+
+# Sanity-check the target interpreter
+asv-tachyon doctor --python "$(which python3.15)"
+```
+
+Point at a specific 3.15 environment:
+
+```bash
+asv-tachyon sample benchmarks.TimeSuite.time_keys-0 \
+  -E "existing:$(pwd)/.asv/env/venv-py3.15/bin/python"
+# or
+asv-tachyon sample benchmarks.TimeSuite.time_keys-0 \
+  --python /path/to/python3.15
+```
+
+## ASV plugin GUI
+
+With `"plugins": ["asv_tachyon.plugin"]` in `asv.conf.json`:
+
+```bash
+asv profile --gui=list          # shows tachyon / flamegraph
+asv profile --gui=tachyon PATH  # opens HTML flamegraph/heatmap artifacts
+```
+
+Note: `asv profile` still *collects* cProfile dumps. For sampling profiles, use `asv-tachyon sample`. The Tachyon GUI opens Tachyon HTML artifacts and points you at `asv-tachyon sample` when handed a cProfile file.
+
+## CLI reference (summary)
+
+| Command | Purpose |
+|---------|---------|
+| `asv-tachyon sample BENCH` | Run BENCH under Tachyon |
+| `asv-tachyon replay BIN` | Convert a binary capture |
+| `asv-tachyon open PATH` | Open HTML / heatmap dir |
+| `asv-tachyon doctor` | Check 3.15 + imports |
+| `asv-tachyon formats` | List output formats |
+
+Useful `sample` flags: `--format`, `--mode`, `-r/--rate`, `--duration`, `--loops`, `-a/--all-threads`, `--native`, `--async-aware`, `--live`, `--browser`, `--baseline` (for diff flame graphs).
+
+## Development
+
+```bash
+git clone https://github.com/HaoZeke/asv_tachyon
+cd asv_tachyon
+uv venv -p 3.12 .venv && source .venv/bin/activate
+uv pip install -e '.[test]'
+pytest -q
+```
+
+Rebuild the README from orgmode:
+
+```bash
+./scripts/org_to_md.sh readme_src.org README.md
+```
+
+## Name and logo
+
+**Tachyon** is CPython's code name for `profiling.sampling` — a nod to the hypothetical faster-than-light particle, matching the profiler's near-zero-overhead external sampling. The logo is a sampling strobe catching a speed-blurred swallow (ASV's mascot) mid-flight.
+
+## License
+
+MIT. See `LICENSE`.

asv_tachyon-0.1.0/changelog.d/1.feat.md

@@ -0,0 +1 @@
+Initial release: sample ASV benchmarks with Python 3.15 Tachyon (`profiling.sampling`), emit flame graphs / heatmaps / gecko / binary captures, and register an `asv profile --gui=tachyon` viewer.

asv_tachyon-0.1.0/changelog.d/readme.md

@@ -0,0 +1,3 @@
+# Changelog fragments
+
+Add a fragment named like `123.feat.md` before releasing.

asv_tachyon-0.1.0/docs/export.el

@@ -0,0 +1,25 @@
+;; Setup Package Manager (to fetch ox-rst automatically)
+(require 'package)
+(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
+(package-initialize)
+
+;; Ensure ox-rst is present
+(unless (package-installed-p 'ox-rst)
+  (package-refresh-contents)
+  (package-install 'ox-rst))
+
+(require 'ox-rst)
+(require 'ox-publish)
+
+;; Define the Publishing Project
+(setq org-publish-project-alist
+      '(("sphinx-rst"
+         :base-directory "./orgmode/"
+         :base-extension "org"
+         :publishing-directory "./source/"
+         :publishing-function org-rst-publish-to-rst
+         :recursive t
+         :headline-levels 4)))
+
+;; Run the publish
+(org-publish "sphinx-rst" t)

asv_tachyon-0.1.0/docs/orgmode/contributing/index.org

@@ -0,0 +1,13 @@
+#+TITLE: Contributing
+#+OPTIONS: toc:nil num:nil author:nil title:nil ^:nil
+
+* Contributing
+
+Issues and PRs welcome at https://github.com/HaoZeke/asv_tachyon.
+
+#+begin_src bash
+uv pip install -e '.[test]'
+pytest -q
+#+end_src
+
+Use Conventional Commits. Changelog fragments go in =changelog.d/=.

asv_tachyon-0.1.0/docs/orgmode/explanation/sampling_vs_tracing.org

@@ -0,0 +1,11 @@
+#+TITLE: Sampling vs tracing
+#+OPTIONS: toc:nil num:nil author:nil title:nil ^:nil
+
+* Sampling vs tracing
+
+Tracing profilers (=cProfile= / =profiling.tracing=) hook every call and return.
+They give exact counts but add high overhead.
+
+Sampling profilers (Tachyon) snapshot the stack on a timer from outside the
+process. They miss rare short functions and do not report call counts, but they
+leave the workload almost undisturbed---ideal for long ASV benchmarks.

asv_tachyon-0.1.0/docs/orgmode/howto/asv_plugin.org

@@ -0,0 +1,26 @@
+#+TITLE: Register the ASV plugin
+#+OPTIONS: toc:nil num:nil author:nil title:nil ^:nil
+
+* Register the ASV plugin
+
+Add to =asv.conf.json=:
+
+#+begin_src json
+{
+  "plugins": ["asv_tachyon.plugin"],
+  "matrix": {
+    "req": {
+      "pip+asv-tachyon": [""]
+    }
+  }
+}
+#+end_src
+
+Then:
+
+#+begin_src bash
+asv profile --gui=list
+#+end_src
+
+Use =asv-tachyon sample= to collect sampling profiles. Use
+=asv profile --gui=tachyon= only for opening Tachyon HTML artifacts.

asv_tachyon-0.1.0/docs/orgmode/howto/diff_flamegraph.org

@@ -0,0 +1,14 @@
+#+TITLE: Differential flame graphs
+#+OPTIONS: toc:nil num:nil author:nil title:nil ^:nil
+
+* Differential flame graphs
+
+#+begin_src bash
+asv-tachyon sample bench.time_x --format binary -o before.bin
+# ... apply a fix ...
+asv-tachyon sample bench.time_x \
+  --format diff-flamegraph --baseline before.bin -o diff.html --browser
+#+end_src
+
+Widths show the *current* run. Colors show change versus the baseline (blue =
+less self time share, red = more, purple = new frames).

asv_tachyon-0.1.0/docs/orgmode/index.org

@@ -0,0 +1,60 @@
+#+TITLE: asv-tachyon
+#+AUTHOR: [[https://rgoswami.me][Rohit Goswami]]
+#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil ^:nil
+
+#+begin_export rst
+===========================
+asv-tachyon
+===========================
+
+:Author: `Rohit Goswami <https://rgoswami.me>`_
+#+end_export
+
+Near-zero-overhead Tachyon sampling profiles for Airspeed Velocity benchmarks.
+
+Python 3.15's =profiling.sampling= module (Tachyon) samples call stacks from
+outside the target process. *asv-tachyon* runs ASV benchmarks under that
+sampler and turns the results into flame graphs, heatmaps, and more.
+
+* Install
+
+#+begin_src bash
+pip install asv-tachyon
+#+end_src
+
+Target environments need Python >= 3.15. The host CLI supports Python 3.10+.
+
+#+begin_export rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials
+
+   tutorials/first_sample
+
+.. toctree::
+   :maxdepth: 2
+   :caption: How-To Guides
+
+   howto/asv_plugin
+   howto/diff_flamegraph
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference
+
+   reference/cli
+   reference/formats
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Explanation
+
+   explanation/sampling_vs_tracing
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Development
+
+   contributing/index
+#+end_export