WPILibC++  unspecified
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Pages
Command Class Referenceabstract

The Command class is at the very core of the entire command framework. More...

#include <Command.h>

Inheritance diagram for Command:
ErrorBase NamedSendable ITableListener Sendable CommandGroup PIDCommand PrintCommand StartCommand WaitCommand WaitForChildren WaitUntilCommand

Public Types

typedef std::set< Subsystem * > SubsystemSet
 

Public Member Functions

 Command ()
 Creates a new command. More...
 
 Command (const std::string &name)
 Creates a new command with the given name and no timeout. More...
 
 Command (double timeout)
 Creates a new command with the given timeout and a default name. More...
 
 Command (const std::string &name, double timeout)
 Creates a new command with the given name and timeout. More...
 
double TimeSinceInitialized () const
 Returns the time since this command was initialized (in seconds). More...
 
void Requires (Subsystem *s)
 This method specifies that the given Subsystem is used by this command. More...
 
bool IsCanceled () const
 Returns whether or not this has been canceled. More...
 
void Start ()
 Starts up the command. More...
 
bool Run ()
 The run method is used internally to actually run the commands. More...
 
void Cancel ()
 This will cancel the current command. More...
 
bool IsRunning () const
 Returns whether or not the command is running. More...
 
bool IsInterruptible () const
 Returns whether or not this command can be interrupted. More...
 
void SetInterruptible (bool interruptible)
 Sets whether or not this command can be interrupted. More...
 
bool DoesRequire (Subsystem *subsystem) const
 Checks if the command requires the given Subsystem. More...
 
SubsystemSet GetRequirements () const
 Returns the requirements (as an std::set of Subsystems pointers) of this command. More...
 
CommandGroupGetGroup () const
 Returns the CommandGroup that this command is a part of. More...
 
void SetRunWhenDisabled (bool run)
 Sets whether or not this Command should run when the robot is disabled. More...
 
bool WillRunWhenDisabled () const
 Returns whether or not this Command will run when the robot is disabled, or if it will cancel itself. More...
 
int GetID () const
 Get the ID (sequence number) for this command The ID is a unique sequence number that is incremented for each command. More...
 
virtual std::string GetName () const
 
virtual void InitTable (std::shared_ptr< ITable > table)
 Initializes a table for this sendable object. More...
 
virtual std::shared_ptr< ITableGetTable () const
 
virtual std::string GetSmartDashboardType () const
 
virtual void ValueChanged (ITable *source, llvm::StringRef key, std::shared_ptr< nt::Value > value, bool isNew)
 Called when a key-value pair is changed in a ITable. More...
 
- Public Member Functions inherited from ErrorBase
 ErrorBase (const ErrorBase &)=delete
 
ErrorBaseoperator= (const ErrorBase &)=delete
 
virtual ErrorGetError ()
 Retrieve the current error. More...
 
virtual const ErrorGetError () const
 
virtual void SetErrnoError (llvm::StringRef contextMessage, llvm::StringRef filename, llvm::StringRef function, uint32_t lineNumber) const
 Set error information associated with a C library call that set an error to the "errno" global variable. More...
 
virtual void SetImaqError (int success, llvm::StringRef contextMessage, llvm::StringRef filename, llvm::StringRef function, uint32_t lineNumber) const
 Set the current error information associated from the nivision Imaq API. More...
 
virtual void SetError (Error::Code code, llvm::StringRef contextMessage, llvm::StringRef filename, llvm::StringRef function, uint32_t lineNumber) const
 Set the current error information associated with this sensor. More...
 
virtual void SetWPIError (llvm::StringRef errorMessage, Error::Code code, llvm::StringRef contextMessage, llvm::StringRef filename, llvm::StringRef function, uint32_t lineNumber) const
 Set the current error information associated with this sensor. More...
 
virtual void CloneError (const ErrorBase &rhs) const
 
virtual void ClearError () const
 Clear the current error information associated with this sensor.
 
virtual bool StatusIsFatal () const
 Check if the current error code represents a fatal error. More...
 
- Public Member Functions inherited from ITableListener
virtual void ValueChangedEx (ITable *source, llvm::StringRef key, std::shared_ptr< nt::Value > value, unsigned int flags)
 Extended version of ValueChanged. More...
 

Protected Member Functions

void SetTimeout (double timeout)
 Sets the timeout of this command. More...
 
bool IsTimedOut () const
 Returns whether or not the timeSinceInitialized() method returns a number which is greater than or equal to the timeout for the command. More...
 
bool AssertUnlocked (const std::string &message)
 If changes are locked, then this will generate a CommandIllegalUse error. More...
 
