docs+feat: add Disposable interface source and usage example

feat(core,doc): unified async dispose mechanism for resource cleanup

BREAKING CHANGE:

- Added full support for asynchronous resource cleanup via a unified FutureOr<void> dispose() method in the Disposable interface.
- The Scope now provides only Future<void> dispose() for disposing all tracked resources and child scopes (sync-only dispose() was removed).
- All calls to cleanup in code and tests (scope itself, subscopes, and custom modules) now require await ...dispose().
- Documentation and all examples updated: resource management is always async and must be awaited; Disposable implementers may use both sync and async cleanup.
- Old-style, synchronous cleanup methods have been completely removed (API is now consistently async for all DI lifecycle management).
- Example and tutorial code now demonstrate async resource disposal patterns.
This commit is contained in:
Sergey Penkovsky
2025-08-01 15:07:12 +03:00
parent 61f2268d63
commit a9c95f6a89
14 changed files with 516 additions and 69 deletions

View File

@@ -75,8 +75,54 @@ Scope - это контейнер, который хранит все дерев
// или
final str = rootScope.tryResolve<String>();
// закрыть главный scope
Cherrypick.closeRootScope();
// Рекомендуется: закрывайте главный scope для автоматического освобождения всех ресурсов
await Cherrypick.closeRootScope();
// Или, для продвинутых/ручных сценариев:
// await rootScope.dispose();
```
### Автоматическое управление ресурсами (`Disposable`, `dispose`)
Если ваш сервис реализует интерфейс `Disposable`, CherryPick автоматически дождётся выполнения `dispose()` при закрытии scope.
**Рекомендация:**
Завершайте работу через `await Cherrypick.closeRootScope()` (для root scope) или `await scope.closeSubScope('feature')` (для подскоупов).
Эти методы автоматически await-ят `dispose()` для всех разрешённых через DI объектов, реализующих `Disposable`, обеспечивая корректную очистку (sync и async) и высвобождение ресурсов.
Вызывайте `await scope.dispose()` если вы явно управляете custom-скоупом.
#### Пример
```dart
class MyService implements Disposable {
@override
FutureOr<void> dispose() async {
// закрытие ресурса, соединений, таймеров и т.п., async/await
print('MyService disposed!');
}
}
final scope = openRootScope();
scope.installModules([
ModuleImpl(),
]);
final service = scope.resolve<MyService>();
// ... используем сервис ...
// Рекомендуемый финал:
await Cherrypick.closeRootScope(); // выведет в консоль 'MyService disposed!'
// Или для подскоупа:
await scope.closeSubScope('feature');
class ModuleImpl extends Module {
@override
void builder(Scope scope) {
bind<MyService>().toProvide(() => MyService()).singleton();
}
}
```
## Логирование