001// Copyright (c) FIRST and other WPILib contributors.
002// Open Source Software; you can modify and/or share it under the terms of
003// the WPILib BSD license file in the root directory of this project.
004
005package org.wpilib.commands3;
006
007import edu.wpi.first.wpilibj.RobotController;
008import java.util.function.Consumer;
009
010/**
011 * An event that occurs during scheduler processing. This can range from {@link Scheduled a command
012 * being scheduled} by a trigger or manual call to {@link Scheduler#schedule(Command)} to {@link
013 * Interrupted a command being interrupted by another}. Event listeners can be registered with a
014 * scheduler via {@link Scheduler#addEventListener(Consumer)}. All events have a timestamp to
015 * indicate when the event occurred.
016 */
017public sealed interface SchedulerEvent {
018  /**
019   * The timestamp for when the event occurred. Measured in microseconds since some arbitrary start
020   * time.
021   *
022   * @return The event timestamp.
023   * @see RobotController#getTime()
024   */
025  long timestampMicros();
026
027  /**
028   * An event marking when a command is scheduled in {@link Scheduler#schedule(Command)}.
029   *
030   * @param command The command that was scheduled
031   * @param timestampMicros When the command was scheduled
032   */
033  record Scheduled(Command command, long timestampMicros) implements SchedulerEvent {}
034
035  /**
036   * An event marking when a command starts running.
037   *
038   * @param command The command that started
039   * @param timestampMicros When the command started
040   */
041  record Mounted(Command command, long timestampMicros) implements SchedulerEvent {}
042
043  /**
044   * An event marking when a command yielded control with {@link Coroutine#yield()}.
045   *
046   * @param command The command that yielded
047   * @param timestampMicros When the command yielded
048   */
049  record Yielded(Command command, long timestampMicros) implements SchedulerEvent {}
050
051  /**
052   * An event marking when a command completed naturally.
053   *
054   * @param command The command that completed
055   * @param timestampMicros When the command completed
056   */
057  record Completed(Command command, long timestampMicros) implements SchedulerEvent {}
058
059  /**
060   * An event marking when a command threw or encountered an unhanded exception.
061   *
062   * @param command The command that encountered the error
063   * @param error The unhandled error
064   * @param timestampMicros When the error occurred
065   */
066  record CompletedWithError(Command command, Throwable error, long timestampMicros)
067      implements SchedulerEvent {}
068
069  /**
070   * An event marking when a command was canceled. If the command was canceled because it was
071   * interrupted by another command, an {@link Interrupted} will be emitted immediately prior to the
072   * cancellation event.
073   *
074   * @param command The command that was canceled
075   * @param timestampMicros When the command was canceled
076   */
077  record Canceled(Command command, long timestampMicros) implements SchedulerEvent {}
078
079  /**
080   * An event marking when a command was interrupted by another. Typically followed by an {@link
081   * Canceled} event.
082   *
083   * @param command The command that was interrupted
084   * @param interrupter The interrupting command
085   * @param timestampMicros When the command was interrupted
086   */
087  record Interrupted(Command command, Command interrupter, long timestampMicros)
088      implements SchedulerEvent {}
089}