void SetParent (CommandGroup *parent)
 Sets the parent of this command. More...
 
virtual void Initialize ()=0
 The initialize method is called the first time this Command is run after being started.
 
virtual void Execute ()=0
 The execute method is called repeatedly until this Command either finishes or is canceled.
 
virtual bool IsFinished ()=0
 Returns whether this command is finished. More...
 
virtual void End ()=0
 Called when the command ended peacefully. More...
 
virtual void Interrupted ()=0
 Called when the command ends because somebody called cancel() or another command shared the same requirements as this one, and booted it out. More...
 
virtual void _Initialize ()
 
virtual void _Interrupted ()
 
virtual void _Execute ()
 
virtual void _End ()
 
virtual void _Cancel ()
 This works like cancel(), except that it doesn't throw an exception if it is a part of a command group. More...
 

Protected Attributes

std::shared_ptr< ITablem_table
 
- Protected Attributes inherited from ErrorBase
Error m_error
 

Friends

class CommandGroup
 
class Scheduler
 

Additional Inherited Members

- Static Public Member Functions inherited from ErrorBase
static void SetGlobalError (Error::Code code, llvm::StringRef contextMessage, llvm::StringRef filename, llvm::StringRef function, uint32_t lineNumber)
 
static void SetGlobalWPIError (llvm::StringRef errorMessage, llvm::StringRef contextMessage, llvm::StringRef filename, llvm::StringRef function, uint32_t lineNumber)
 
static ErrorGetGlobalError ()
 Retrieve the current global error.
 
- Static Protected Attributes inherited from ErrorBase
static priority_mutex _globalErrorMutex
 
static Error _globalError
 

Detailed Description

The Command class is at the very core of the entire command framework.

Every command can be started with a call to Start(). Once a command is started it will call Initialize(), and then will repeatedly call Execute() until the IsFinished() returns true. Once it does, End() will be called.

However, if at any point while it is running Cancel() is called, then the command will be stopped and Interrupted() will be called.

If a command uses a Subsystem, then it should specify that it does so by calling the Requires(...) method in its constructor. Note that a Command may have multiple requirements, and Requires(...) should be called for each one.

If a command is running and a new command with shared requirements is started, then one of two things will happen. If the active command is interruptible, then Cancel() will be called and the command will be removed to make way for the new one. If the active command is not interruptible, the other one will not even be started, and the active one will continue functioning.

See Also
CommandGroup
Subsystem

Constructor & Destructor Documentation

Command::Command ( )

Creates a new command.

The name of this command will be default.

Command::Command ( const std::string &  name)

Creates a new command with the given name and no timeout.

Parameters
namethe name for this command
Command::Command ( double  timeout)

Creates a new command with the given timeout and a default name.

Parameters
timeoutthe time (in seconds) before this command "times out"
See Also
Command::isTimedOut() isTimedOut()
Command::Command ( const std::string &  name,
double  timeout 
)

Creates a new command with the given name and timeout.

Parameters
namethe name of the command
timeoutthe time (in seconds) before this command "times out"
See Also
Command::isTimedOut() isTimedOut()

Member Function Documentation

void Command::_Cancel ( )
protectedvirtual

This works like cancel(), except that it doesn't throw an exception if it is a part of a command group.

Should only be called by the parent command group.

bool Command::AssertUnlocked ( const std::string &  message)
protected

If changes are locked, then this will generate a CommandIllegalUse error.

Parameters
messagethe message to report on error (it is appended by a default message)
Returns
true if assert passed, false if assert failed
void Command::Cancel ( )

This will cancel the current command.

This will cancel the current command eventually. It can be called multiple times. And it can be called when the command is not running. If the command is running though, then the command will be marked as canceled and eventually removed.

A command can not be canceled if it is a part of a command group, you must cancel the command group instead.

bool Command::DoesRequire ( Subsystem system) const

Checks if the command requires the given Subsystem.

Parameters
systemthe system
Returns
whether or not the subsystem is required (false if given nullptr)
virtual void Command::End ( )
protectedpure virtual

Called when the command ended peacefully.

This is where you may want to wrap up loose ends, like shutting off a motor that was being used in the command.

Implemented in CommandGroup, WaitUntilCommand, PrintCommand, WaitForChildren, WaitCommand, and StartCommand.

CommandGroup * Command::GetGroup ( ) const

Returns the CommandGroup that this command is a part of.

Will return null if this Command is not in a group.

Returns
the CommandGroup that this command is a part of (or null if not in group)
int Command::GetID ( ) const

Get the ID (sequence number) for this command The ID is a unique sequence number that is incremented for each command.

