Repository navigation
feat(api): add cancellation, progress and async overloads for readers - #244
Conversation
Add NwcProgress and cancellation/progress overloads for NwcClashDetector.Run and NwcDocument.RunClashDetection. The detector checks the token in the outer mesh loop and periodically in the inner pair loop, and reports completed/total meshes. Existing synchronous overloads are unchanged. Async I/O and assembly/open overloads remain a follow-up.
Add cancellation/progress overloads for NwcDocument.Open (path and stream), NwcAssembly.LoadFromDirectory and OpenNwf. Report read-container, read-geometry, open and per-model load-models progress and check the token at phase boundaries and between models. Add OpenAsync, LoadFromDirectoryAsync, OpenNwfAsync and Save*Async wrappers for document exports. Add six cancellation/progress/async regression tests.
Код-ревью — feat(api): add cancellation, progress and async overloads for readers (стек на #236)Вердикт: approve-with-comments Резюме ревьюеров
Подтверждённые замечания (4)1. [СРЕДНЯЯ] Тесты отмены не проверяют заявленные точки проверки токена — Все тесты отмены используют токен, отменённый ДО вызова. Такой токен перехватывает самая первая проверка в NwcDocument.Open(string, ...) (строка 135 в NwcDocument.cs) или в Open(Stream, ...) (строка 160). Заявленные в PR проверки между моделями в LoadFromDirectory/OpenNwf, после чтения контейнера, перед геометрией и перед TimeLiner ни одним тестом не покрыты. OpenNwf_CanceledToken вообще пишет пустой файл и не отличает собственную проверку OpenNwf от проверки внутри Open. Прогресс для OpenNwf, отмена в OpenAsync/LoadFromDirectoryAsync/OpenNwfAsync и все Save*Async, кроме SaveJsonAsync, не тестируются. Единственный async-тест проверяет только File.Exists(json). Уточнение проверяющего: Тесты отмены используют только токен, отменённый до вызова, поэтому проверяют лишь первую проверку в NwcDocument.Open. Проверки между моделями в LoadFromDirectory/OpenNwf, после чтения контейнера, перед геометрией и в местах NwcDocument.cs:163, 182, 208, 242 не покрыты. Нет тестов отмены в процессе работы (например, из IProgress.Report), прогресса OpenNwf, отмены async-перегрузок и Save*Async. Это пробел в тестовом покрытии (medium), а не дефект поведения. Сценарий: Удалить все cancellationToken.ThrowIfCancellationRequested() из NwcAssembly.LoadFromDirectory и OpenNwf, а в NwcDocument.Open(Stream, ...) оставить только первую проверку (строка 160). LoadFromDirectory_CanceledToken_ThrowsOperationCanceled и OpenNwf_CanceledToken_ThrowsOperationCanceled останутся зелёными, потому что NwcDocument.Open(path, ...) сам бросает исключение на уже отменённом токене. Регрессия «отмена между моделями не работает» или «токен не доходит до Open» пройдёт CI незамеченной. Нет и теста, где отмена происходит посреди операции, например из IProgress.Report после первой модели. Исправление: Добавить тесты, где токен отменяется из callback прогресса: после первого load-models в папке из 2-3 файлов ожидать OperationCanceledException и ровно один отчёт; после read-container в Open. Для OpenNwf собрать .nwf с несколькими xref. Для async-перегрузок проверять Task.IsCanceled. Для OpenNwf и LoadFromDirectory дополнительно проверять порядок и значения Completed/Total. 2. [СРЕДНЯЯ] Тесты отмены используют заранее отменённый токен и не проверяют заявленные промежуточные точки проверки — Описание PR заявляет проверки токена "between models", после чтения контейнера, перед парсингом геометрии, перед парсингом TimeLiner и перед возвратом. Три теста отмены (Open, LoadFromDirectory, OpenNwf) создают токен с уже выставленной отменой. Они срабатывают на самой первой проверке (NwcDocument.cs:160, NwcAssembly.cs:188 и :224) и никогда не доходят до остальных. Промежуточные проверки (NwcDocument.cs:163, 182, 208, 242, 284, 299; NwcAssembly.cs:193, 241) ни одним тестом не затрагиваются. Для сравнения, #236 тестирует то же самое только pre-cancelled, так что механизма отмены посреди операции в наборе тестов нет вообще. Уточнение проверяющего: Тесты отмены проверяют только предотменённый токен и не защищают регрессионно проверки между моделями (NwcAssembly.cs:193, 241) и между фазами Open (NwcDocument.cs:163, 182, 208, 242, 284, 299). Это пробел в тестах, а не баг в продуктовом коде. Рекомендуется отменять токен из IProgress-колбэка, например на "read-container" для Open и на "load-models" 1/2 для LoadFromDirectory. Сценарий: Удаляем все ThrowIfCancellationRequested, кроме первого в Open(Stream), в LoadFromDirectory оставляем только проверку на строке 188 (перед циклом) и убираем проверки в цикле OpenNwf. Все три теста остаются зелёными, хотя пользователь, нажавший Cancel во время загрузки второй модели из папки, получит полную загрузку вместо OperationCanceledException. Заявленное поведение "между моделями" и "между фазами" не защищено регрессионно. Исправление: Отменять токен из IProgress-колбэка: на отчёте read-container для Open (и проверять, что отчёт open не пришёл), на отчёте load-models 1/2 для LoadFromDirectory (ожидать OCE и что вторая модель не открыта). 3. [НИЗКАЯ] Прогресс OpenNwf считает total по всем XRef, но отчитывается только о загруженных моделях — total = 1 + References.Count включает ссылки, которые затем пропускаются через continue без Report: нерезолвленные (unresolved), дубликаты по полному пути и файлы не .nwc/.nwd (skipped). Report вызывается только после успешной загрузки модели, поэтому Completed никогда не достигает Total, если хотя бы одна ссылка не загрузилась. Уточнение проверяющего: Прогресс OpenNwf объявляет total = 1 + число XRef, но Report вызывается только для реально загруженных моделей. При unresolved, дубликатах и пропущенных (не .nwc/.nwd) ссылках итоговый Completed остаётся меньше Total, и финального Report нет. Прогресс-бар не доходит до 100%, и завершение нельзя отличить от обрыва по одному только payload. Это неточность прогресса, а не функциональный сбой: результат сборки корректен, UnresolvedXRefs и SkippedXRefs заполняются. Сценарий: В .nwf три XRef: a.nwc существует, b.nwc отсутствует (unresolved), c.rvt (skipped). total = 4. Приходят отчёты (1,4) и (2,4), после чего метод возвращает сборку. Прогресс-бар остаётся на 50%, а код вида 'Completed == Total' не срабатывает. Из-за этого нельзя отличить завершение от обрыва. Ни одна ветка continue не увеличивает Completed. Исправление: Либо вызывать Report и в ветках unresolved/duplicate/skipped (увеличивая Completed), либо считать total только по ссылкам, которые будут загружены, либо отдавать финальный Report(n, n) перед возвратом. Независимо нашли также: tests-claims 4. [НИЗКАЯ] Все тесты отмены передают заранее отменённый токен и проходят на первой же проверке — Open_CanceledToken, LoadFromDirectory_CanceledToken и OpenNwf_CanceledToken вызывают Cancel() до старта. Выбрасывается самая первая проверка (NwcDocument.cs:160, NwcAssembly.cs:188 и 224). Заявленные в PR проверки между фазами и между моделями (NwcDocument.cs:163, 182, 208, 242, 284, 299; NwcAssembly.cs:193 и 241) не исполняются ни одним тестом. Если удалить любую из них, все шесть тестов останутся зелёными. Прогресс OpenNwf (включая ветки unresolved/skipped из предыдущего замечания) не покрыт вовсе. Из 16 Save*Async проверен один, SaveJsonAsync, и только через File.Exists, без чтения содержимого. Путь отмены через Task.Run (TaskCanceledException, Task.IsCanceled) тоже не проверен. Уточнение проверяющего: Тесты отмены используют только заранее отменённый токен, поэтому проверяют лишь первую проверку в каждом методе. Не покрыты: отмена между фазами NwcDocument.Open, отмена внутри цикла LoadFromDirectory и OpenNwf (через колбэк IProgress), прогресс OpenNwf с unresolved/skipped XRef, отмена через Task в Async и содержимое результата SaveAsync (проверен лишь File.Exists для SaveJsonAsync). Прогресс фаз Open и load-models для LoadFromDirectory покрыт отдельными тестами. Это пробел в тестах, а не функциональный дефект. Сценарий: Регрессия: из цикла LoadFromDirectory убрана cancellationToken.ThrowIfCancellationRequested() (NwcAssembly.cs:193), либо в OpenNwf нарушена нумерация progress. Токен, отменённый на второй модели, больше не прерывает загрузку, но CI остаётся зелёным. Тест OpenNwf_CanceledToken к тому же пишет в .nwf пустой файл и зависит только от проверки на строке 224. Нужны тесты с отменой изнутри IProgress.Report (например, отмена в отчёте первой модели) и тест OpenNwf с unresolved XRef. Исправление: Добавить тесты, где токен отменяется из колбэка IProgress после первой модели или фазы и проверяется, что вторая модель не загружается. Добавить тест OpenNwf с нерезолвленным XRef, сверяющий последовательность Completed/Total, и тест OpenAsync с отменой через Task. |
Drop the clash-detector cancellation from the closed #236 and the Save*Async wrappers of the frozen exporters; keep reader cancellation, progress and SaveAsync (.nwc). OpenNwf progress now counts every reference; OpenManifest gets the same token and progress overload; tests cancel mid-operation.
Completes the remaining #111 work: Open/assembly cancellation, progress and async I/O wrappers. Stacked on #236 (
fix/clash-cancellation), which addsNwcProgressand clash cancellation.What changed
NwcDocument.Openhas cancellation/progress overloads for paths and streams; existing signatures are unchanged.NwcAssembly.LoadFromDirectoryandNwcAssembly.OpenNwfhave cancellation/progress overloads; the reader checks the token between models and reportsload-modelscompleted/total.NwcDocument.Openchecks the token at the start, after the container read, before geometry parsing, before TimeLiner parsing and before returning. It reportsread-container,read-geometryandopenphases.OpenAsync,LoadFromDirectoryAsync,OpenNwfAsyncand documentSave*Asyncwrappers for JSON, OBJ, GLB, IFC, BCF viewpoints, XML viewpoints, HTML viewer and the raw.nwcsave..nwfopen, andOpenAsync+SaveJsonAsync.Files
src/NwcIO/NwcDocument.cssrc/NwcIO/Model/NwcAssembly.cstests/NwcIO.Tests/ReaderCancellationTests.csdocs/public-api.mdCHANGELOG.mdTests
dotnet build NwcIO.slnx -c Release— success, 0 warnings, 0 errors.dotnet test NwcIO.slnx -c Release --no-build— full suite passes (exit 0).ReaderCancellationTests: 6 passed.Remaining limitations
OpenAsync/Save*Asynccurrently wrap the synchronous implementation inTask.Run; file I/O itself is not yet truly asynchronous.NwcDocument; assembly BCF/clash/viewpoint exports have no async wrappers yet.