penkovsky_sa/cherrypick
1
0
Fork 0
mirror of https://github.com/pese-git/cherrypick.git synced 2026-01-24 13:47:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(benchmarks): update README files with stability options, repeat/warmup params, stat fields, and usage examples

Browse Source
This commit is contained in:
Sergey Penkovsky
2025-08-06 13:48:51 +03:00
parent 7f488f873e
commit 6928daa50e
2 changed files with 61 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
benchmark_cherrypick/README.md
View File

@@ -2,28 +2,23 @@
Benchmarks for the performance and features of the cherrypick (core) DI container. Benchmarks for the performance and features of the cherrypick (core) DI container.
All scenarios use only the public API (scope, module, binding, scoping, and async).
## Scenarios ## Scenarios
- **RegisterAndResolve**: Basic registration and resolution of a dependency. - **RegisterAndResolve**: Basic registration and resolution of a dependency.
- **ChainSingleton (A->B->C, singleton)**: Deep dependency chain, all as singletons. - **ChainSingleton** (A->B->C, singleton): Deep dependency chain, all as singletons.
- **ChainFactory (A->B->C, factory)**: Dependency chain with factory bindings (new instance per request). - **ChainFactory** (A->B->C, factory): Dependency chain with factory bindings (new instance per request).
- **NamedResolve (by name)**: Resolving a named dependency among several implementations. - **NamedResolve** (by name): Resolving a named dependency among several implementations.
- **AsyncChain (A->B->C, async)**: Asynchronous dependency chain. - **AsyncChain** (A->B->C, async): Asynchronous dependency chain.
- **ScopeOverride (child overrides parent)**: Overriding a dependency in a child scope over a parent. - **ScopeOverride** (child overrides parent): Overriding a dependency in a child scope over a parent.
## Features ## Features
- **Unified benchmark structure**: All test scenarios use a unified base mixin for setup/teardown. - **Unified benchmark structure**
- **Flexible CLI parameterization**: - **Flexible CLI parameterization (chain length, depth, repeats, warmup, scenario selection, format)**
Run benchmarks with custom parameters for chain length, depth, scenarios and formats. - **Automatic matrix/mass run for sets of parameters**
- **Matrix/mass run support**: - **Statistics: mean, median, stddev, min, max for each scenario**
Easily run benchmarks for all combinations of chainLength and depth in one run. - **Pretty-table, CSV, and JSON output**
- **Machine and human readable output**: - **Warmup runs before timing for better result stability**
Supports pretty-table, CSV, and JSON for downstream analytics or data storage.
- **Scenario selection**:
Run all or only specific benchmarks via CLI.
## How to run ## How to run
@@ -31,21 +26,21 @@ All scenarios use only the public API (scope, module, binding, scoping, and asyn
```shell ```shell
dart pub get dart pub get
``` ```
2. Run all benchmarks (with default parameters): 2. Run all benchmarks (defaults: single parameter set, repeat=5, warmup=2):
```shell ```shell
dart run bin/main.dart dart run bin/main.dart
``` ```
### Run with custom parameters ### Custom parameters
- Mass run in matrix mode (CSV output): - Matrix run (CSV, 7 repeats, 3 warmups):
```shell ```shell
dart run bin/main.dart --benchmark=chain_singleton --chainCount=10,100 --nestingDepth=5,10 --format=csv dart run bin/main.dart --benchmark=chain_singleton --chainCount=10,100 --nestingDepth=5,10 --repeat=7 --warmup=3 --format=csv
``` ```
- Run only the named resolve scenario: - Run only the named resolve scenario:
```shell ```shell
dart run bin/main.dart --benchmark=named dart run bin/main.dart --benchmark=named --repeat=3 --warmup=1
``` ```
- See available CLI flags: - See available CLI flags:
@@ -53,22 +48,21 @@ All scenarios use only the public API (scope, module, binding, scoping, and asyn
dart run bin/main.dart --help dart run bin/main.dart --help
``` ```
#### Available CLI options #### CLI options
- `--benchmark` (or `-b`) — Scenario to run: - `--benchmark` (`-b`) — Scenario:
`register`, `chain_singleton`, `chain_factory`, `named`, `override`, `async_chain`, `all` (default) `register`, `chain_singleton`, `chain_factory`, `named`, `override`, `async_chain`, `all` (default: all)
- `--chainCount` (or `-c`) — Comma-separated chain lengths. E.g. `10,100` - `--chainCount` (`-c`) — Comma-separated chain lengths. E.g. `10,100`
- `--nestingDepth` (or `-d`) — Comma-separated chain depths. E.g. `5,10` - `--nestingDepth` (`-d`) — Comma-separated chain depths. E.g. `5,10`
- `--format` (or `-f`) — Result output format: `pretty` (table), `csv`, `json` - `--repeat` (`-r`) — How many times to measure each scenario (`default: 5`)
- `--help` (or `-h`) — Print help - `--warmup` (`-w`) — How many warmup runs before actual timing (`default: 2`)
- `--format` (`-f`) — Output: `pretty`, `csv`, `json` (default: pretty)
- `--help` (`-h`) — Print help
#### Example output (`--format=csv`) #### Example output (`--format=csv`)
``` ```
benchmark,chainCount,nestingDepth,elapsed_us benchmark,chainCount,nestingDepth,mean_us,median_us,stddev_us,min_us,max_us,trials,timings_us
ChainSingleton,10,5,2450000 ChainSingleton,10,5,2450000,2440000,78000,2290000,2580000,5,"2440000;2460000;2450000;2580000;2290000"
ChainSingleton,10,10,2624000
ChainSingleton,100,5,2506300
ChainSingleton,100,10,2856900
``` ```
--- ---
@@ -81,7 +75,7 @@ ChainSingleton,100,10,2856900
--- ---
## Example for contributors ## Contributor example
```dart ```dart
class MyBenchmark extends BenchmarkBase with BenchmarkWithScope { class MyBenchmark extends BenchmarkBase with BenchmarkWithScope {

72
benchmark_cherrypick/README.ru.md
View File

@@ -2,28 +2,23 @@
Бенчмарки производительности и возможностей DI-контейнера cherrypick (core). Бенчмарки производительности и возможностей DI-контейнера cherrypick (core).
Все сценарии используют только публичное API (scope, module, binding, scoping, async).
## Сценарии ## Сценарии
- **RegisterAndResolve**: базовая регистрация и разрешение зависимости. - **RegisterAndResolve**: базовая регистрация и разрешение зависимости.
- **ChainSingleton (A->B->C, singleton)**: длинная цепочка зависимостей, все как singleton. - **ChainSingleton** (A->B->C, singleton): длинная цепочка зависимостей, все как singleton.
- **ChainFactory (A->B->C, factory)**: цепочка зависимостей через factory (новый объект на каждый запрос). - **ChainFactory** (A->B->C, factory): цепочка зависимостей через factory (новый объект на каждый запрос).
- **NamedResolve (by name)**: разрешение зависимости по имени среди нескольких реализаций. - **NamedResolve** (by name): разрешение зависимости по имени среди нескольких реализаций.
- **AsyncChain (A->B->C, async)**: асинхронная цепочка зависимостей. - **AsyncChain** (A->B->C, async): асинхронная цепочка зависимостей.
- **ScopeOverride (child overrides parent)**: перекрытие зависимости в дочернем scope относительно родителя. - **ScopeOverride** (child overrides parent): перекрытие зависимости в дочернем scope относительно родителя.
## Возможности ## Возможности
- **Унифицированная структура бенчмарков**: Все тесты используют единый миксин для setup/teardown (`BenchmarkWithScope`). - **Унифицированная структура бенчмарков**
- **Гибкая параметризация CLI**: - **Гибкая параметризация CLI (chainCount, nestingDepth, repeats, warmup, сценарий, формат)**
Любые комбинации параметров chainCount, nestingDepth, сценария и формата вывода. - **Автоматический матричный запуск для наборов параметров**
- **Массовый/матричный запуск**: - **Статистика: среднее, медиана, stddev, min, max для каждого сценария**
Перебор всех вариантов комбинаций chainCount и depth одной командой. - **Вывод в таблицу, CSV или JSON**
- **Машино- и человекочитаемый вывод**: - **Прогревочные запуски до замера времени для стабильности**
Поддержка pretty-таблицы, CSV, JSON — удобно для анализа результатов.
- **Выбор сценария**:
Запуск всех сценариев или только нужного через CLI.
## Как запустить ## Как запустить
@@ -31,53 +26,52 @@
```shell ```shell
dart pub get dart pub get
``` ```
2. Запустить все бенчмарки с параметрами по умолчанию: 2. Запустить все бенчмарки (по умолчанию: одни значения, repeat=5, warmup=2):
```shell ```shell
dart run bin/main.dart dart run bin/main.dart
``` ```
### Запуск с параметрами ### Пользовательские параметры
- Матричный прогон (csv-вывод): - Матричный прогон (csv, 7 повторов, 3 прогрева):
```shell ```shell
dart run bin/main.dart --benchmark=chain_singleton --chainCount=10,100 --nestingDepth=5,10 --format=csv dart run bin/main.dart --benchmark=chain_singleton --chainCount=10,100 --nestingDepth=5,10 --repeat=7 --warmup=3 --format=csv
``` ```
- Только сценарий разрешения по имени: - Только сценарий с именованным разрешением:
```shell ```shell
dart run bin/main.dart --benchmark=named dart run bin/main.dart --benchmark=named --repeat=3 --warmup=1
``` ```
- Справка по командам: - Посмотреть все флаги CLI:
```shell ```shell
dart run bin/main.dart --help dart run bin/main.dart --help
``` ```
#### CLI-флаги #### Опции CLI
- `--benchmark` (или `-b`) — Сценарий: - `--benchmark` (`-b`) — Сценарий:
`register`, `chain_singleton`, `chain_factory`, `named`, `override`, `async_chain`, `all` (по умолчанию) `register`, `chain_singleton`, `chain_factory`, `named`, `override`, `async_chain`, `all` (по умолчанию all)
- `--chainCount` (или `-c`) — Через запятую, несколько длин цепочек. Например: `10,100` - `--chainCount` (`-c`) — Длины цепочек через запятую. Напр: `10,100`
- `--nestingDepth` (или `-d`) — Через запятую, глубины цепочек. Например: `5,10` - `--nestingDepth` (`-d`) — Глубины цепочек через запятую. Напр: `5,10`
- `--format` (или `-f`) — Формат вывода: `pretty` (таблица), `csv`, `json` - `--repeat` (`-r`) — Сколько раз мерить каждую конфигурацию (`по умолчанию: 5`)
- `--help` (или `-h`) — Показать справку - `--warmup` (`-w`) — Сколько прогревочных запусков до замера времени (`по умолчанию: 2`)
- `--format` (`-f`) — Вывод: `pretty`, `csv`, `json` (по умолчанию pretty)
- `--help` (`-h`) — Показать справку
#### Пример вывода (`--format=csv`) #### Пример вывода (`--format=csv`)
``` ```
benchmark,chainCount,nestingDepth,elapsed_us benchmark,chainCount,nestingDepth,mean_us,median_us,stddev_us,min_us,max_us,trials,timings_us
ChainSingleton,10,5,2450000 ChainSingleton,10,5,2450000,2440000,78000,2290000,2580000,5,"2440000;2460000;2450000;2580000;2290000"
ChainSingleton,10,10,2624000
ChainSingleton,100,5,2506300
ChainSingleton,100,10,2856900
``` ```
--- ---
## Добавить свой бенчмарк ## Как добавить свой бенчмарк
1. Создайте Dart-файл с классом, наследующим BenchmarkBase или AsyncBenchmarkBase. 1. Создайте Dart-файл с классом, унаследованным от `BenchmarkBase` или `AsyncBenchmarkBase`.
2. Используйте миксин BenchmarkWithScope для автоматического управления Scope. 2. Используйте миксин `BenchmarkWithScope` для управления Scope (если нужно).
3. Добавьте его вызов в bin/main.dart для выбора через CLI. 3. Добавьте ваш бенчмарк в bin/main.dart для запуска через CLI.
--- ---