CommandScheduler

public class CommandScheduler
extends Object implements ICommandScheduler

java.lang.Object
   ↳ com.android.tradefed.command.CommandScheduler


A scheduler for running TradeFederation commands across all available devices.

Will attempt to prioritize commands to run based on a total running count of their execution time. e.g. infrequent or fast running commands will get prioritized over long running commands.

Runs forever in background until shutdown.

Summary

Public constructors

CommandScheduler()

Creates a CommandScheduler.

Public methods

Pair<Boolean, Integer> addCommand(String[] args)

Adds a command to the scheduler.

void addCommandFile(String cmdFilePath, extraArgs)

Adds all commands from given file to the scheduler

void await()

Waits for scheduler to start running, including waiting for handover from old TF to complete if applicable.

static TradefedDelegator checkDelegation(String[] args)

Create a delegator based on the command line to see if we need to delegate the run.

static createReleaseMap(IInvocationContext context, Throwable e)

Create a map of the devices state so they can be released appropriately.

ISandbox createSandbox()

Create a ISandbox that the invocation will use to run.

void displayCommandQueue(PrintWriter printWriter)

Output detailed debug info on state of command execution queue.

void displayCommandsInfo(PrintWriter printWriter, String regex)

Output a list of current commands.

void displayInvocationsInfo(PrintWriter printWriter)

Displays a list of current invocations.

void dumpCommandsXml(PrintWriter printWriter, String regex)

Dump the expanded xml file for the command with all Option values specified for all current commands.

long execCommand(ICommandScheduler.IScheduledInvocationListener listener, reservedDevices, String[] args)

Directly execute command on already allocated devices.

long execCommand(IInvocationContext context, ICommandScheduler.IScheduledInvocationListener listener, String[] args)

Directly allocates a device and executes a command without adding it to the command queue using an already existing IInvocationContext.

long execCommand(ICommandScheduler.IScheduledInvocationListener listener, String[] args)

Directly allocates a device and executes a command without adding it to the command queue.

CommandFileWatcher getCommandFileWatcher()

Get the appropriate CommandFileWatcher for this scheduler

int getExecutingCommandCount()

Returns the number of Commands in executing state.

CommandScheduler.HostState getHostState()
String getInvocationInfo(int invocationId)

Return the information on an invocation bu specifying the invocation id.

CommandRunner.ExitCode getLastInvocationExitCode()

Return the error code of the last invocation that ran.

Throwable getLastInvocationThrowable()

Return the Throwable from the last invocation that ran.

int getReadyCommandCount()

Returns the number of Commands in ready state in the queue.

long getShutdownTimeout()
boolean isDeviceInInvocationThread(ITestDevice device)

Returns true if the device is used by an active invocation thread.

boolean isShuttingDown()
void notifyFileChanged(File cmdFile, extraArgs)
void removeAllCommands()

Remove all commands from scheduler

void run()

The main execution block of this thread.

void setClearcutClient(ClearcutClient client)

Set the client to report harness data

boolean shouldShutdownOnCmdfileError()

Return true if we need to shutdown the scheduler on a command errors

void shutdown(boolean notifyStop)

Attempt to gracefully shutdown the command scheduler.

void shutdownHard(boolean killAdb)

Attempt to forcefully shutdown the command scheduler.

void shutdownHard()

Attempt to forcefully shutdown the command scheduler.

void shutdownOnEmpty()

Similar to shutdown(), but will instead wait for all commands to be executed before exiting.

void start()

Starts the scheduler including setting up of logging, init of DeviceManager etc

boolean stopInvocation(ITestInvocation invocation)

Stop a running invocation.

boolean stopInvocation(int invocationId, String cause)

Stop a running invocation by specifying it's id.

void stopScheduling()

Stops scheduling and accepting new tests but does not stop Tradefed.

Protected methods

void cleanUp()

Closes the logs and does any other necessary cleanup before we quit.

IConfiguration createConfiguration(String[] args)
IInvocationContext createInvocationContext()
void dryRunCommandReporting(ICommandScheduler.IScheduledInvocationListener handler, IConfiguration config)

Determines if a given command is a dry-run.

long execCommand(IInvocationContext context, ICommandScheduler.IScheduledInvocationListener listener, reservedDevices, String[] args)
IConfigurationFactory getConfigFactory()

Factory method for getting a reference to the IConfigurationFactory

DeviceManagementGrpcServer getDeviceManagementServer()
IDeviceManager getDeviceManager()

Factory method for getting a reference to the IDeviceManager

TradefedFeatureServer getFeatureServer()
IHostOptions getHostOptions()
IKeyStoreClient getKeyStoreClient()

Fetches a IKeyStoreClient using the IKeyStoreFactory declared in IGlobalConfiguration or null if none is defined.

TestInvocationManagementServer getTestInvocationManagementServer()
void initLogging()

Initializes the ddmlib log.

boolean isShutdown()
void processReadyCommands(IDeviceManager manager)

Public constructors

CommandScheduler

public CommandScheduler ()

Creates a CommandScheduler.

Note: start must be called before use.

Public methods

addCommand

public Pair<Boolean, Integer> addCommand (String[] args)

