Efim Beshmenev
136 lines
6.2 KiB
Markdown
136 lines
6.2 KiB
Markdown
# Universal Container
|
|
|
|
Экспериментальный C++20-контейнер индексируемой последовательности, который во
|
|
время работы выбирает представление и его геометрию:
|
|
|
|
```text
|
|
contiguous vector <-> segmented tiered storage
|
|
|
|
|
+-> leaf 64 / 128 / 256 / 512 / 1024
|
|
+-> минимально достаточная глубина каталога
|
|
```
|
|
|
|
Это не контейнер с одним «лучшим» размером блока. `CostModelPolicy` собирает
|
|
выборочную статистику чтений и полную статистику структурных изменений,
|
|
оценивает стоимость кандидатов и выдаёт `AdaptationDecision`: целевой режим и
|
|
`TieredConfig`. Переход выполняется, только если прогнозируемая экономия на
|
|
будущем горизонте превышает стоимость O(N)-перестройки с запасом.
|
|
|
|
Проект исследовательский. Сохранённые измерения показывают, что оптимальный
|
|
leaf действительно меняется с `N`, размером элемента и локальностью правок, но
|
|
пока не доказывают превосходство adaptive-варианта во всех или в среднем по
|
|
финальной holdout-матрице. Ограничения честно перечислены в
|
|
[docs/findings.md](docs/findings.md).
|
|
|
|
`std::deque` и `std::list` присутствуют только как внешние benchmark-baselines.
|
|
Они не являются режимами контейнера: `AdaptiveSequence` переключается только
|
|
между contiguous vector и tiered storage.
|
|
|
|
## Быстрый старт
|
|
|
|
Из обычной командной строки Windows:
|
|
|
|
```bat
|
|
build.bat baseline test
|
|
```
|
|
|
|
Доступные профили:
|
|
|
|
```bat
|
|
build.bat scalar test
|
|
build.bat baseline test
|
|
build.bat avx2 test
|
|
build.bat all test
|
|
```
|
|
|
|
Проект проверен с Visual Studio 18 2026 и workload «Desktop development with
|
|
C++». `build.bat` сам находит комплектный CMake из Visual Studio. Готовые
|
|
программы находятся в
|
|
`out\bin\<profile>\Release\`:
|
|
|
|
- `uc_demo.exe` — минимальный пример;
|
|
- `uc_tests.exe` — differential/property-тесты;
|
|
- `uc_bench.exe` — benchmark runner.
|
|
|
|
Все Release-цели собираются с `/O2` и статическим MSVC runtime (`/MT`). Профиль
|
|
`scalar` — проверенный для MSVC 19.51 режим `project-novec`: внутренний ключ
|
|
`/d2Qvec-`, `/Oi-` и отключение vector algorithms STL. Это не универсальная
|
|
гарантия отсутствия SIMD внутри ABI/CRT. `baseline` оставляет штатную
|
|
автовекторизацию без AVX-флага, `avx2` добавляет `/arch:AVX2`. Перед запуском
|
|
AVX2-тестов и benchmark выполняется проверка CPU/OS; неподдерживаемый профиль
|
|
безопасно пропускается. Подробности приведены в
|
|
[docs/benchmarking.md](docs/benchmarking.md).
|
|
|
|
Полный воспроизводимый запуск:
|
|
|
|
```bat
|
|
benchmark.bat smoke
|
|
benchmark.bat quick
|
|
benchmark.bat full
|
|
```
|
|
|
|
Для multi-core сравнения `std::vector`, пяти fixed-tiered geometry и adaptive
|
|
вплоть до 100 миллионов `uint32_t`:
|
|
|
|
```bat
|
|
large_benchmark.bat smoke 12
|
|
large_benchmark.bat full 12 3
|
|
large_benchmark.bat full 12 3 huge
|
|
```
|
|
|
|
Третий аргумент ограничивает число одновременно работающих N=100M-ячеек;
|
|
значение 3 — эвристически более безопасный вариант для машины с 32 GiB RAM.
|
|
Четвёртый аргумент оставляет в матрице только N=100M.
|
|
|
|
Каждый запуск создаёт отдельную timestamp-папку в `results\benchmarks\`, куда
|
|
пишутся raw CSV, сводки и описание окружения. `out\` полностью игнорируется
|
|
Git, результаты исследования — намеренно нет.
|
|
|
|
## API
|
|
|
|
```cpp
|
|
#include <universal_container/adaptive_sequence.hpp>
|
|
|
|
uc::AdaptiveSequence<std::uint32_t> values;
|
|
values.push_back(10);
|
|
values.insert(0, 5);
|
|
values.erase(1);
|
|
auto x = values[0];
|
|
|
|
values.force_vector_mode();
|
|
values.force_tiered_mode({256, 64, 4});
|
|
values.enable_auto_mode();
|
|
values.adapt_now(); // явная безопасная maintenance point
|
|
```
|
|
|
|
Опциональный flat hash index со stable IDs:
|
|
|
|
```cpp
|
|
uc::AdaptiveSequence<std::uint32_t, true> indexed;
|
|
indexed.push_back(5);
|
|
indexed.push_back(5);
|
|
auto ids = indexed.find_all_ids(5);
|
|
indexed.erase_by_id(ids.front());
|
|
```
|
|
|
|
При включённом индексе запись через `operator[]` идёт через proxy и обновляет
|
|
индекс. Сам индекс не хранит логические позиции как ключи дубликатов.
|
|
|
|
## Каталоги
|
|
|
|
```text
|
|
include/universal_container/ публичные header-only компоненты
|
|
src/ demo и benchmark runner
|
|
tests/ correctness/differential tests
|
|
tools/ анализ CSV, аудит флагов, AVX2 probe и metadata
|
|
docs/ архитектура и выводы
|
|
results/benchmarks/ сохранённые результаты
|
|
out/build/ промежуточная сборка (ignored)
|
|
out/bin/ exe по профилям (ignored)
|
|
out/lib/ библиотеки (ignored)
|
|
out/symbols/ PDB по профилям (ignored)
|
|
```
|
|
|
|
Архитектура и контракт инвалидирования описаны в
|
|
[docs/architecture.md](docs/architecture.md).
|