Notify class

A lightweight synchronization primitive for control-plane signaling.

Notify is perfect for coordination without data payloads. Unlike channels, it doesn't carry values - just wake-up signals. Use it for configuration changes, shutdown notifications, flush commands, and "check your state" signals.

Key Concepts

• Permits: Stored notifications that can be consumed immediately
• Waiters: Tasks waiting for notifications
• notifyOne: Wake one waiter or store one permit
• notifyAll: Wake all current waiters (doesn't store permits)

Usage Patterns

Basic signaling:

final notify = Notify();

// Waiter
final (future, cancel) = notify.notified();
await future; // Waits until notified

// Notifier
notify.notifyOne(); // Wakes one waiter

Configuration reload pattern:

final configChanged = Notify();

// Worker listening for config changes
Future<void> worker() async {
  while (!shutdown) {
    final (notified, cancel) = configChanged.notified();

    // Race between work and config changes
    await XSelect.run((s) => s
      ..onFuture(notified, (_) => 'config_changed')
      ..onTick(Ticker.every(Duration(seconds: 1)), () => 'work')
    );

    reloadConfig();
  }
}

// Trigger config reload
configChanged.notifyAll(); // Wake all workers

Shutdown coordination:

final shutdown = Notify();

// Graceful shutdown
Future<void> gracefulShutdown() async {
  shutdown.notifyAll(); // Signal all workers
  await Future.delayed(Duration(seconds: 5)); // Grace period
  shutdown.close(); // Force remaining waiters to fail
}

When to use Notify vs Channels

• Use Notify for: Config changes, shutdown signals, flush commands, "wake up and check" notifications
• Use Channels for: Data processing, task queues, request/reply, anything with payloads