dart-lifecycle-disposed-flag-overload

Dart Lifecycle _disposed Flag Overload

Problem

A Dart/Flutter class with start/stop lifecycle methods sets a "disposed"/"stopped" boolean inside stop(), but the guard clause in start() short-circuits whenever that boolean is true. After a stop→start cycle, start() silently returns without doing anything. The class has two distinct concerns conflated into one flag:

1. "This instance is permanently torn down" (e.g. user switched accounts, object is being discarded) — should prevent any further work.
2. "Currently not listening, but could be re-started" (e.g. user navigated away from the inbox screen and may come back) — must allow future start() calls.

When those concerns share a single flag, the second concern silently breaks the first.

Context / Trigger Conditions

• A class (repository, service, controller, bloc, cubit, notifier) has methods like:
  • startListening() / stopListening()
  • subscribe() / unsubscribe()
  • connect() / disconnect()
  • open() / close()
• stop() includes a line like _disposed = true; or _stopped = true;
• start() begins with a guard like:

  if (_subscription != null || _disposed || !isInitialized) return;
  

• Symptom: the feature works on first open, breaks on every subsequent open
• Unit tests that mock the dependencies pass because they only exercise one cycle OR because the mock doesn't model the real instance's internal state
• Manual QA finds that leaving and returning to a screen breaks the feature silently (no error thrown, no log emitted, no visible indication)

Solution

Separate the two concerns. Reserve the permanent-teardown flag for the code path that actually tears the instance down for good (typically a _resetState() called on user-switch or full logout), and do NOT set it inside stop().

Before (broken)

class MyRepository {
  bool _disposed = false;
  StreamSubscription<Event>? _subscription;

  void startListening() {
    if (_subscription != null || _disposed || !isInitialized) return;
    _subscription = _client.subscribe(...).listen(...);
  }

  Future<void> stopListening() async {
    _disposed = true;                    // ← THE BUG
    await _subscription?.cancel();
    _subscription = null;
  }

  void _resetState() {
    _disposed = true;
    // ... wipe credentials ...
    _disposed = false;
  }
}

After stopListening(), _disposed == true forever until _resetState() is called (which only happens on user switch). Any subsequent startListening() hits the guard and returns silently.

After (fixed)

class MyRepository {
  bool _disposed = false;
  StreamSubscription<Event>? _subscription;

  void startListening() {
    // Guard still checks _disposed for the permanent-teardown case — that
    // window is only open during _resetState()'s synchronous body.
    if (_subscription != null || _disposed || !isInitialized) return;
    _subscription = _client.subscribe(...).listen(...);
  }

  Future<void> stopListening() async {
    // Do NOT set _disposed here — _disposed is reserved for _resetState()
    // (permanent teardown, e.g. user switch). Setting it would make a
    // subsequent startListening() call a silent no-op and break re-open
    // flows like "user leaves the screen and comes back later".
    await _subscription?.cancel();
    _subscription = null;
  }

  void _resetState() {
    _disposed = true;
    // ... wipe credentials, cancel subscription, etc. ...
    _disposed = false;
  }
}

The _subscription != null half of the guard is still sufficient to make startListening() idempotent against double-calls within a single listening lifetime.

Verification

1. Add a regression test that exercises start → stop → start and asserts the start work happened twice:

   test('startListening after stopListening re-opens the subscription', () async {
     final repo = createRepository();
     repo.initialize(...);
   
     repo.startListening();
     await repo.stopListening();
     repo.startListening();
   
     // Both opens must hit the client.
     verify(() => mockClient.subscribe(any(), ...)).called(2);
   
     await repo.stopListening();
   });
   

2. Manual QA: visit the screen that drives the lifecycle, back out of it, visit it again. The feature should work on the second visit identically to the first.

3. Run the existing test for the permanent-teardown path (e.g. user switch / _resetState()) and confirm it still passes. The fix should not affect that path.

Example

From divine-mobile (PR #2769, April 2026): DmRepository drove NIP-17 gift-wrap subscription lifecycle from the inbox screen's initState/dispose. On the second visit to the inbox, DMs silently stopped arriving. Root cause: stopListening() had _disposed = true; as its first line. Fix: delete that line, leave an explanatory comment, add a regression test that asserts mockNostrClient.subscribe was called twice after an open → close → open cycle. Commit bd1420eb3 fix(dm): allow startListening() to succeed after stopListening().

Notes

• Why mocks hide this bug: unit tests that mock the dependency (e.g. a mock NostrClient) only verify that the repository calls subscribe() once when startListening() is called. They don't exercise the real state machine across multiple cycles unless the test explicitly cycles start→stop→start and verifies the second start also called subscribe. Add that cycle to your lifecycle test suite preemptively.
• Alternative name for the flag: if you need two flags because both concerns genuinely exist, name them for their actual meaning: _permanentlyDisposed (or _torn_down) vs _isListening (or _started). A single bool with an overloaded meaning is the root smell.
• Riverpod/Bloc lifecycle binding: this bug is especially common when a screen wires startListening() in initState and stopListening() in dispose and the user can leave and return to the screen. If that flow is new, always add a "visit twice" test to your widget test for that screen.
• Watch for asymmetric reconnect paths: onDone callbacks on cancelled streams may also read the flag and decide whether to schedule a reconnect. After separating the flags, audit every read of the old flag to confirm the new semantics still match the callsite's intent.

References

• Dart StreamSubscription.cancel() docs: https://api.dart.dev/stable/dart-async/StreamSubscription/cancel.html (cancellation does not deliver a done event to the listener, which is relevant when auditing onDone reconnect paths after this fix.)
• Flutter lifecycle (State.initState / State.dispose): https://api.flutter.dev/flutter/widgets/State-class.html