hydra

Class ClientVmMgr

java.lang.Object

hydra.ClientVmMgr

public class ClientVmMgr
extends Object

This class provides a public API that hydra clients can use to dynamically stop or start client VMs during a test run. The API can only be used from hydra tasks of type "TASK".

Hydra clients can stop any client VM, including their own. They can only start client VMs other than themselves, for obvious reasons. A VM can only be the target of a dynamic action by one client at a time. A VM cannot be the target of a dynamic action while it is itself (briefly) engaged as a source initiating an action on another VM. However, once a dynamic action has been initiated, the source of the action becomes available as a target while the action is taking place (unless it is also the target).

Stop and start methods are available in synchronous and asynchronous versions. Asynchronous methods return as soon as the stop or start is initiated, and allow clients to stop themselves and stop or start others while they are doing real work. Synchronous methods do not return until the requested stop or start has fully completed. They should be used with caution for reasons described later.

A ClientVmInfo object can be passed in to some methods to describe the target VM using various combinations of parameters. If more than one VM matches the target info, the implementation chooses one to be acted upon. The methods throw ClientVmNotFoundException if no VMs matching the target info are available as a target, either because they are already the targets of dynamic actions or are initiating dynamic actions themselves.

How a VM is stopped is controlled by the stop mode, which is one of MEAN_KILL, NICE_KILL, MEAN_EXIT, NICE_EXIT, or NICE_DISCONNECT. When a VM is actually stopped depends on 1) the stop mode and 2) whether it contains clients that have been configured for CLOSETASKs that have the runMode set to always or dynamic. To prevent a CLOSETASK from running on dynamic exits, use run mode once, which is the default setting.

How and when a VM is restarted is controlled by the start mode, which is one of IMMEDIATE, ON_DEMAND, NEVER, or after a specified number of milliseconds. When the VM is actually scheduled to run TASKs again depends on 1) the start mode and 2) whether it contains clients that have been configured for INITTASKs that have the run mode set to always or dynamic. To prevent an INITTASK from running on dynamic starts, use run mode once, which is the default setting.

Synchronous methods using an exit stop mode can experience a large delay if clients in the target VM must complete their current TASKs. The delay is even greater if they must complete some number of CLOSETASKs on shutdown or INITTASKs on startup. Also, synchronization can cause deadlock, and it is up to the test developer to avoid it. For example, if two VMs attempt to stop each other at the same time, they will block if circumstances require them both to complete their current task.

When a VM is dynamically started, it creates a new log file using the same logical VM ID but a new PID. Client logs contain informational messages about the requested action. The action itself takes place in the master, using threads named for the source client and the particular action, e.g., Dynamic Client VM Stopper.

Field Summary

Fields

Modifier and Type	Field and Description
protected static int	ASYNC
static int	DEFAULT_START_MODE The default start mode, ON_DEMAND.
static int	DEFAULT_STOP_MODE The default stop mode, MEAN_KILL.
static String	Immediate
static int	IMMEDIATE Use as a start mode when immediate restart is desired.
static int	MEAN_EXIT Use as a stop mode to issue a normal System.exit(0) shutdown on the VM, without a prior distributed system disconnect.
static int	MEAN_KILL Use as a stop mode to issue kill -9 on the VM.
static String	MeanExit
static String	MeanKill
static String	Never
static int	NEVER Use as a start mode when restart must never occur.
static int	NICE_DISCONNECT Use as a stop mode to issue a distributed system disconnect on the VM.
static int	NICE_EXIT Use as a stop mode to issue a distributed system disconnect and normal System.exit(0) shutdown on the VM.
static int	NICE_KILL Use as a stop mode to issue kill -TERM on the VM.
static String	NiceDisconnect
static String	NiceExit
static String	NiceKill
static int	ON_DEMAND Use as a start mode when restart should wait for invocation of a start method in this interface.
static String	OnDemand
protected static int	SYNC

Constructor Summary

Constructors

Constructor and Description
ClientVmMgr()

