|
| 1 | +# Schedule Timer System |
| 2 | + |
| 3 | +The OnTime app includes an automatic timer system within the `ScheduleBloc` that manages precise timing for schedule start notifications. This system ensures that schedule start events are triggered at the exact scheduled time. |
| 4 | + |
| 5 | +## 🎯 Overview |
| 6 | + |
| 7 | +The timer system automatically: |
| 8 | + |
| 9 | +- Starts when an upcoming schedule is received |
| 10 | +- Triggers a `ScheduleStarted` event at exactly x minute 00 seconds |
| 11 | +- Handles proper cleanup and timer management |
| 12 | +- Ensures thread-safety and prevents memory leaks |
| 13 | + |
| 14 | +## 🔄 Timer Flow |
| 15 | + |
| 16 | +```mermaid |
| 17 | +sequenceDiagram |
| 18 | + participant UC as UseCase |
| 19 | + participant SB as ScheduleBloc |
| 20 | + participant Timer as Timer |
| 21 | + participant State as State |
| 22 | +
|
| 23 | + UC->>SB: ScheduleUpcomingReceived(schedule) |
| 24 | + SB->>SB: Cancel existing timer |
| 25 | + SB->>SB: _startScheduleTimer(schedule) |
| 26 | + SB->>Timer: Create Timer(targetTime) |
| 27 | + Note over Timer: Timer set for schedule.scheduleTime<br/>at x minute 00 seconds |
| 28 | + SB->>State: emit(ScheduleState.upcoming/ongoing) |
| 29 | +
|
| 30 | + Timer-->>SB: Timer fires at exact minute |
| 31 | + SB->>SB: add(ScheduleStarted()) |
| 32 | + SB->>SB: _onScheduleStarted() |
| 33 | + SB->>State: emit(ScheduleState.started) |
| 34 | +
|
| 35 | + Note over SB: Timer cleanup on close()<br/>or new schedule received |
| 36 | +``` |
| 37 | + |
| 38 | +## 📋 Implementation Details |
| 39 | + |
| 40 | +### Key Components |
| 41 | + |
| 42 | +1. **Timer Management** |
| 43 | + |
| 44 | + - `_scheduleStartTimer`: Dart Timer instance that handles the countdown |
| 45 | + - `_currentScheduleId`: Tracks the active schedule to prevent stale events |
| 46 | + |
| 47 | +2. **Event Handling** |
| 48 | + |
| 49 | + - `ScheduleUpcomingReceived`: Triggers timer setup |
| 50 | + - `ScheduleStarted`: Fired when timer completes |
| 51 | + |
| 52 | +3. **State Transitions** |
| 53 | + - `upcoming` → `started`: When timer fires for upcoming schedules |
| 54 | + - `ongoing` → `started`: When timer fires for preparation-in-progress schedules |
| 55 | + |
| 56 | +### Timer Calculation |
| 57 | + |
| 58 | +The timer calculates the exact target time as: |
| 59 | + |
| 60 | +```dart |
| 61 | +final targetTime = DateTime( |
| 62 | + scheduleTime.year, |
| 63 | + scheduleTime.month, |
| 64 | + scheduleTime.day, |
| 65 | + scheduleTime.hour, |
| 66 | + scheduleTime.minute, |
| 67 | + 0, // Always trigger at 00 seconds |
| 68 | + 0, // 0 milliseconds |
| 69 | +); |
| 70 | +``` |
| 71 | + |
| 72 | +### Safety Features |
| 73 | + |
| 74 | +- **Timer Cancellation**: Previous timers are automatically cancelled when new schedules arrive |
| 75 | +- **Bloc State Validation**: Timer callbacks verify the bloc is still active before firing events |
| 76 | +- **Schedule ID Matching**: Events only fire for the currently tracked schedule |
| 77 | +- **Proper Cleanup**: All timers are cancelled when the bloc is disposed |
| 78 | + |
| 79 | +## 🛡️ Error Handling |
| 80 | + |
| 81 | +The system includes several safety mechanisms: |
| 82 | + |
| 83 | +1. **Past Schedule Protection**: Timers are not set for schedules in the past |
| 84 | +2. **Bloc Lifecycle Management**: Timer callbacks check `isClosed` before adding events |
| 85 | +3. **Memory Leak Prevention**: All timers are properly cancelled in `close()` |
| 86 | +4. **Race Condition Prevention**: Schedule ID tracking prevents stale timer events |
| 87 | + |
| 88 | +## 📱 Usage Example |
| 89 | + |
| 90 | +The timer system works automatically within the `ScheduleBloc`: |
| 91 | + |
| 92 | +```dart |
| 93 | +// When a new schedule is received |
| 94 | +bloc.add(ScheduleSubscriptionRequested()); |
| 95 | +
|
| 96 | +// The bloc will: |
| 97 | +// 1. Listen for upcoming schedules |
| 98 | +// 2. Automatically start timers for each schedule |
| 99 | +// 3. Emit ScheduleStarted events at the exact scheduled time |
| 100 | +// 4. Transition to 'started' state |
| 101 | +
|
| 102 | +// Listen for state changes |
| 103 | +bloc.stream.listen((state) { |
| 104 | + if (state.status == ScheduleStatus.started) { |
| 105 | + // Handle schedule start (e.g., show notification, start tracking) |
| 106 | + } |
| 107 | +}); |
| 108 | +``` |
| 109 | + |
| 110 | +## 🔧 Configuration |
| 111 | + |
| 112 | +The timer system requires no additional configuration and works automatically with: |
| 113 | + |
| 114 | +- Any `ScheduleWithPreparationEntity` that has a valid `scheduleTime` |
| 115 | +- Both upcoming and ongoing schedule states |
| 116 | +- All timezone-aware DateTime calculations |
| 117 | + |
| 118 | +## 📊 Performance Considerations |
| 119 | + |
| 120 | +- **Single Timer**: Only one timer runs at a time per bloc instance |
| 121 | +- **Minimal Memory Footprint**: Timers are created/destroyed as needed |
| 122 | +- **Precise Timing**: Uses Dart's native Timer for accurate scheduling |
| 123 | +- **Efficient Cleanup**: No lingering resources after bloc disposal |
| 124 | + |
| 125 | +## 🚀 Future Enhancements |
| 126 | + |
| 127 | +Potential improvements to consider: |
| 128 | + |
| 129 | +- Multiple concurrent schedule timers |
| 130 | +- Configurable timer precision (seconds vs milliseconds) |
| 131 | +- Timer persistence across app restarts |
| 132 | +- Integration with system-level scheduling APIs |
0 commit comments