# _bench

URL: /pounce/api/_bench/
Section: api
Description: Standardized performance benchmarks for pounce.

Spawns a pounce server with built-in ASGI apps and drives load using
``http.client`` from multiple threads.  Reports throughput, latency
percentiles, and memory usage.

---

> For a complete page index, fetch /pounce/llms.txt.

Open LLM text
(/pounce/api/_bench/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_bench%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_bench%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_bench%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_bench%2Findex.txt)

Module

#
`_bench`

Standardized performance benchmarks for pounce.

Spawns a pounce server with built-in ASGI apps and drives load using
`http.client`from multiple threads. Reports throughput, latency
percentiles, and memory usage.

2Classes9Functions

## Classes

`WorkloadResult`

10

▼

Results from a single workload run.

Results from a single workload run.

#### Attributes

Name
Type
Description

`name`

`str`

—

`total_requests`

`int`

—

`errors`

`int`

—

`duration_s`

`float`

—

`latencies_ms`

`list[float]`

—

`rss_mb`

`float`

—

#### Methods

`rps`

0

`float`

▼

property

`def rps(self) -> float`

##### Returns

`float`

`p50`

0

`float`

▼

property

`def p50(self) -> float`

##### Returns

`float`

`p95`

0

`float`

▼

property

`def p95(self) -> float`

##### Returns

`float`

`p99`

0

`float`

▼

property

`def p99(self) -> float`

##### Returns

`float`

`BenchSuite`

5

▼

Results from a complete benchmark suite.

Results from a complete benchmark suite.

#### Attributes

Name
Type
Description

`label`

`str`

—

`workers`

`int`

—

`connections`

`int`

—

`duration`

`int`

—

`workloads`

`list[WorkloadResult (/pounce/api/_bench/#WorkloadResult)]`

—

## Functions

`_find_free_port`

0

`int`

▼

Find an available TCP port.

`def _find_free_port() -> int`

##### Returns

`int`

`_get_rss_mb`

1

`float`

▼

Get resident set size in MB for a process.

Tries platform-specific approaches …

`def _get_rss_mb(pid: int) -> float`

Get resident set size in MB for a process.

Tries platform-specific approaches in order:

- /proc/{pid}/status (Linux)

- ps command (macOS / BSD)

##### Parameters

Name
Type
Description

`pid`
`int`

##### Returns

`float`

`_wait_for_server`

3

`bool`

▼

Wait until a server is accepting connections.

`def _wait_for_server(host: str, port: int, timeout: float = 10.0) -> bool`

##### Parameters

Name
Type
Description

`host`
`str`

`port`
`int`

`timeout`
`float`

Default:`10.0`

##### Returns

`bool`

`_write_bench_app`

1

`None`

▼

Write the benchmark ASGI app to a temporary file.

`def _write_bench_app(path: str) -> None`

##### Parameters

Name
Type
Description

`path`
`str`

`_emit`

1

`None`

▼

Write a benchmark progress message to stderr.

`def _emit(msg: str) -> None`

##### Parameters

Name
Type
Description

`msg`
`str`

`_drive_load`

7

`tuple[int, int, list[flo…`

▼

Drive HTTP load from multiple threads.

Returns (total_requests, errors, latenc…

`def _drive_load(host: str, port: int, path: str, method: str, body: bytes | None, duration: float, connections: int) -> tuple[int, int, list[float]]`

Drive HTTP load from multiple threads.

Returns (total_requests, errors, latencies_ms).

##### Parameters

Name
Type
Description

`host`
`str`

`port`
`int`

`path`
`str`

`method`
`str`

`body`
`bytes | None`

`duration`
`float`

`connections`
`int`

##### Returns

`tuple[int, int, list[float]]`

`_run_bench`

6

`BenchSuite (/pounce/api/_bench/#BenchSuite)`

▼

Run a full benchmark suite against a server command.

Starts the server, runs e…

`def _run_bench(server_cmd: list[str], label: str, duration: int, connections: int, host: str, port: int) -> BenchSuite`

Run a full benchmark suite against a server command.

Starts the server, runs each workload, collects results, and stops
the server.

##### Parameters

Name
Type
Description

`server_cmd`
`list[str]`

`label`
`str`

`duration`
`int`

`connections`
`int`

`host`
`str`

`port`
`int`

##### Returns

`BenchSuite (/pounce/api/_bench/#BenchSuite)`

`_format_results`

1

`str`

▼

Render benchmark results as a plain text table.

`def _format_results(suites: list[BenchSuite]) -> str`

##### Parameters

Name
Type
Description

`suites`
`list[BenchSuite (/pounce/api/_bench/#BenchSuite)]`

##### Returns

`str`

`register_bench_command`

1

`None`

▼

Register the ``bench`` subcommand on the CLI.

`def register_bench_command(cli: Any) -> None`

##### Parameters

Name
Type
Description

`cli`
`Any`