Method Summary

Modifier and Type	Method and Description
static Vector	getClientVmids() Returns the VM IDs (as Integers) for all client VMs, regardless of whether the VMs are currently started or stopped.
static Vector	getOtherClientVmids() Returns the VM IDs (as Integers) for all client VMs except this one, regardless of whether the VMs are currently started or stopped.
static int	getPid(int vmid) Returns the PID for the client VM with the given VM ID.
static ClientVmInfo	start(String reason) Starts a client VM that was stopped using start mode ON_DEMAND.
static ClientVmInfo	start(String reason, ClientVmInfo target) Starts a client VM that was stopped using start mode ON_DEMAND, and is described by the given ClientVmInfo.
static ClientVmInfo	startAsync(String reason) Starts a client VM that was stopped using start mode ON_DEMAND.
static ClientVmInfo	startAsync(String reason, ClientVmInfo target) Starts a client VM that was stopped using start mode ON_DEMAND, and is described by the given ClientVmInfo.
protected static void	startRemote(String srcName, int srcVmid, int actionId, String reason, int syncMode, ClientVmInfo match) Starts a client VM previously reserved.
static ClientVmInfo	stop(String reason) Stops this client VM using DEFAULT_STOP_MODE, and DEFAULT_START_MODE.
static ClientVmInfo	stop(String reason, ClientVmInfo target) Stops a client VM described by the given ClientVmInfo using DEFAULT_STOP_MODE and DEFAULT_START_MODE.
static ClientVmInfo	stop(String reason, int stopMode, int startMode) Stops this client VM using the specified stop and start modes.
static ClientVmInfo	stop(String reason, int stopMode, int startMode, ClientVmInfo target) Stops a client VM described by the given ClientVmInfo using the specified stop and start modes.
static ClientVmInfo	stopAsync(String reason) Stops this client VM using DEFAULT_STOP_MODE, and DEFAULT_START_MODE.
static ClientVmInfo	stopAsync(String reason, ClientVmInfo target) Stops a client VM described by the given ClientVmInfo using DEFAULT_STOP_MODE and DEFAULT_START_MODE.
static ClientVmInfo	stopAsync(String reason, int stopMode, int startMode) Stops this client VM using the specified stop and start modes.
static ClientVmInfo	stopAsync(String reason, int stopMode, int startMode, ClientVmInfo target) Stops a client VM described by the given ClientVmInfo using the specified stop and start modes.
protected static void	stopRemote(String srcName, int srcVmid, int actionId, String reason, int syncMode, int stopMode, int startMode, ClientVmInfo match) Stops a client VM previously reserved.
static int	toStartMode(String startMode) Convert a string to a start mode.
static int	toStopMode(String stopMode) Convert a string to a stop mode.
static String	toStopModeString(int stopMode) Convert a stop mode into a string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SYNC

protected static final int SYNC

See Also:

Constant Field Values

ASYNC

protected static final int ASYNC

See Also:

Constant Field Values

NICE_KILL

public static final int NICE_KILL

Use as a stop mode to issue kill -TERM on the VM. The VM is killed without regard to whether its clients are still running tasks or are configured to run CLOSETASKs.

See Also:

Constant Field Values

NiceKill

public static final String NiceKill

See Also:

Constant Field Values

MEAN_KILL

public static final int MEAN_KILL

Use as a stop mode to issue kill -9 on the VM. The VM is killed without regard to whether its clients are still running tasks or are configured to run CLOSETASKs.

See Also:

Constant Field Values

MeanKill

public static final String MeanKill

See Also:

Constant Field Values

NICE_EXIT

public static final int NICE_EXIT

Use as a stop mode to issue a distributed system disconnect and normal System.exit(0) shutdown on the VM. The clients in the VM are first allowed to complete their current tasks and any CLOSETASKs that have been configured for them.

See Also:

Constant Field Values

NiceExit

public static final String NiceExit

See Also:

Constant Field Values

MEAN_EXIT