Adds a command to the scheduler.

A command is essentially an instance of a configuration to run and its associated arguments.

If "--help" argument is specified the help text for the config will be outputed to stdout. Otherwise, the config will be added to the queue to run.

Parameters
args String: the config arguments.

Returns
Pair<Boolean, Integer> A pair of values, first value is a Boolean true if command was added successfully. Second value is the known command tracker id(non-negative value) if the command was added successfully, return 0 when command is added for all devices, otherwise -1.

Throws
ConfigurationException

addCommandFile

public void addCommandFile (String cmdFilePath, 
                 extraArgs)

Adds all commands from given file to the scheduler

Parameters
cmdFilePath String: the filesystem path of comand file

extraArgs : a ERROR(/List) of String arguments to append to each command parsed from file. Can be empty but should not be null.

Throws
ConfigurationException

await

public void await ()

Waits for scheduler to start running, including waiting for handover from old TF to complete if applicable.

checkDelegation

public static TradefedDelegator checkDelegation (String[] args)

Create a delegator based on the command line to see if we need to delegate the run.

Parameters
args String

Returns
TradefedDelegator

Throws
com.android.tradefed.config.ConfigurationException
ConfigurationException

createReleaseMap

public static  createReleaseMap (IInvocationContext context, 
                Throwable e)

Create a map of the devices state so they can be released appropriately.

Parameters
context IInvocationContext

e Throwable

Returns

createSandbox

public ISandbox createSandbox ()

Create a ISandbox that the invocation will use to run.

Returns
ISandbox

displayCommandQueue

public void displayCommandQueue (PrintWriter printWriter)

Output detailed debug info on state of command execution queue.

displayCommandsInfo

public void displayCommandsInfo (PrintWriter printWriter, 
                String regex)

Output a list of current commands.

Parameters
printWriter PrintWriter: the ERROR(/PrintWriter) to output to.

regex String: the regular expression to which commands should be matched in order to be printed. If null, then all commands will be printed.

displayInvocationsInfo

public void displayInvocationsInfo (PrintWriter printWriter)

Displays a list of current invocations.

Parameters
printWriter PrintWriter: the ERROR(/PrintWriter) to output to.

dumpCommandsXml

public void dumpCommandsXml (PrintWriter printWriter, 
                String regex)

Dump the expanded xml file for the command with all Option values specified for all current commands.

Parameters
printWriter PrintWriter: the ERROR(/PrintWriter) to output the status to.

regex String: the regular expression to which commands should be matched in order for the xml file to be dumped. If null, then all commands will be dumped.

execCommand

public long execCommand (ICommandScheduler.IScheduledInvocationListener listener, 
                 reservedDevices, 
                String[] args)

Directly execute command on already allocated devices.

Parameters
listener ICommandScheduler.IScheduledInvocationListener: the ICommandScheduler.IScheduledInvocationListener to be informed

reservedDevices : the ERROR(/List) to use

args String: the command arguments

Returns
long The invocation id of the scheduled command.

Throws
ConfigurationException

execCommand

public long execCommand (IInvocationContext context, 
                ICommandScheduler.IScheduledInvocationListener listener, 
                String[] args)

Directly allocates a device and executes a command without adding it to the command queue using an already existing IInvocationContext.

Parameters
context IInvocationContext: an existing IInvocationContext.

listener ICommandScheduler.IScheduledInvocationListener: the ICommandScheduler.IScheduledInvocationListener to be informed

args String: the command arguments

Returns
long

Throws
ConfigurationException
NoDeviceException

execCommand

public long execCommand (ICommandScheduler.IScheduledInvocationListener listener, 
                String[] args)

Directly allocates a device and executes a command without adding it to the command queue.

Parameters
listener ICommandScheduler.IScheduledInvocationListener: the ICommandScheduler.IScheduledInvocationListener to be informed

args String: the command arguments

Returns
long The invocation id of the scheduled command.

Throws
ConfigurationException
NoDeviceException

getCommandFileWatcher

public CommandFileWatcher getCommandFileWatcher ()

Get the appropriate CommandFileWatcher for this scheduler

Returns
CommandFileWatcher

getExecutingCommandCount

public int getExecutingCommandCount ()

Returns the number of Commands in executing state.

Returns
int

getHostState

public CommandScheduler.HostState getHostState ()

Returns
CommandScheduler.HostState

getInvocationInfo

public String getInvocationInfo (int invocationId)

Return the information on an invocation bu specifying the invocation id.

Parameters
invocationId int: the tracking id of the invocation.

Returns
String A String containing information about the invocation.

getLastInvocationExitCode

public CommandRunner.ExitCode getLastInvocationExitCode ()

Return the error code of the last invocation that ran. Return 0 (no error), if no invocation has ran yet.

Returns
CommandRunner.ExitCode

getLastInvocationThrowable

public Throwable getLastInvocationThrowable ()

Return the Throwable from the last invocation that ran. Return null, if no throwable is available.

Returns
Throwable

getReadyCommandCount

public int getReadyCommandCount ()

Returns the number of Commands in ready state in the queue.

Returns
int

getShutdownTimeout

public long getShutdownTimeout ()

