Schedule Timer System

Schedule Timer System

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.

🎯 Overview

The timer system automatically:

• Starts when an upcoming schedule is received
• Triggers a ScheduleStarted event at exactly x minute 00 seconds
• Handles proper cleanup and timer management
• Ensures thread-safety and prevents memory leaks

🔄 Timer Flow

sequenceDiagram
    participant UC as UseCase
    participant SB as ScheduleBloc
    participant Timer as Timer
    participant State as State

    UC->>SB: ScheduleUpcomingReceived(schedule)
    SB->>SB: Cancel existing timer
    SB->>SB: _startScheduleTimer(schedule)
    SB->>Timer: Create Timer(targetTime)
    Note over Timer: Timer set for schedule.scheduleTime<br/>at x minute 00 seconds
    SB->>State: emit(ScheduleState.upcoming/ongoing)

    Timer-->>SB: Timer fires at exact minute
    SB->>SB: add(ScheduleStarted())
    SB->>SB: _onScheduleStarted()
    SB->>State: emit(ScheduleState.started)

    Note over SB: Timer cleanup on close()<br/>or new schedule received

Loading

📋 Implementation Details

Key Components

1. Timer Management

   • _scheduleStartTimer: Dart Timer instance that handles the countdown
   • _currentScheduleId: Tracks the active schedule to prevent stale events

2. Event Handling

   • ScheduleUpcomingReceived: Triggers timer setup
   • ScheduleStarted: Fired when timer completes

3. State Transitions

   • upcoming → started: When timer fires for upcoming schedules
   • ongoing → started: When timer fires for preparation-in-progress schedules

Timer Calculation

The timer calculates the exact target time as:

final targetTime = DateTime(
  scheduleTime.year,
  scheduleTime.month,
  scheduleTime.day,
  scheduleTime.hour,
  scheduleTime.minute,
  0, // Always trigger at 00 seconds
  0, // 0 milliseconds
);

Safety Features

• Timer Cancellation: Previous timers are automatically cancelled when new schedules arrive
• Bloc State Validation: Timer callbacks verify the bloc is still active before firing events
• Schedule ID Matching: Events only fire for the currently tracked schedule
• Proper Cleanup: All timers are cancelled when the bloc is disposed

🛡️ Error Handling

The system includes several safety mechanisms:

1. Past Schedule Protection: Timers are not set for schedules in the past
2. Bloc Lifecycle Management: Timer callbacks check isClosed before adding events
3. Memory Leak Prevention: All timers are properly cancelled in close()
4. Race Condition Prevention: Schedule ID tracking prevents stale timer events

📱 Usage Example

The timer system works automatically within the ScheduleBloc:

// When a new schedule is received
bloc.add(ScheduleSubscriptionRequested());

// The bloc will:
// 1. Listen for upcoming schedules
// 2. Automatically start timers for each schedule
// 3. Emit ScheduleStarted events at the exact scheduled time
// 4. Transition to 'started' state

// Listen for state changes
bloc.stream.listen((state) {
  if (state.status == ScheduleStatus.started) {
    // Handle schedule start (e.g., show notification, start tracking)
  }
});

🔧 Configuration

The timer system requires no additional configuration and works automatically with:

• Any ScheduleWithPreparationEntity that has a valid scheduleTime
• Both upcoming and ongoing schedule states
• All timezone-aware DateTime calculations

📊 Performance Considerations

• Single Timer: Only one timer runs at a time per bloc instance
• Minimal Memory Footprint: Timers are created/destroyed as needed
• Precise Timing: Uses Dart's native Timer for accurate scheduling
• Efficient Cleanup: No lingering resources after bloc disposal

🚀 Future Enhancements

Potential improvements to consider:

• Multiple concurrent schedule timers
• Configurable timer precision (seconds vs milliseconds)
• Timer persistence across app restarts
• Integration with system-level scheduling APIs