public static final int MEAN_EXIT

Use as a stop mode to issue a normal System.exit(0) shutdown on the VM, without a prior distributed system disconnect. The clients in the VM are first allowed to complete their current tasks and any CLOSETASKs that have been configured for them.

See Also:

Constant Field Values

MeanExit

public static final String MeanExit

See Also:

Constant Field Values

NICE_DISCONNECT

public static final int NICE_DISCONNECT

Use as a stop mode to issue a distributed system disconnect on the VM. The clients in the VM are first allowed to complete their current tasks and any CLOSETASKs that have been configured for them.

See Also:

Constant Field Values

NiceDisconnect

public static final String NiceDisconnect

See Also:

Constant Field Values

DEFAULT_STOP_MODE

public static final int DEFAULT_STOP_MODE

The default stop mode, MEAN_KILL.

See Also:

Constant Field Values

IMMEDIATE

public static final int IMMEDIATE

Use as a start mode when immediate restart is desired.

See Also:

Constant Field Values

Immediate

public static final String Immediate

See Also:

Constant Field Values

ON_DEMAND

public static final int ON_DEMAND

Use as a start mode when restart should wait for invocation of a start method in this interface.

See Also:

Constant Field Values

OnDemand

public static final String OnDemand

See Also:

Constant Field Values

NEVER

public static final int NEVER

Use as a start mode when restart must never occur.

See Also:

Constant Field Values

Never

public static final String Never

See Also:

Constant Field Values

DEFAULT_START_MODE

public static final int DEFAULT_START_MODE

The default start mode, ON_DEMAND.

See Also:

Constant Field Values

Constructor Detail

ClientVmMgr

public ClientVmMgr()

Method Detail

toStopModeString

public static String toStopModeString(int stopMode)

Convert a stop mode into a string.

toStopMode

public static int toStopMode(String stopMode)

Convert a string to a stop mode.

toStartMode

public static int toStartMode(String startMode)

Convert a string to a start mode.

stop

public static ClientVmInfo stop(String reason)
                         throws ClientVmNotFoundException

Stops this client VM using DEFAULT_STOP_MODE, and DEFAULT_START_MODE. This method is synchronous, blocking the calling client until its VM has stopped. Note that this will cause deadlock if the stop mode is NICE_EXIT or MEAN_EXIT.

Parameters:

reason - The reason for stopping the VM.

Returns:

A ClientVmInfo describing this VM.

Throws:

ClientVmNotFoundException - if this VM is unavailable as a target.

DynamicActionException - if the test is terminating abnormally and refuses to allow any further dynamic actions.

stopAsync

public static ClientVmInfo stopAsync(String reason)
                              throws ClientVmNotFoundException

Stops this client VM using DEFAULT_STOP_MODE, and DEFAULT_START_MODE. This method is asynchronous, allowing the client to continue doing real work while its VM is stopped.

Parameters:

reason - The reason for stopping the VM.

Returns:

A ClientVmInfo describing this VM.

Throws:

ClientVmNotFoundException - if this VM is unavailable as a target.

DynamicActionException - if the test is terminating abnormally and refuses to allow any further dynamic actions.

stop

public static ClientVmInfo stop(String reason,
                                int stopMode,
                                int startMode)
                         throws ClientVmNotFoundException

Stops this client VM using the specified stop and start modes. This method is synchronous, blocking the calling client until its VM has stopped. Note that this will cause deadlock if the stop mode is NICE_EXIT or MEAN_EXIT.

Parameters:

reason - The reason for stopping the VM.

stopMode - One of NICE_KILL, MEAN_KILL, NICE_EXIT, MEAN_EXIT, or NICE_DISCONNECT.

startMode - One of IMMEDIATE, ON_DEMAND, NEVER, or a positive delay in milliseconds.

Returns:

A ClientVmInfo describing this VM.

Throws:

ClientVmNotFoundException - if this VM is unavailable as a target.

IllegalArgumentException - if a mode is invalid.