Returns
long

isDeviceInInvocationThread

public boolean isDeviceInInvocationThread (ITestDevice device)

Returns true if the device is used by an active invocation thread.

Parameters
device ITestDevice

Returns
boolean

isShuttingDown

public boolean isShuttingDown ()

Returns
boolean

notifyFileChanged

public void notifyFileChanged (File cmdFile, 
                 extraArgs)

Parameters
cmdFile File

extraArgs

removeAllCommands

public void removeAllCommands ()

Remove all commands from scheduler

run

public void run ()

The main execution block of this thread.

setClearcutClient

public void setClearcutClient (ClearcutClient client)

Set the client to report harness data

Parameters
client ClearcutClient

shouldShutdownOnCmdfileError

public boolean shouldShutdownOnCmdfileError ()

Return true if we need to shutdown the scheduler on a command errors

Returns
boolean

shutdown

public void shutdown (boolean notifyStop)

Attempt to gracefully shutdown the command scheduler.

Parameters
notifyStop boolean: if true, notifies invocations of TF shutdown.

shutdownHard

public void shutdownHard (boolean killAdb)

Attempt to forcefully shutdown the command scheduler.

Similar to shutdown(), but will also optionally kill the adb connection, in an attempt to 'inspire' invocations in progress to complete quicker.

Parameters
killAdb boolean

shutdownHard

public void shutdownHard ()

Attempt to forcefully shutdown the command scheduler. Same as shutdownHard(true).

shutdownOnEmpty

public void shutdownOnEmpty ()

Similar to shutdown(), but will instead wait for all commands to be executed before exiting.

Note that if any commands are in loop mode, the scheduler will never exit.

start

public void start ()

Starts the scheduler including setting up of logging, init of DeviceManager etc

stopInvocation

public boolean stopInvocation (ITestInvocation invocation)

Stop a running invocation.

Parameters
invocation ITestInvocation

Returns
boolean true if the invocation was stopped, false otherwise

stopInvocation

public boolean stopInvocation (int invocationId, 
                String cause)

Stop a running invocation by specifying it's id.

Parameters
invocationId int: the tracking id of the invocation.

cause String: the cause for stopping the invocation.

Returns
boolean true if the invocation was stopped, false otherwise

stopScheduling

public void stopScheduling ()

Stops scheduling and accepting new tests but does not stop Tradefed. This is meant to enable a two steps shutdown where first we drain all the running tests, then terminate Tradefed process.

Protected methods

cleanUp

protected void cleanUp ()

Closes the logs and does any other necessary cleanup before we quit.

Exposed so unit tests can mock.

createConfiguration

protected IConfiguration createConfiguration (String[] args)

Parameters
args String

Returns
IConfiguration

Throws
ConfigurationException

createInvocationContext

protected IInvocationContext createInvocationContext ()

Returns
IInvocationContext

dryRunCommandReporting

protected void dryRunCommandReporting (ICommandScheduler.IScheduledInvocationListener handler, 
                IConfiguration config)

Determines if a given command is a dry-run. If the command is a dry-run, validate it. If there are any configs issue, it will throw a ConfigurationException.

Parameters
handler ICommandScheduler.IScheduledInvocationListener: ERROR(/InvocationEventHandler) to report events for dry-run validation.

config IConfiguration

Returns
void true if the command are a dry run, false otherwise.

Throws
com.android.tradefed.config.ConfigurationException
ConfigurationException

execCommand

protected long execCommand (IInvocationContext context, 
                ICommandScheduler.IScheduledInvocationListener listener, 
                 reservedDevices, 
                String[] args)

Parameters
context IInvocationContext

listener ICommandScheduler.IScheduledInvocationListener

reservedDevices

args String

Returns
long

Throws
ConfigurationException

getConfigFactory

protected IConfigurationFactory getConfigFactory ()

Factory method for getting a reference to the IConfigurationFactory

Returns
IConfigurationFactory the IConfigurationFactory to use

getDeviceManagementServer

protected DeviceManagementGrpcServer getDeviceManagementServer ()

Returns
DeviceManagementGrpcServer

getDeviceManager

protected IDeviceManager getDeviceManager ()

Factory method for getting a reference to the IDeviceManager

Returns
IDeviceManager the IDeviceManager to use

getFeatureServer

protected TradefedFeatureServer getFeatureServer ()

Returns
TradefedFeatureServer

getHostOptions

protected IHostOptions getHostOptions ()

Returns
IHostOptions

getKeyStoreClient

protected IKeyStoreClient getKeyStoreClient ()

Fetches a IKeyStoreClient using the IKeyStoreFactory declared in IGlobalConfiguration or null if none is defined.

Returns
IKeyStoreClient IKeyStoreClient

getTestInvocationManagementServer

protected TestInvocationManagementServer getTestInvocationManagementServer ()

Returns
TestInvocationManagementServer

initLogging

protected void initLogging ()

Initializes the ddmlib log.

Exposed so unit tests can mock.

isShutdown

protected boolean isShutdown ()

Returns
boolean

processReadyCommands

protected void processReadyCommands (IDeviceManager manager)

Parameters
manager IDeviceManager