diff --git a/benchmark_cherrypick/README.md b/benchmark_cherrypick/README.md index 74ace69..140e659 100644 --- a/benchmark_cherrypick/README.md +++ b/benchmark_cherrypick/README.md @@ -2,28 +2,23 @@ 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 - **RegisterAndResolve**: Basic registration and resolution of a dependency. -- **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). -- **NamedResolve (by name)**: Resolving a named dependency among several implementations. -- **AsyncChain (A->B->C, async)**: Asynchronous dependency chain. -- **ScopeOverride (child overrides parent)**: Overriding a dependency in a child scope over a parent. +- **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). +- **NamedResolve** (by name): Resolving a named dependency among several implementations. +- **AsyncChain** (A->B->C, async): Asynchronous dependency chain. +- **ScopeOverride** (child overrides parent): Overriding a dependency in a child scope over a parent. ## Features -- **Unified benchmark structure**: All test scenarios use a unified base mixin for setup/teardown. -- **Flexible CLI parameterization**: - Run benchmarks with custom parameters for chain length, depth, scenarios and formats. -- **Matrix/mass run support**: - Easily run benchmarks for all combinations of chainLength and depth in one run. -- **Machine and human readable output**: - Supports pretty-table, CSV, and JSON for downstream analytics or data storage. -- **Scenario selection**: - Run all or only specific benchmarks via CLI. +- **Unified benchmark structure** +- **Flexible CLI parameterization (chain length, depth, repeats, warmup, scenario selection, format)** +- **Automatic matrix/mass run for sets of parameters** +- **Statistics: mean, median, stddev, min, max for each scenario** +- **Pretty-table, CSV, and JSON output** +- **Warmup runs before timing for better result stability** ## How to run @@ -31,21 +26,21 @@ All scenarios use only the public API (scope, module, binding, scoping, and asyn ```shell dart pub get ``` -2. Run all benchmarks (with default parameters): +2. Run all benchmarks (defaults: single parameter set, repeat=5, warmup=2): ```shell 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 - 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: ```shell - dart run bin/main.dart --benchmark=named + dart run bin/main.dart --benchmark=named --repeat=3 --warmup=1 ``` - 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 ``` -#### Available CLI options +#### CLI options -- `--benchmark` (or `-b`) — Scenario to run: - `register`, `chain_singleton`, `chain_factory`, `named`, `override`, `async_chain`, `all` (default) -- `--chainCount` (or `-c`) — Comma-separated chain lengths. E.g. `10,100` -- `--nestingDepth` (or `-d`) — Comma-separated chain depths. E.g. `5,10` -- `--format` (or `-f`) — Result output format: `pretty` (table), `csv`, `json` -- `--help` (or `-h`) — Print help +- `--benchmark` (`-b`) — Scenario: + `register`, `chain_singleton`, `chain_factory`, `named`, `override`, `async_chain`, `all` (default: all) +- `--chainCount` (`-c`) — Comma-separated chain lengths. E.g. `10,100` +- `--nestingDepth` (`-d`) — Comma-separated chain depths. E.g. `5,10` +- `--repeat` (`-r`) — How many times to measure each scenario (`default: 5`) +- `--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`) ``` -benchmark,chainCount,nestingDepth,elapsed_us -ChainSingleton,10,5,2450000 -ChainSingleton,10,10,2624000 -ChainSingleton,100,5,2506300 -ChainSingleton,100,10,2856900 +benchmark,chainCount,nestingDepth,mean_us,median_us,stddev_us,min_us,max_us,trials,timings_us +ChainSingleton,10,5,2450000,2440000,78000,2290000,2580000,5,"2440000;2460000;2450000;2580000;2290000" ``` --- @@ -81,7 +75,7 @@ ChainSingleton,100,10,2856900 --- -## Example for contributors +## Contributor example ```dart class MyBenchmark extends BenchmarkBase with BenchmarkWithScope { diff --git a/benchmark_cherrypick/README.ru.md b/benchmark_cherrypick/README.ru.md index 37a5690..4b04c7c 100644 --- a/benchmark_cherrypick/README.ru.md +++ b/benchmark_cherrypick/README.ru.md @@ -2,28 +2,23 @@ Бенчмарки производительности и возможностей DI-контейнера cherrypick (core). -Все сценарии используют только публичное API (scope, module, binding, scoping, async). - ## Сценарии - **RegisterAndResolve**: базовая регистрация и разрешение зависимости. -- **ChainSingleton (A->B->C, singleton)**: длинная цепочка зависимостей, все как singleton. -- **ChainFactory (A->B->C, factory)**: цепочка зависимостей через factory (новый объект на каждый запрос). -- **NamedResolve (by name)**: разрешение зависимости по имени среди нескольких реализаций. -- **AsyncChain (A->B->C, async)**: асинхронная цепочка зависимостей. -- **ScopeOverride (child overrides parent)**: перекрытие зависимости в дочернем scope относительно родителя. +- **ChainSingleton** (A->B->C, singleton): длинная цепочка зависимостей, все как singleton. +- **ChainFactory** (A->B->C, factory): цепочка зависимостей через factory (новый объект на каждый запрос). +- **NamedResolve** (by name): разрешение зависимости по имени среди нескольких реализаций. +- **AsyncChain** (A->B->C, async): асинхронная цепочка зависимостей. +- **ScopeOverride** (child overrides parent): перекрытие зависимости в дочернем scope относительно родителя. ## Возможности -- **Унифицированная структура бенчмарков**: Все тесты используют единый миксин для setup/teardown (`BenchmarkWithScope`). -- **Гибкая параметризация CLI**: - Любые комбинации параметров chainCount, nestingDepth, сценария и формата вывода. -- **Массовый/матричный запуск**: - Перебор всех вариантов комбинаций chainCount и depth одной командой. -- **Машино- и человекочитаемый вывод**: - Поддержка pretty-таблицы, CSV, JSON — удобно для анализа результатов. -- **Выбор сценария**: - Запуск всех сценариев или только нужного через CLI. +- **Унифицированная структура бенчмарков** +- **Гибкая параметризация CLI (chainCount, nestingDepth, repeats, warmup, сценарий, формат)** +- **Автоматический матричный запуск для наборов параметров** +- **Статистика: среднее, медиана, stddev, min, max для каждого сценария** +- **Вывод в таблицу, CSV или JSON** +- **Прогревочные запуски до замера времени для стабильности** ## Как запустить @@ -31,53 +26,52 @@ ```shell dart pub get ``` -2. Запустить все бенчмарки с параметрами по умолчанию: +2. Запустить все бенчмарки (по умолчанию: одни значения, repeat=5, warmup=2): ```shell dart run bin/main.dart ``` -### Запуск с параметрами +### Пользовательские параметры -- Матричный прогон (csv-вывод): +- Матричный прогон (csv, 7 повторов, 3 прогрева): ```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 - dart run bin/main.dart --benchmark=named + dart run bin/main.dart --benchmark=named --repeat=3 --warmup=1 ``` -- Справка по командам: +- Посмотреть все флаги CLI: ```shell dart run bin/main.dart --help ``` -#### CLI-флаги +#### Опции CLI -- `--benchmark` (или `-b`) — Сценарий: - `register`, `chain_singleton`, `chain_factory`, `named`, `override`, `async_chain`, `all` (по умолчанию) -- `--chainCount` (или `-c`) — Через запятую, несколько длин цепочек. Например: `10,100` -- `--nestingDepth` (или `-d`) — Через запятую, глубины цепочек. Например: `5,10` -- `--format` (или `-f`) — Формат вывода: `pretty` (таблица), `csv`, `json` -- `--help` (или `-h`) — Показать справку +- `--benchmark` (`-b`) — Сценарий: + `register`, `chain_singleton`, `chain_factory`, `named`, `override`, `async_chain`, `all` (по умолчанию all) +- `--chainCount` (`-c`) — Длины цепочек через запятую. Напр: `10,100` +- `--nestingDepth` (`-d`) — Глубины цепочек через запятую. Напр: `5,10` +- `--repeat` (`-r`) — Сколько раз мерить каждую конфигурацию (`по умолчанию: 5`) +- `--warmup` (`-w`) — Сколько прогревочных запусков до замера времени (`по умолчанию: 2`) +- `--format` (`-f`) — Вывод: `pretty`, `csv`, `json` (по умолчанию pretty) +- `--help` (`-h`) — Показать справку #### Пример вывода (`--format=csv`) ``` -benchmark,chainCount,nestingDepth,elapsed_us -ChainSingleton,10,5,2450000 -ChainSingleton,10,10,2624000 -ChainSingleton,100,5,2506300 -ChainSingleton,100,10,2856900 +benchmark,chainCount,nestingDepth,mean_us,median_us,stddev_us,min_us,max_us,trials,timings_us +ChainSingleton,10,5,2450000,2440000,78000,2290000,2580000,5,"2440000;2460000;2450000;2580000;2290000" ``` --- -## Добавить свой бенчмарк +## Как добавить свой бенчмарк -1. Создайте Dart-файл с классом, наследующим BenchmarkBase или AsyncBenchmarkBase. -2. Используйте миксин BenchmarkWithScope для автоматического управления Scope. -3. Добавьте его вызов в bin/main.dart для выбора через CLI. +1. Создайте Dart-файл с классом, унаследованным от `BenchmarkBase` или `AsyncBenchmarkBase`. +2. Используйте миксин `BenchmarkWithScope` для управления Scope (если нужно). +3. Добавьте ваш бенчмарк в bin/main.dart для запуска через CLI. ---