raii library

Core library providing RAII (Resource Acquisition Is Initialization) pattern implementation for Dart/Flutter applications.

This library provides a foundation for managing object lifecycles through a systematic approach to resource initialization and cleanup. It implements the RAII pattern, ensuring that resources are properly managed throughout their lifetime.

The library follows these core principles:

  • Explicit lifecycle management through clear interfaces
  • Hierarchical resource management where parent objects manage their children
  • Automatic cleanup of resources when they're no longer needed
  • LIFO disposal order (last registered, first disposed)

Basic usage:

// Create a lifecycle container
final raiiManager = RaiiManager()..initLifecycle();

// Wrap a resource that needs lifecycle management
final resource = RaiiBox.withLifecycle(
  raiiManager,
  instance: MyResource(),
  init: (r) => r.initialize(),
  dispose: (r) => r.cleanup(),
  debugLabel: 'MyResource',
);

// When done, dispose the `raiiManager` to cleanup all managed resources
raiiManager.disposeLifecycle();

For long-lived resources that should exist for the entire application lifetime, use alwaysAliveRaiiManager:

final globalResource = RaiiBox.withLifecycle(
  alwaysAliveRaiiManager,
  instance: MyGlobalResource(),
  debugLabel: 'GlobalResource',
);

This library serves as the foundation for more specific lifecycle management implementations in Flutter widgets, controllers, and other disposable resources. It provides the core abstractions that other libraries build upon to provide type-safe, automatic resource management.

Classes

RaiiBox<T>
A container class that wraps an instance with lifecycle management capabilities.
RaiiDisposeable
Helper class for managing simple disposable resources.
RaiiLifecycle
Defines the interface for objects that have a lifecycle.
RaiiLifecycleAware
An interface for objects that can manage the lifecycle of other RaiiLifecycle objects.
RaiiLifecycleHolderTracker
Interface for lifecycle objects that track their parent holder.
RaiiManager
A concrete implementation of RaiiLifecycleAware that can manage multiple lifecycles.

Mixins

RaiiLifecycleHolderTrackerMixin
Mixin implementation of RaiiLifecycleHolderTracker.
RaiiLifecycleMixin
A mixin that implements the RaiiLifecycle interface with basic lifecycle state tracking.
RaiiManagerMixin
A mixin that implements the RaiiLifecycleAware interface with support for managing multiple lifecycle objects.

Properties

alwaysAliveRaiiManager → _AlwaysAliveRaiiManager
A globally accessible RaiiManager that never gets disposed.
final

Exceptions / Errors

AlreadyDisposedException
Exception thrown when attempting to dispose an already disposed lifecycle.
AlreadyInitializedException
Exception thrown when attempting to initialize an already initialized lifecycle.
DisposalFailedException
Exception thrown when a lifecycle operation fails during disposal.
ManagerDisposedException
Exception thrown when attempting to register a lifecycle with a disposed manager.
NotInitializedException
Exception thrown when attempting to dispose a lifecycle that was never initialized.
RaiiLifecycleException
Base exception for all RAII lifecycle-related errors.