DynamicActionException - if the test is terminating abnormally and refuses to allow any further dynamic actions.

stopAsync

public static ClientVmInfo stopAsync(String reason,
                                     int stopMode,
                                     int startMode)
                              throws ClientVmNotFoundException

Stops this client VM using the specified stop and start modes. This method is asynchronous, allowing the client to continue doing real work while its VM is stopped.

Parameters:

reason - The reason for stopping the VM.

stopMode - One of NICE_KILL, MEAN_KILL, NICE_EXIT, MEAN_EXIT, or NICE_DISCONNECT.

startMode - One of IMMEDIATE, ON_DEMAND, NEVER, or a positive delay in milliseconds.

Returns:

A ClientVmInfo describing this VM.

Throws:

ClientVmNotFoundException - if this VM is unavailable as a target.

IllegalArgumentException - if a mode is invalid.

DynamicActionException - if the test is terminating abnormally and refuses to allow any further dynamic actions.

stop

public static ClientVmInfo stop(String reason,
                                ClientVmInfo target)
                         throws ClientVmNotFoundException

Stops a client VM described by the given ClientVmInfo using DEFAULT_STOP_MODE and DEFAULT_START_MODE. This method is synchronous. It returns when the target VM has fully stopped, but does not wait for it to restart. Note that this method can cause a significant wait or even deadlock if used inappropriately.

Parameters:

reason - The reason for stopping the VM.

target - Information used to select the target client VM.

Returns:

A ClientVmInfo describing the selected VM.

Throws:

ClientVmNotFoundException - if this VM is unavailable as a target.

IllegalArgumentException - if target info is invalid.

DynamicActionException - if the test is terminating abnormally and refuses to allow any further dynamic actions.

stopAsync

public static ClientVmInfo stopAsync(String reason,
                                     ClientVmInfo target)
                              throws ClientVmNotFoundException

Stops a client VM described by the given ClientVmInfo using DEFAULT_STOP_MODE and DEFAULT_START_MODE. This method is asynchronous, allowing the client to continue doing real work while the target VM is stopped.

Parameters:

reason - The reason for stopping the VM.

target - Information used to select the target client VM.

Returns:

A ClientVmInfo describing the selected VM.

Throws:

ClientVmNotFoundException - if no matching VMs are available as targets.

IllegalArgumentException - if target info is invalid.

DynamicActionException - if the test is terminating abnormally and refuses to allow any further dynamic actions.

stop

public static ClientVmInfo stop(String reason,
                                int stopMode,
                                int startMode,
                                ClientVmInfo target)
                         throws ClientVmNotFoundException

Stops a client VM described by the given ClientVmInfo using the specified stop and start modes. This method is synchronous. It returns when the target VM has fully stopped, but does not wait for it to restart. Note that this method can cause a significant wait or even deadlock if used inappropriately.

Parameters:

reason - The reason for stopping the VM.

stopMode - One of NICE_KILL, MEAN_KILL, NICE_EXIT, MEAN_EXIT, or NICE_DISCONNECT.

startMode - One of IMMEDIATE, ON_DEMAND, NEVER, or a positive delay in milliseconds.

target - Information used to select the target client VM.

Returns:

A ClientVmInfo describing the selected VM.

Throws:

ClientVmNotFoundException - if no matching VMs are available as targets.

IllegalArgumentException - if mode or target info is invalid.

DynamicActionException - if the test is terminating abnormally and refuses to allow any further dynamic actions.

stopAsync

public static ClientVmInfo stopAsync(String reason,
                                     int stopMode,
                                     int startMode,
                                     ClientVmInfo target)
                              throws ClientVmNotFoundException

Stops a client VM described by the given ClientVmInfo using the specified stop and start modes. This method is asynchronous, allowing the client to continue doing real work while the target VM is stopped.

Parameters:

reason - The reason for stopping the VM.

stopMode - One of NICE_KILL, MEAN_KILL, NICE_EXIT, MEAN_EXIT, or NICE_DISCONNECT.

