Обновлен README.ru.md: новые современные сценарии, параметры CLI, форматы отчётов, инструкция по расширению

2026-01-24 05:25:19 +00:00 · 2025-08-06 23:22:05 +03:00
parent 352442e52d
commit b72dec9944
1 changed files with 75 additions and 60 deletions
--- 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
   ```

-### Пользовательские параметры
-
- Матричный прогон (csv, 7 повторов, 3 прогрева):
-  ```shell
-  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 --repeat=3 --warmup=1
-  ```
-
- Посмотреть все флаги CLI:
+3. **Показать все CLI-параметры:**
   ```shell
   dart run bin/main.dart --help
   ```

-#### Опции CLI
+### 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`) — Показать справку
+- `--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` — Показать справку

-#### Пример вывода (`--format=csv`)
+### Примеры запуска
+
+- **Матричный запуск:**
+  ```shell
+  dart run bin/main.dart --benchmark=chainSingleton --chainCount=10,100 --nestingDepth=5,10 --repeat=5 --warmup=2 --format=markdown
  ```
-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
+
+- **Только сценарий с именованным разрешением:**
+  ```shell
+  dart run bin/main.dart --benchmark=named --repeat=3
  ```

+### Пример вывода (Markdown):
+
+```
+| 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<MyType>(); }
-  @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)

 ---