[cmd3] Add a whenCanceled method to the StateMachine

[chzboi42]

Normal commands have a whenCanceled method in the NeedsNameBuilderStage, but StateMachines don't have one as they're not normal staged commands. It would be beneficial to add one as StateMachines can still be cancelled like normal commands. Currently the alternative is to wrap the StateMachine in a staged command and add a whenCanceled condition there, but that adds boilerplate and creates an extra command that shouldn't really be needed.

There could be a whenCanceled(Runnable) method that stores a callback, then the StateMachine overrides the onCancel() method to run that callback. It would look something like this (Java):

private Runnable m_onCancel = () -> {};

public void whenCanceled(Runnable onCancel) {
     m_onCancel = onCancel;
}

@Override
public void onCancel() {
     m_onCancel.run();
}

It may also be a good idea to run the current state's exit sequence at the top of the onCancel method to help with cleanup. The main difference between a State's onExit and the whenCanceled is that the latter would be global and run regardless of which state is running.

[SamCarlberg]

Do you have any examples showing how this would be useful? As they are right now, state machine commands are simple wrappers for coordinating other commands - if the state machine is canceled, then the command for the state it's in will be canceled and its onCancel() hook will be called. What cancellation logic would the state machine need?

[chzboi42]

Do you have any examples showing how this would be useful? As they are right now, state machine commands are simple wrappers for coordinating other commands - if the state machine is canceled, then the command for the state it's in will be canceled and its onCancel() hook will be called. What cancellation logic would the state machine need?

A state machine level onCancel() would work to cancel any methods that had been started but not necessarily ended/stopped by a previous state, such as instant commands. One example I can think of would be during a launching sequence - In a multi-stage launching sequence (Spin up launcher rollers, start indexing, start agitating, stop agitating if too much fuel is stuck), spinning a roller is usually an instant command. if the driver wanted to cancel the statemachine during the agitiation state (Assuming the command is bound to a whileTrue trigger), only the agitation state would be cancelled, and any commands inititated by the spinning up and indexing state (like running the launcher and indexer rollers) would not be cancelled, meaning those rollers would keep going. A global whenCancelled() in the StateMachine would apply to all commands regardless of state, so that the user can call commands to stop all motors when the statemachine is cancelled.

The main reason for this is that a full cleanup would run regardless of state, especially if the user wanted one last default method to run at the end for safety/redundancy. Since state machines are the alternative to complicated coroutines, since the coroutine has its own whenCancelled() method (even though commands within it might also have their own), it makes sense to me that state machine commands should also have their own overarching runnable for when they're cancelled.

[SamCarlberg]

That sounds like a misunderstanding of commands and states. In a state machine, every command is a state. If a command puts a mechanism into a certain state (such as agitating a hopper), that command should continue to run as long as the mechanism is in that state. A command that sets a state and then instantly exits (such as by starting agitation and then immediately exiting) loses out on lifecycle management (like onCancel becoming a no-op) and telemetry that doesn't match the state of the robot.