startMode - One of IMMEDIATE, ON_DEMAND, NEVER, or a positive delay in milliseconds.

target - Information used to select the target client VM.

Returns:

A ClientVmInfo describing the selected VM.

Throws:

ClientVmNotFoundException - if no matching VMs are available as targets.

IllegalArgumentException - if mode or target info is invalid.

DynamicActionException - if the test is terminating abnormally and refuses to allow any further dynamic actions.

start

public static ClientVmInfo start(String reason)
                          throws ClientVmNotFoundException

Starts a client VM that was stopped using start mode ON_DEMAND. The specific VM chosen is up to the implementation. This method is synchronous, blocking the calling client until the target VM has fully started and run any INITTASKs configured for it. Note that this could entail a significant wait.

Parameters:

reason - The reason for starting the VM.

Returns:

A ClientVmInfo describing the selected VM.

Throws:

ClientVmNotFoundException - if no matching VMs are available as targets.

DynamicActionException - if the test is terminating abnormally and refuses to allow any further dynamic actions.

startAsync

public static ClientVmInfo startAsync(String reason)
                               throws ClientVmNotFoundException

Starts a client VM that was stopped using start mode ON_DEMAND. The specific VM chosen is up to the implementation. This method is asynchronous, allowing the client to continue doing real work while the target VM is started.

Parameters:

reason - The reason for starting the VM.

Returns:

A ClientVmInfo describing the selected VM.

Throws:

ClientVmNotFoundException - if no matching VMs are available as targets.

DynamicActionException - if the test is terminating abnormally and refuses to allow any further dynamic actions.

start

public static ClientVmInfo start(String reason,
                                 ClientVmInfo target)
                          throws ClientVmNotFoundException

Starts a client VM that was stopped using start mode ON_DEMAND, and is described by the given ClientVmInfo. This method is synchronous, blocking the calling client until the target VM has fully started and run any INITTASKs configured for it. Note that this could entail a significant wait.

Parameters:

reason - The reason for starting the VM.

target - Information used to select the target client VM.

Returns:

A ClientVmInfo describing the selected VM.

Throws:

ClientVmNotFoundException - if no matching VMs are available as targets.

IllegalArgumentException - if the target info is invalid.

DynamicActionException - if the test is terminating abnormally and refuses to allow any further dynamic actions.

startAsync

public static ClientVmInfo startAsync(String reason,
                                      ClientVmInfo target)
                               throws ClientVmNotFoundException

Starts a client VM that was stopped using start mode ON_DEMAND, and is described by the given ClientVmInfo. This method is asynchronous, allowing the client to continue doing real work while the target VM is started.

Parameters:

reason - The reason for starting the VM.

target - Information used to select the target client VM.

Returns:

A ClientVmInfo describing the selected VM.

Throws:

ClientVmNotFoundException - if no matching VMs are available as targets.

IllegalArgumentException - if the target info is invalid.

DynamicActionException - if the test is terminating abnormally and refuses to allow any further dynamic actions.

getPid

public static int getPid(int vmid)

Returns the PID for the client VM with the given VM ID. This is -1 if the VM is currently started or stopped or is being started or stopped.

getClientVmids

public static Vector getClientVmids()

Returns the VM IDs (as Integers) for all client VMs, regardless of whether the VMs are currently started or stopped.

getOtherClientVmids

public static Vector getOtherClientVmids()

Returns the VM IDs (as Integers) for all client VMs except this one, regardless of whether the VMs are currently started or stopped.

stopRemote

protected static void stopRemote(String srcName,
                                 int srcVmid,
                                 int actionId,
                                 String reason,
                                 int syncMode,
                                 int stopMode,
                                 int startMode,
                                 ClientVmInfo match)

Stops a client VM previously reserved.

startRemote

protected static void startRemote(String srcName,
                                  int srcVmid,
                                  int actionId,
                                  String reason,
                                  int syncMode,
                                  ClientVmInfo match)

Starts a client VM previously reserved.