Stivo182 · Stivo182 · May 1, 2025 · May 1, 2025 · May 1, 2025 · May 1, 2025
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,17 @@
+# Документация
+
+## Темы
+- [Быстрый старт](БыстрыйСтарт.md)
+- [Запуск бенчмарков](ЗапускБенчмарков.md)
+- [Выбор стратегии запуска](ВыборСтратегииЗапуска.md)
+- [Параметризация](Параметризация.md)
+- [Эталоны](Эталоны.md)
+- [Мониторинг памяти](МониторингПамяти.md)
+- [Обработчики событий](ОбработчикиСобытий.md)
+- [Статистика](Статистика.md)
+- [Сортировка отчета](СортировкаОтчета.md)
+- [Аннотации](../src/BenchmarkOneScript/annotations/Классы)
+
+## Примеры
+- [Бенчмарки](../samples/benchmarks/Классы)
+- [API](../samples/api)
diff --git a/docs/БыстрыйСтарт.md b/docs/БыстрыйСтарт.md
@@ -0,0 +1,92 @@
+# Быстрый старт
+
+## 1. Установка
+
+```bash
+opm install benchmark
+```
+
+## 2. Создание бенчмарка
+
+Создайте класс с методами, помеченными аннотацией `&Бенчмарк`, где каждый метод реализует тестируемую логику. 
+В следующем примере мы сравниваем алгоритмы конкатенации строк через оператор `+` и метод `СтрСоединить`:
+
+```bsl
+// КонкатенацияСтрок.os
+
+&Параметры(100, 1000)
+Перем Количество Экспорт;
+Перем Подстрока;
+
+&МониторингПамяти
+Процедура ПриСозданииОбъекта()
+	Подстрока = "Просто текст";
+КонецПроцедуры
+
+&Бенчмарк
+&Эталон
+Процедура ОператорСложения() Экспорт
+	Текст = "";
+	Для НомерПодстроки = 1 По Количество Цикл
+		Текст = Текст + Подстрока;
+	КонецЦикла;
+КонецПроцедуры
+
+&Бенчмарк
+Процедура МассивПодстрок() Экспорт
+	МассивПодстрок = Новый Массив();
+	Для НомерПодстроки = 1 По Количество Цикл
+		МассивПодстрок.Добавить(Подстрока);
+	КонецЦикла;
+
+	Текст = СтрСоединить(МассивПодстрок);
+КонецПроцедуры
+```
+## 3. Запуск бенчмарков
+
+Запустите бенчмарки одним из следующих способов:
+
+**CLI:**
+
+```bash
+benchos run [FILE]
+```
+
+`FILE` - имя файла класса бенчмарков в текущем каталоге, либо полный путь к нему
+
+**API:**
+
+```bsl
+#Использовать benchmark
+#Использовать "."
+
+Результат = Бенчмаркинг.Запустить(Тип("КонкатенацияСтрок"));
+```
+
+## 4. Просмотр результатов
+
+После завершения тестов в консоли будет отображена подробная сводная таблица, оформленная в формате Markdown:
+
+```
+BenchmarkOneScript v0.1.0, OneScript v2.0.0.567-rc7-29039316, Microsoft Windows NT 10.0.20348.0 \
+Intel Core i7-8700 CPU 3.20GHz (Max: 3.19GHz) (Coffee Lake), 1 CPU, 12 logical and 6 physical cores
+
+| Method           | Количество | Baseline |       Mean |     StdErr |      StdDev |     Median | Ratio |     Op/s |   Allocated |
+|------------------|-----------:|----------|-----------:|-----------:|------------:|-----------:|------:|---------:|------------:|
+| МассивПодстрок   |        100 | false    |   75.44 us |   66.16 ns |    362.4 ns |   74.74 us | 1.624 | 13,256.1 |    17.77 KB |
+| ОператорСложения |        100 | true     |   46.51 us |   88.31 ns |    483.7 ns |   45.90 us |     1 | 21,499.5 |    126.5 KB |
+| МассивПодстрок   |      1,000 | false    |   686.0 us |   691.6 ns |  3,787.9 ns |   680.1 us | 0.505 |  1,457.8 |    165.4 KB |
+| ОператорСложения |      1,000 | true     | 1,365.8 us | 4,913.6 ns | 26,912.8 ns | 1,341.6 us |     1 |    732.1 | 11,809.0 KB |
+
+// Легенда
+Количество : Значение параметра 'Количество'
+Mean       : Арифметическое среднее всех измерений
+StdErr     : Стандартная ошибка всех измерений
+StdDev     : Стандартное отклонение всех измерений
+Ratio      : Среднее коэффициентов отношений ([Mean] / [Baseline Mean])
+Median     : Значение, разделяющее упорядоченные измерения на две равные части
+Op/s       : Операций в секунду
+Allocated  : Выделяемая память на одну операцию
+1 us       : 1 Микросекунда
+1 ns       : 1 Наносекунда
+```
diff --git a/docs/ВыборСтратегииЗапуска.md b/docs/ВыборСтратегииЗапуска.md
@@ -0,0 +1,94 @@
+# Выбор стратегии запуска
+
+## ПропускнаяСпособность
+
+Стратегия используется по умолчанию. Оптимальна для микробенчмаркинга. 
+Автоматическии подбирает количество вызовов за итерацию. Выполняет прогревочные итерации для стабилизации результатов.
+
+### Аннотация
+
+```bsl
+&СтратегияПропускнаяСпособность
+Процедура ПриСозданииОбъекта()
+```
+
+### API
+
+```bsl
+Конфигурация.УстановитьСтратегию(СтратегииЗапускаБенчмарка.ПропускнаяСпособность)
+```
+
+## ХолодныйЗапуск
+
+Стратегия для оценки производительности при первом запуске без предварительной оптимизации (Отключает оценочные и прогревочные итерации).
+
+### Аннотация
+
+```bsl
+&СтратегияХолодныйЗапуск
+Процедура ПриСозданииОбъекта()
+```
+
+### API
+
+```bsl
+Конфигурация.УстановитьСтратегию(СтратегииЗапускаБенчмарка.ХолодныйЗапуск)
+```
+
+### Пример
+
+```bsl
+Перем ЭтоПервыйВызов;
+
+&СтратегияХолодныйЗапуск
+&КоличествоИтераций(5)
+&КолонкаМин
+&КолонкаМакс
+Процедура ПриСозданииОбъекта()
+	ЭтоПервыйВызов = Истина;	
+КонецПроцедуры
+
+&Бенчмарк
+Процедура Бенчмарк() Экспорт
+
+	Если ЭтоПервыйВызов Тогда
+		ЭтоПервыйВызов = Ложь;
+		Приостановить(1000);
+	Иначе
+		Приостановить(10);
+	КонецЕсли;
+
+КонецПроцедуры
+```
+
+### Вывод
+
+```md
+// Бенчмарк: МойКласс.Бенчмарк
+
+Измерение  1 : 1 op, 1.001 s, 1.001 s/op
+Измерение  2 : 1 op, 10.34 ms, 10.34 ms/op
+Измерение  3 : 1 op, 10.48 ms, 10.48 ms/op
+Измерение  4 : 1 op, 10.19 ms, 10.19 ms/op
+Измерение  5 : 1 op, 10.67 ms, 10.67 ms/op
+
+// Сводка
+
+BenchmarkOneScript v0.1.0, OneScript v2.0.0.567-rc7-29039316, Microsoft Windows NT 10.0.20348.0 \
+Intel Core i7-8700 CPU 3.20GHz (Max: 3.19GHz) (Coffee Lake), 1 CPU, 12 logical and 6 physical cores
+
+| Method   |     Mean |   StdErr |   StdDev |      Min |   Median |     Max |  Op/s |
+|----------|---------:|---------:|---------:|---------:|---------:|--------:|------:|
+| Бенчмарк | 208.6 ms | 88.62 ms | 198.2 ms | 10.19 ms | 10.48 ms | 1.001 s | 4.794 |
+
+// Легенда
+Mean   : Арифметическое среднее всех измерений
+StdErr : Стандартная ошибка всех измерений
+StdDev : Стандартное отклонение всех измерений
+Min    : Минимум
+Median : Значение, разделяющее упорядоченные измерения на две равные части
+Max    : Максимум
+Op/s   : Операций в секунду
+1 ms   : 1 Миллисекунда
+1 s    : 1 Секунда
+```
diff --git a/docs/ЗапускБенчмарков.md b/docs/ЗапускБенчмарков.md
@@ -0,0 +1,62 @@
+# Запуск бенчмарков
+
+## CLI
+
+```bash
+benchos run [FILE]
+```
+
+`FILE` - имя файла класса бенчмарков в текущем каталоге, либо полный путь к нему
+
+**Примеры использования:**
+
+```bash
+# Запуск по имени класса (файл МойКласс.os должен существовать в текущей директории)
+benchos run МойКласс
+
+# Запуск по имени файла в текущей директории
+benchos run МойКласс.os
+
+# Запуск по абсолютному пути
+benchos run /path/to/МойКласс.os
+```
+
+## API
+
+### Базовый сценарий
+
+```bsl
+// Запуск по типу класса бенчмарков
+Результат = Бенчмаркинг.Запустить(Тип("МойКласс"));
+
+// Запуск через экземпляр класса бенчмарков
+Результат = Бенчмаркинг.Запустить(Новый МойКласс);
+```
+
+### Запуск отдельных бенчмарков
+
+```bsl
+ДескрипторыБенчмарков = Новый КоллекцияДескрипторовБенчмарков(Тип("МойКласс"));
+
+// Запуск конкретного бенчмарка
+ДескрипторБенчмарка = ДескрипторыБенчмарков.НайтиПоИмени("МойБенчмарк");
+Результат = Бенчмаркинг.Запустить(ДескрипторБенчмарка);
+
+// Запуск отфильтрованного списка
+ДескрипторыБенчмарков.Фильтровать("Элемент -> Элемент.Категория() = ""Б""");
+Результат = Бенчмаркинг.Запустить(ДескрипторыБенчмарков);
+```
+
+### Передача конфигурации
+
+```bsl
+// Создание новой конфигурации
+Конфигурация = Новый КонфигурацияБенчмарков();
+Конфигурация.УстановитьКоличествоИтераций(10);
+Результат = Бенчмаркинг.Запустить(Тип("МойКласс"), Конфигурация);
+
+// Модификация существующей конфигурации
+Конфигурация = Новый КонфигурацияБенчмарков(Тип("МойКласс"));
+Конфигурация.УстановитьКоличествоИтераций(10);
+Результат = Бенчмаркинг.Запустить(Тип("МойКласс"), Конфигурация);
+```
diff --git a/docs/МониторингПамяти.md b/docs/МониторингПамяти.md
@@ -0,0 +1,41 @@
+# Мониторинг памяти
+
+Для анализа аллокаций предусмотрена аннотация `&МониторингПамяти`.
+
+### Аннотация
+
+```bsl
+&МониторингПамяти
+Процедура ПриСозданииОбъекта()
+```
+
+### API
+
+```bsl
+Конфигурация.ДобавитьМониторингПамяти();
+```
+
+### Пример
+
+```bsl
+&МониторингПамяти
+Процедура ПриСозданииОбъекта()
+КонецПроцедуры
+
+&Бенчмарк
+&Параметры(100)
+&Параметры(1000)
+Процедура Бенчмарк(Количество) Экспорт
+	Строка = "";
+	Для к = 1 По Количество Цикл
+		Строка = Строка + "Просто текст";
+	КонецЦикла;
+КонецПроцедуры
+```
+
+### Вывод
+
+| Method   | Количество |       Mean |     StdErr |      StdDev |     Median |     Op/s |   Allocated |
+|----------|-----------:|-----------:|-----------:|------------:|-----------:|---------:|------------:|
+| Бенчмарк |        100 |   43.81 us |   97.74 ns |    535.4 ns |   42.87 us | 22,826.5 |    126.9 KB |
+| Бенчмарк |      1,000 | 1,298.2 us | 5,433.7 ns | 29,761.8 ns | 1,252.7 us |    770.3 | 11,809.4 KB |
diff --git a/docs/ОбработчикиСобытий.md b/docs/ОбработчикиСобытий.md
@@ -0,0 +1,69 @@
+# Обработчики событий
+
+Для изоляции логики подготовки и завершения от измеряемого кода в тестах производительности предусмотрен механизм обработчиков событий. 
+Используйте специальные аннотации, чтобы определить методы, которые будут выполняться в разных фазах жизненного цикла бенчмарков:
+
+#### &ПередВсеми
+Аннотация `&ПередВсеми` помечает метод, который выполняется **один раз** перед запуском всех бенчмарков. 
+Этот метод предназначен для глобальной подготовки данных, инициализации ресурсов (например, подключение к базе, загрузка файлов) или настройки окружения.
+
+#### &ПослеВсех
+Метод с аннотацией `&ПослеВсех` вызывается **после завершения всех бенчмарков**. 
+Он используется для финализации: освобождения ресурсов (закрытие соединений), записи итоговых отчетов или выполнения других действий.
+
+#### &ПередКаждым
+Аннотация `&ПередКаждым` указывает, что метод должен выполняться **перед каждым запуском бенчмарка**. 
+Это позволяет подготовить контекст для отдельного теста — например, сбросить состояние объекта, сгенерировать тестовые данные или выполнить предварительные проверки.
+
+#### &ПослеКаждого
+Метод с аннотацией `&ПослеКаждого` вызывается **после каждого выполнения бенчмарка**. 
+Он используется для постобработки: валидации результатов, сброса временных значений или освобождения ресурсов, которые создавались для конкретного теста.
+
+### API
+
+```bsl
+// Регистрация обработчика из произвольного объекта через делегат
+Конфигурация.ДобавитьОбработчикСобытия(
+	СобытияБенчмарков.ПередВсеми,
+	Новый Делегат(Объект, "Инициализация")
+);
+
+// Регистрация обработчика из класса бенчмарка
+Конфигурация.ДобавитьОбработчикСобытия
+	СобытияБенчмарков.ПослеВсех,
+	"Завершение"
+);
+
+// Удаление всех обработчиков для события
+Конфигурация.УдалитьОбработчикиСобытия(СобытияБенчмарков.ПередКаждым);
+```
+
+### Пример
+
+```bsl
+Перем ДвоичныеДанные;
+
+&ПередВсеми
+Процедура Инициализация(Контекст) Экспорт
+	ДвоичныеДанные = ПолучитьДвоичныеДанныеИзСтроки("Много данных");
+КонецПроцедуры
+
+&ПослеВсех
+Процедура Завершение(Контекст) Экспорт
+	ДвоичныеДанные = Неопределено;
+КонецПроцедуры
+
+&Бенчмарк
+Процедура SHA256() Экспорт
+	ХешированиеДанных = Новый ХешированиеДанных(ХешФункция.SHA256);
+	ХешированиеДанных.Добавить(ДвоичныеДанные);
+	ХешСумма = ХешированиеДанных.ХешСумма;
+КонецПроцедуры
+
+&Бенчмарк
+Процедура MD5() Экспорт
+	ХешированиеДанных = Новый ХешированиеДанных(ХешФункция.MD5);
+	ХешированиеДанных.Добавить(ДвоичныеДанные);
+	ХешСумма = ХешированиеДанных.ХешСумма;
+КонецПроцедуры
+```