[commands] Revamp Interruptible (#4192)

wpilibNewCommands/src/main/native/include/frc2/command/Command.h

@@ -91,20 +91,36 @@ class Command {
   virtual bool IsFinished() { return false; }
 
   /**
-   * Specifies the set of subsystems used by this command.  Two commands cannot
-   * use the same subsystem at the same time.  If the command is scheduled as
-   * interruptible and another command is scheduled that shares a requirement,
-   * the command will be interrupted.  Else, the command will not be scheduled.
-   * If no subsystems are required, return an empty set.
+   * Specifies the set of subsystems used by this command. Two commands cannot
+   * use the same subsystem at the same time. If another command is scheduled
+   * that shares a requirement, GetInterruptionBehavior() will be checked and
+   * followed. If no subsystems are required, return an empty set.
    *
    * <p>Note: it is recommended that user implementations contain the
    * requirements as a field, and return that field here, rather than allocating
    * a new set every time this is called.
    *
    * @return the set of subsystems that are required
+   * @see InterruptionBehavior
    */
   virtual wpi::SmallSet<Subsystem*, 4> GetRequirements() const = 0;
 
+  /**
+   * An enum describing the command's behavior when another command with a
+   * shared requirement is scheduled.
+   */
+  enum class InterruptionBehavior {
+    /**
+     * This command ends, End(true) is called, and the incoming command is
+     * scheduled normally.
+     *
+     * <p>This is the default behavior.
+     */
+    kCancelSelf,
+    /** This command continues, and the incoming command is not scheduled. */
+    kCancelIncoming
+  };
+
   /**
    * Decorates this command with a timeout.  If the specified timeout is
    * exceeded before the command finishes normally, the command will be
@@ -238,21 +254,22 @@ class Command {
   virtual std::unique_ptr<Command> IgnoringDisable(bool doesRunWhenDisabled) &&;
 
   /**
-   * Schedules this command.
+   * Decorates this command to run or stop when disabled.
    *
-   * @param interruptible whether this command can be interrupted by another
-   * command that shares one of its requirements
+   * @param interruptBehavior true to run when disabled.
+   * @return the decorated command
    */
-  void Schedule(bool interruptible);
+  virtual std::unique_ptr<Command> WithInterruptBehavior(
+      InterruptionBehavior interruptBehavior) &&;
 
   /**
-   * Schedules this command, defaulting to interruptible.
+   * Schedules this command.
    */
-  void Schedule() { Schedule(true); }
+  void Schedule();
 
   /**
-   * Cancels this command.  Will call the command's interrupted() method.
-   * Commands will be canceled even if they are not marked as interruptible.
+   * Cancels this command. Will call End(true). Commands will be canceled
+   * regardless of interruption behavior.
    */
   void Cancel();
 
@@ -296,6 +313,16 @@ class Command {
    */
   virtual bool RunsWhenDisabled() const { return false; }
 
+  /**
+   * How the command behaves when another command with a shared requirement is
+   * scheduled.
+   *
+   * @return a variant of InterruptionBehavior, defaulting to kCancelSelf.
+   */
+  virtual InterruptionBehavior GetInterruptionBehavior() const {
+    return InterruptionBehavior::kCancelSelf;
+  }
+
   virtual std::string GetName() const;
 
  protected: