Benchmarks
==========

async-cache ships a benchmark suite in ``benchmarks/run.py`` that measures
real-world performance characteristics.

Running Benchmarks
------------------

.. code-block:: bash

    # Default (10,000 iterations)
    python benchmarks/run.py

    # Custom iterations
    python benchmarks/run.py --iterations 50000

    # Also write JSON results
    python benchmarks/run.py --json results.json

What Is Measured
----------------

1. **Hit vs Miss Latency** — per-operation latency for cache hits and misses
2. **Thundering Herd** — 100 coroutines racing on 1 key; verifies only 1 loader fires
3. **Batch DataLoader** — throughput of batch_loader mode (keys/sec)
4. **Competitor Comparison** — side-by-side with ``aiocache.SimpleMemoryCache`` and
   ``cachetools.LRUCache`` (sync baseline)

Sample Results
--------------

*Python 3.12, 10,000 iterations, Linux*

Hit vs Miss Latency
~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 30 35 35

   * - Metric
     - Hit
     - Miss
   * - Median latency
     - ~0.8µs
     - ~3.2µs
   * - p99 latency
     - ~2.8µs
     - ~11µs
   * - Throughput
     - >1M ops/s
     - >300K ops/s

Thundering Herd Protection
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1

   * - Metric
     - Value
   * - Coroutines per round
     - 100
   * - Loader calls per round
     - **1.0** (verified)
   * - Round time
     - ~600µs

Batch DataLoader
~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1

   * - Metric
     - Value
   * - Keys per batch
     - 200
   * - Throughput
     - ~60K keys/s

Competitor Comparison
~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1

   * - Library
     - Avg Hit Latency
     - Notes
   * - **async-cache**
     - ~0.8µs
     - async-native, thundering herd, batching
   * - aiocache
     - varies
     - Install ``aiocache`` to compare
   * - cachetools (sync)
     - varies
     - Sync-only, no herd/batch protection

To include competitor results, install the optional packages:

.. code-block:: bash

    pip install aiocache cachetools
    python benchmarks/run.py