Efim Beshmenev
6.2 KiB
Universal Container
Экспериментальный C++20-контейнер индексируемой последовательности, который во время работы выбирает представление и его геометрию:
contiguous vector <-> segmented tiered storage
|
+-> leaf 64 / 128 / 256 / 512 / 1024
+-> минимально достаточная глубина каталога
Это не контейнер с одним «лучшим» размером блока. CostModelPolicy собирает
выборочную статистику чтений и полную статистику структурных изменений,
оценивает стоимость кандидатов и выдаёт AdaptationDecision: целевой режим и
TieredConfig. Переход выполняется, только если прогнозируемая экономия на
будущем горизонте превышает стоимость O(N)-перестройки с запасом.
Проект исследовательский. Сохранённые измерения показывают, что оптимальный
leaf действительно меняется с N, размером элемента и локальностью правок, но
пока не доказывают превосходство adaptive-варианта во всех или в среднем по
финальной holdout-матрице. Ограничения честно перечислены в
docs/findings.md.
std::deque и std::list присутствуют только как внешние benchmark-baselines.
Они не являются режимами контейнера: AdaptiveSequence переключается только
между contiguous vector и tiered storage.
Быстрый старт
Из обычной командной строки Windows:
build.bat baseline test
Доступные профили:
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.
Полный воспроизводимый запуск:
benchmark.bat smoke
benchmark.bat quick
benchmark.bat full
Для multi-core сравнения std::vector, пяти fixed-tiered geometry и adaptive
вплоть до 100 миллионов uint32_t:
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
#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:
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 и обновляет
индекс. Сам индекс не хранит логические позиции как ключи дубликатов.
Каталоги
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.