Returns
the ID of this command
std::string Command::GetName ( ) const
virtual
Returns
the name of the subtable of SmartDashboard that the Sendable object will use

Implements NamedSendable.

Command::SubsystemSet Command::GetRequirements ( ) const

Returns the requirements (as an std::set of Subsystems pointers) of this command.

Returns
the requirements (as an std::set of Subsystems pointers) of this command
std::string Command::GetSmartDashboardType ( ) const
virtual
Returns
the string representation of the named data type that will be used by the smart dashboard for this sendable

Implements Sendable.

Reimplemented in PIDCommand.

std::shared_ptr< ITable > Command::GetTable ( ) const
virtual
Returns
the table that is currently associated with the sendable

Implements Sendable.

void Command::InitTable ( std::shared_ptr< ITable subtable)
virtual

Initializes a table for this sendable object.

Parameters
subtableThe table to put the values in.

Implements Sendable.

Reimplemented in PIDCommand.

virtual void Command::Interrupted ( )
protectedpure virtual

Called when the command ends because somebody called cancel() or another command shared the same requirements as this one, and booted it out.

This is where you may want to wrap up loose ends, like shutting off a motor that was being used in the command.

Generally, it is useful to simply call the end() method within this method

Implemented in CommandGroup, WaitUntilCommand, PrintCommand, WaitForChildren, WaitCommand, and StartCommand.

bool Command::IsCanceled ( ) const

Returns whether or not this has been canceled.

Returns
whether or not this has been canceled
virtual bool Command::IsFinished ( )
protectedpure virtual

Returns whether this command is finished.

If it is, then the command will be removed and end() will be called.

It may be useful for a team to reference the isTimedOut() method for time-sensitive commands.

Returns
whether this command is finished.
See Also
Command::isTimedOut() isTimedOut()

Implemented in CommandGroup, WaitUntilCommand, PrintCommand, WaitForChildren, WaitCommand, and StartCommand.

bool Command::IsInterruptible ( ) const

Returns whether or not this command can be interrupted.

Returns
whether or not this command can be interrupted
bool Command::IsRunning ( ) const

Returns whether or not the command is running.

This may return true even if the command has just been canceled, as it may not have yet called Command#interrupted().

Returns
whether or not the command is running
bool Command::IsTimedOut ( ) const
protected

Returns whether or not the timeSinceInitialized() method returns a number which is greater than or equal to the timeout for the command.

If there is no timeout, this will always return false.

Returns
whether the time has expired
void Command::Requires ( Subsystem subsystem)

This method specifies that the given Subsystem is used by this command.

This method is crucial to the functioning of the Command System in general.

Note that the recommended way to call this method is in the constructor.

Parameters
subsystemthe Subsystem required
See Also
Subsystem
bool Command::Run ( )

The run method is used internally to actually run the commands.

Returns
whether or not the command should stay within the Scheduler.
void Command::SetInterruptible ( bool  interruptible)

Sets whether or not this command can be interrupted.

Parameters
interruptiblewhether or not this command can be interrupted
void Command::SetParent ( CommandGroup parent)
protected

Sets the parent of this command.

No actual change is made to the group.

Parameters
parentthe parent
void Command::SetRunWhenDisabled ( bool  run)

Sets whether or not this Command should run when the robot is disabled.

By default a command will not run when the robot is disabled, and will in fact be canceled.

Parameters
runwhether or not this command should run when the robot is disabled
void Command::SetTimeout ( double  timeout)
protected

Sets the timeout of this command.

Parameters
timeoutthe timeout (in seconds)
See Also
Command::isTimedOut() isTimedOut()
void Command::Start ( )

Starts up the command.

Gets the command ready to start.

Note that the command will eventually start, however it will not necessarily do so immediately, and may in fact be canceled before initialize is even called.

double Command::TimeSinceInitialized ( ) const

Returns the time since this command was initialized (in seconds).

This function will work even if there is no specified timeout.

Returns
the time since this command was initialized (in seconds).
void Command::ValueChanged ( ITable source,
llvm::StringRef  key,
std::shared_ptr< nt::Value value,
bool  isNew 
)
virtual

Called when a key-value pair is changed in a ITable.

Parameters
sourcethe table the key-value pair exists in
keythe key associated with the value that changed
valuethe new value
isNewtrue if the key did not previously exist in the table, otherwise it is false

Implements ITableListener.

bool Command::WillRunWhenDisabled ( ) const

Returns whether or not this Command will run when the robot is disabled, or if it will cancel itself.

Returns
whether or not this Command will run when the robot is disabled, or if it will cancel itself

The documentation for this class was generated from the following files: