命令调度程序

The CommandScheduler (Java, C++) is the class responsible for actually running commands. Each iteration (ordinarily once per 20ms), the scheduler polls all registered buttons, schedules commands for execution accordingly, runs the command bodies of all scheduled commands, and ends those commands that have finished or are interrupted.

“CommandScheduler”还运行每个已注册“Subsystem”的“periodic()”方法。

使用命令调度程序

“CommandScheduler” 是一个 单例类 ，这意味着它是一个只有一个实例的全局类。因此，为了访问调度程序，用户必须调用 “CommandScheduler.getInstance()” 命令。

在大多数情况下，用户不必直接调用调度程序方法——几乎所有重要的调度程序方法在其他位置都有方便包装器（例如，在“Command”和“Subsystem”接口中）。

但是，有一个例外：用户必须从其“Robot”类的“robotPeriodic()”方法中调用“CommandScheduler.getInstance().run()”。如果不这样做，则调度程序将永远不会运行，并且命令框架将无法运行。提供的基于命令的项目模板已包含此调用。

“schedule()”方法

To schedule a command, users call the schedule() method (Java, C++). This method takes a command, and attempts to add it to list of currently-running commands, pending whether it is already running or whether its requirements are available. If it is added, its initialize() method is called.

This method walks through the following steps:

1. Verifies that the command isn’t in a composition.

2. No-op if scheduler is disabled, command is already scheduled, or robot is disabled and command doesn’t <commands:runsWhenDisabled>.

3. If requirements are in use: * If all conflicting commands are interruptible, cancel them. * If not, don’t schedule the new command.

4. Call initialize().

JavaC++ (Source)

  private void schedule(Command command) {
    if (command == null) {
      DriverStation.reportWarning("Tried to schedule a null command", true);
      return;
    }
    if (m_inRunLoop) {
      m_toSchedule.add(command);
      return;
    }

    requireNotComposed(command);

    // Do nothing if the scheduler is disabled, the robot is disabled and the command doesn't
    // run when disabled, or the command is already scheduled.
    if (m_disabled
        || isScheduled(command)
        || RobotState.isDisabled() && !command.runsWhenDisabled()) {
      return;
    }

    Set<Subsystem> requirements = command.getRequirements();

    // Schedule the command if the requirements are not currently in-use.
    if (Collections.disjoint(m_requirements.keySet(), requirements)) {
      initCommand(command, requirements);
    } else {
      // Else check if the requirements that are in use have all have interruptible commands,
      // and if so, interrupt those commands and schedule the new command.
      for (Subsystem requirement : requirements) {
        Command requiring = requiring(requirement);
        if (requiring != null
            && requiring.getInterruptionBehavior() == InterruptionBehavior.kCancelIncoming) {
          return;
        }
      }
      for (Subsystem requirement : requirements) {
        Command requiring = requiring(requirement);
        if (requiring != null) {
          cancel(requiring);
        }
      }
      initCommand(command, requirements);
    }
  }

  private void initCommand(Command command, Set<Subsystem> requirements) {
    m_scheduledCommands.add(command);
    for (Subsystem requirement : requirements) {
      m_requirements.put(requirement, command);
    }
    command.initialize();
    for (Consumer<Command> action : m_initActions) {
      action.accept(command);
    }

    m_watchdog.addEpoch(command.getName() + ".initialize()");

调度程序运行顺序

备注

每个“Command”的“initialize()”方法都是在调度命令时调用的，而不必在调度程序运行时调用（除非该命令已绑定到按钮）。

What does a single iteration of the scheduler’s run() method (Java, C++) actually do? The following section walks through the logic of a scheduler iteration. For the full implementation, see the source code (Java, C++).

步骤1：运行子系统定期方法

First, the scheduler runs the periodic() method of each registered Subsystem. In simulation, each subsystem’s simulationPeriodic() method is called as well.

JavaC++ (Source)

    // Run the periodic method of all registered subsystems.
    for (Subsystem subsystem : m_subsystems.keySet()) {
      subsystem.periodic();
      if (RobotBase.isSimulation()) {
        subsystem.simulationPeriodic();
      }
      m_watchdog.addEpoch(subsystem.getClass().getSimpleName() + ".periodic()");
    }

步骤2：轮询命令调度触发器

备注

有关触发器绑定如何工作的更多信息，请参阅:doc:binding-commands-to-triggers

其次，调度程序轮询所有已注册触发器的状态，以查看是否应调度已绑定到这些触发器的任何新命令。如果满足调度绑定命令的条件，则对命令进行调度并运行其“Initialize()”方法。

JavaC++ (Source)

    // Poll buttons for new commands to add.
    loopCache.poll();
    m_watchdog.addEpoch("buttons.run()");

步骤3：运行/完成计划的命令

第三，调度程序调用每个当前调度的命令的“execute()”方法，然后通过调用“isFinished()”方法检查命令是否完成。如果命令已完成，则还将调用“end()”方法，并对该命令进行调度，并释放其所需的子系统。

请注意，此调用顺序是针对每个命令按顺序进行的——因此，一个命令可能会先调用其“end()”方法，而另一命令可能会调用其“execute()”方法。命令按计划的顺序处理。

JavaC++ (Source)

    // Run scheduled commands, remove finished commands.
    for (Iterator<Command> iterator = m_scheduledCommands.iterator(); iterator.hasNext(); ) {
      Command command = iterator.next();

      if (!command.runsWhenDisabled() && RobotState.isDisabled()) {
        command.end(true);
        for (Consumer<Command> action : m_interruptActions) {
          action.accept(command);
        }
        m_requirements.keySet().removeAll(command.getRequirements());
        iterator.remove();
        m_watchdog.addEpoch(command.getName() + ".end(true)");
        continue;
      }

      command.execute();
      for (Consumer<Command> action : m_executeActions) {
        action.accept(command);
      }
      m_watchdog.addEpoch(command.getName() + ".execute()");
      if (command.isFinished()) {
        command.end(false);
        for (Consumer<Command> action : m_finishActions) {
          action.accept(command);
        }
        iterator.remove();

        m_requirements.keySet().removeAll(command.getRequirements());
        m_watchdog.addEpoch(command.getName() + ".end(false)");
      }
    }

步骤4：调度默认命令

最后，任何已注册的“子系统”都有其默认命令（如果有的话）。注意，此时将调用默认命令的“initialize()”方法。

JavaC++ (Source)

    // Add default commands for un-required registered subsystems.
    for (Map.Entry<Subsystem, Command> subsystemCommand : m_subsystems.entrySet()) {
      if (!m_requirements.containsKey(subsystemCommand.getKey())
          && subsystemCommand.getValue() != null) {
        schedule(subsystemCommand.getValue());
      }
    }

禁用调度程序

可以通过调用“CommandScheduler.getInstance().disable()”来禁用调度程序。禁用时，调度程序的“schedule()”和“run()”命令将不执行任何操作。

可以通过调用“CommandScheduler.getInstance.()enable()”来重新启用调度程序。

命令事件方法

Occasionally, it is desirable to have the scheduler execute a custom action whenever a certain command event (initialization, execution, or ending) occurs. This can be done with the following methods:

• onCommandInitialize (Java, C++) runs a specified action whenever a command is initialized.

• onCommandExecute (Java, C++) runs a specified action whenever a command is executed.

• onCommandFinish (Java, C++) runs a specified action whenever a command finishes normally (i.e. the isFinished() method returned true).

• onCommandInterrupt (Java, C++) runs a specified action whenever a command is interrupted (i.e. by being explicitly canceled or by another command that shares one of its requirements).

A typical use-case for these methods is adding markers in an event log whenever a command scheduling event takes place, as demonstrated in the following code from the HatchbotInlined example project (Java, C++):

JavaC++ (Source)

    // Set the scheduler to log Shuffleboard events for command initialize, interrupt, finish
    CommandScheduler.getInstance()
        .onCommandInitialize(
            command ->
                Shuffleboard.addEventMarker(
                    "Command initialized", command.getName(), EventImportance.kNormal));
    CommandScheduler.getInstance()
        .onCommandInterrupt(
            command ->
                Shuffleboard.addEventMarker(
                    "Command interrupted", command.getName(), EventImportance.kNormal));
    CommandScheduler.getInstance()
        .onCommandFinish(
            command ->
                Shuffleboard.addEventMarker(
                    "Command finished", command.getName(), EventImportance.kNormal));