diff --git a/benchmark_cherrypick/README.ru.md b/benchmark_cherrypick/README.ru.md index 9d48f0b..01c9b2f 100644 --- a/benchmark_cherrypick/README.ru.md +++ b/benchmark_cherrypick/README.ru.md @@ -1,102 +1,117 @@ # benchmark_cherrypick -Бенчмарки производительности и возможностей DI-контейнера cherrypick (core). +_Набор бенчмарков для анализа производительности и особенностей DI-контейнера cherrypick._ -## Сценарии +## Описание -- **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 относительно родителя. +Этот пакет предоставляет комплексные синтетические бенчмарки для DI-контейнера [cherrypick](https://github.com/). CLI-интерфейс позволяет запускать сценарии с разной глубиной, шириной, вариантами разрешения (singletons, factories, named, override, async), снимая статистику по времени и памяти, генерируя отчёты в различных форматах. -## Возможности +**Особенности:** +- Матричный запуск (chain count, nesting depth, сценарий, повторы) +- Гибкая настройка CLI +- Много форматов отчётов: таблица, CSV, JSON, Markdown +- Подсчет времени и памяти (mean, median, stddev, min, max, разница RSS/пик) +- Встроенные и легко расширяемые сценарии (singletons, factories, async, named, override) +- Механизм подключения других DI-контейнеров через адаптеры -- **Унифицированная структура бенчмарков** -- **Гибкая параметризация CLI (chainCount, nestingDepth, repeats, warmup, сценарий, формат)** -- **Автоматический матричный запуск для наборов параметров** -- **Статистика: среднее, медиана, stddev, min, max для каждого сценария** -- **Память: memory_diff_kb (итоговая разница), delta_peak_kb (максимальный рост), peak_rss_kb (абсолютный пик)** -- **Вывод в таблицу, CSV или JSON** -- **Прогревочные запуски до замера времени для стабильности** +--- + +## Сценарии бенчмарков + +- **RegisterSingleton**: Регистрация и разрешение singleton-зависимости +- **ChainSingleton**: Глубокая цепочка singleton-зависимостей (A→B→C...) +- **ChainFactory**: Цепочка с factory (новый объект при каждом разрешении) +- **AsyncChain**: Асинхронная цепочка зависимостей +- **Named**: Разрешение зависимости по имени среди нескольких реализаций +- **Override**: Разрешение зависимости, перекрытой в дочернем scope + +--- ## Как запустить -1. Установить зависимости: +1. **Установите зависимости:** ```shell dart pub get ``` -2. Запустить все бенчмарки (по умолчанию: одни значения, repeat=5, warmup=2): +2. **Запустите все бенчмарки (по умолчанию: одна комбинация, 2 прогрева, 2 повтора):** ```shell dart run bin/main.dart ``` -### Пользовательские параметры +3. **Показать все CLI-параметры:** + ```shell + dart run bin/main.dart --help + ``` -- Матричный прогон (csv, 7 повторов, 3 прогрева): +### CLI-параметры + +- `--benchmark, -b` — Сценарий: + `registerSingleton`, `chainSingleton`, `chainFactory`, `asyncChain`, `named`, `override`, `all` (по умолчанию: all) +- `--chainCount, -c` — Длины цепочек через запятую (`10,100`) +- `--nestingDepth, -d` — Глубины цепочек через запятую (`5,10`) +- `--repeat, -r` — Повторов на сценарий (по умолчанию 2) +- `--warmup, -w` — Прогревов до замера (по умолчанию 1) +- `--format, -f` — Формат отчёта: `pretty`, `csv`, `json`, `markdown` (по умолчанию pretty) +- `--help, -h` — Показать справку + +### Примеры запуска + +- **Матричный запуск:** ```shell - dart run bin/main.dart --benchmark=chain_singleton --chainCount=10,100 --nestingDepth=5,10 --repeat=7 --warmup=3 --format=csv + dart run bin/main.dart --benchmark=chainSingleton --chainCount=10,100 --nestingDepth=5,10 --repeat=5 --warmup=2 --format=markdown ``` -- Только сценарий с именованным разрешением: +- **Только сценарий с именованным разрешением:** ```shell - dart run bin/main.dart --benchmark=named --repeat=3 --warmup=1 + dart run bin/main.dart --benchmark=named --repeat=3 ``` -- Посмотреть все флаги CLI: - ```shell - dart run bin/main.dart --help - ``` +### Пример вывода (Markdown): -#### Опции CLI - -- `--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,mean_us,median_us,stddev_us,min_us,max_us,trials,timings_us,memory_diff_kb,delta_peak_kb,peak_rss_kb -ChainSingleton,10,5,2450000,2440000,78000,2290000,2580000,5,"2440000;2460000;2450000;2580000;2290000",-64,0,200064 +| Benchmark | Chain Count | Depth | Mean (us) | ... | PeakRSS(KB) | +|------------------|-------------|-------|-----------| ... |-------------| +| ChainSingleton | 10 | 5 | 2450000 | ... | 200064 | ``` --- +## Форматы отчёта + +- **pretty** — табличный человекочитаемый вывод +- **csv** — удобно для Excel и анализа скриптами +- **json** — для автотестов и аналитики +- **markdown** — Markdown-таблица (в Issues/Wiki) + +--- + ## Как добавить свой бенчмарк -1. Создайте Dart-файл с классом, унаследованным от `BenchmarkBase` или `AsyncBenchmarkBase`. -2. Используйте миксин `BenchmarkWithScope` для управления Scope (если нужно). -3. Добавьте ваш бенчмарк в bin/main.dart для запуска через CLI. - ---- - -## Пример для контрибуторов +1. Создайте класс на основе `BenchmarkBase` (для sync) или `AsyncBenchmarkBase` (для async) +2. Настройте DI через адаптер, создайте нужный модуль/сценарий +3. Добавьте новый случай в bin/main.dart для CLI +4. Для поддержки других DI-контейнеров реализуйте свой DIAdapter +Пример минимального бенчмарка: ```dart -class MyBenchmark extends BenchmarkBase with BenchmarkWithScope { +class MyBenchmark extends BenchmarkBase { MyBenchmark() : super('My custom'); - @override void setup() => setupScope([MyModule()]); - @override void run() { scope.resolve(); } - @override void teardown() => teardownScope(); + @override void setup() {/* настройка DI, создание цепочки */} + @override void run() {/* разрешение/запуск */} + @override void teardown() {/* очистка, если нужно */} } ``` --- -| Benchmark | Chain Count | Depth | Mean (us) | Median | Stddev | Min | Max | N | ΔRSS(KB) | ΔPeak(KB) | PeakRSS(KB) | -|---|---|---|---|---|---|---|---|---|---|---|---| -| RegisterSingleton | 10 | 5 | 24 | 45 | 22 | 2 | 45 | 2 | 0 | 0 | 199232 | -| ChainSingleton | 10 | 5 | 41 | 45 | 4 | 37 | 45 | 2 | 0 | 0 | 199296 | -| ChainFactory | 10 | 5 | 43 | 50 | 8 | 35 | 50 | 2 | 0 | 0 | 199296 | -| AsyncChain | 10 | 5 | 49 | 50 | 2 | 47 | 50 | 2 | 0 | 0 | 199344 | -| Named | 10 | 5 | 1 | 1 | 0 | 1 | 1 | 2 | 0 | 0 | 199344 | -| Override | 10 | 5 | 2 | 2 | 1 | 1 | 2 | 2 | 0 | 0 | 199360 | +## Метрики + +Бенчмарки собирают: +- **Время** (мкс): среднее, медиана, stddev, min, max, полный лист замеров +- **Память (RSS):** + - memory_diff_kb — итоговая разница RSS (KB) + - delta_peak_kb — разница пикового RSS (KB) + - peak_rss_kb — абсолютный пик (KB) ---