com.netflix.fenzo

Class TaskScheduler

java.lang.Object

com.netflix.fenzo.TaskScheduler

public class TaskScheduler
extends java.lang.Object

A scheduling service that you can use to optimize the assignment of tasks to hosts within a Mesos framework. Call the scheduleOnce() method with a list of task requests and a list of new resource lease offers, and that method will return a set of task assignments.

The TaskScheduler stores any unused lease offers and will apply them during future calls to scheduleOnce() until a time expires, which is defined by the lease offer expiry time that you set when you build the TaskScheduler (the default is 10 seconds). Upon reaching the expiry time, the TaskScheduler rejects expired resource lease offers by invoking the action you supplied then you built the TaskScheduler.

Note that when you launch a task that has been scheduled by the TaskScheduler, you should call the task assigner action available from the getTaskAssigner() method. When that task completes, you should call the task unassigner action available from the getTaskUnAssigner() method. These actions make the TaskScheduler keep track of launched tasks. The TaskScheduler then makes these tracked tasks available to its scheduling optimization functions. Do not call the scheduler concurrently. The scheduler assigns tasks in the order that they are received in a particular list. It checks each task against available resources until it finds a match.

You create your TaskScheduler by means of the TaskScheduler.Builder. It provides methods with which you can adjust the scheduler's autoscaling rules, fitness calculators, and so forth.

See Also:

Wikipedia: Builder pattern

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TaskScheduler.Builder The Builder is how you construct a TaskScheduler object with particular characteristics.

Method Summary

Modifier and Type	Method and Description
void	addOrReplaceAutoScaleRule(AutoScaleRule rule) Add a new autoscale rule to those used by this scheduler.
void	addOrReplaceResAllocs(ResAllocs resAllocs) Add a new resource allocation, or replace an existing one of the same name.
void	disableVM(java.lang.String hostname, long durationMillis) Disable the virtual machine with the specified hostname.
boolean	disableVMByVMId(java.lang.String vmID, long durationMillis) Disable the virtual machine with the specified ID.
void	enableVM(java.lang.String hostname) Enable the VM with the specified host name.
void	expireAllLeases() Call this method to instruct the task scheduler to reject all of the unused offers it is currently holding.
void	expireAllLeases(java.lang.String hostname) Call this method to instruct the task scheduler to reject all of the unused offers it is currently holding that concern resources offered by the host with the name hostname.
boolean	expireAllLeasesByVMId(java.lang.String vmId) Call this method to instruct the task scheduler to reject all of the unused offers it is currently holding that concern resources offered by the host with the ID, vmId.
void	expireLease(java.lang.String leaseId) Call this method to instruct the task scheduler to reject a particular resource offer.
java.util.Collection<AutoScaleRule>	getAutoScaleRules() Get the autoscale rules currently registered with the scheduler.
java.util.Map<java.lang.String,ResAllocs>	getResAllocs() Get the current mapping of resource allocations registered with the scheduler.
java.util.Map<java.lang.String,java.util.Map<VMResource,java.lang.Double[]>>	getResourceStatus() Returns the state of resources on all known hosts.
Action2<TaskRequest,java.lang.String>	getTaskAssigner() Get the task assigner action.
TaskTracker	getTaskTracker()
Action2<java.lang.String,java.lang.String>	getTaskUnAssigner() Get the task unassigner action.
java.util.List<VirtualMachineCurrentState>	getVmCurrentStates() Returns the current state of all known hosts.
void	removeAutoScaleRule(java.lang.String ruleName) Remove the autoscale rule associated with the given name from those used by the scheduler.
void	removeResAllocs(java.lang.String groupName) Remove a resource allocation associated with the specified name.
SchedulingResult	scheduleOnce(java.util.List<? extends TaskRequest> requests, java.util.List<VirtualMachineLease> newLeases) Schedule a list of task requests by using any newly-added resource leases in addition to any previously-unused leases.
void	setActiveVmGroupAttributeName(java.lang.String attributeName) Set how the scheduler determines to which group the VM (host) belongs.
void	setActiveVmGroups(java.util.List<java.lang.String> vmGroups) Set the list of VM group names that are active.
void	setAutoscalerCallback(Action1<AutoScaleAction> callback) Set the autoscale call back action.
void	shutdown() Mark task scheduler as shutdown and shutdown any thread pool executors created.

Methods inherited from class java.lang.Object

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

Method Detail

setAutoscalerCallback

public void setAutoscalerCallback(Action1<AutoScaleAction> callback)
                           throws java.lang.IllegalStateException

Set the autoscale call back action. The callback you pass to this method receives an indication when an autoscale action is to be performed, telling it which autoscale rule prompted the action and whether the action is to scale up or scale down the autoscale group. The callback then initiates the appropriate scaling actions.

Parameters:

callback - the callback to invoke for autoscale actions

Throws:

java.lang.IllegalStateException - if no autoscaler was established

See Also:

Autoscaling

getTaskTracker

public TaskTracker getTaskTracker()

getResAllocs

public java.util.Map<java.lang.String,ResAllocs> getResAllocs()

Get the current mapping of resource allocations registered with the scheduler.

Returns:

current mapping of resource allocations

See Also:

Resource Allocation Limits

addOrReplaceResAllocs

public void addOrReplaceResAllocs(ResAllocs resAllocs)

Add a new resource allocation, or replace an existing one of the same name.

Parameters:

resAllocs - the resource allocation to add or replace

See Also:

Resource Allocation Limits

removeResAllocs

public void removeResAllocs(java.lang.String groupName)

Remove a resource allocation associated with the specified name.

Parameters:

groupName - the name of the resource allocation to remove

See Also:

Resource Allocation Limits

getAutoScaleRules

public java.util.Collection<AutoScaleRule> getAutoScaleRules()

Get the autoscale rules currently registered with the scheduler.

Returns:

a collection of currently registered autoscale rules

See Also:

Autoscaling

addOrReplaceAutoScaleRule

public void addOrReplaceAutoScaleRule(AutoScaleRule rule)

Add a new autoscale rule to those used by this scheduler. If a rule with the same name exists, it is replaced. This autoscale rule will be used the next time the scheduler invokes its autoscale action.

Parameters:

rule - the autoscale rule to add

See Also:

Autoscaling

removeAutoScaleRule

public void removeAutoScaleRule(java.lang.String ruleName)

Remove the autoscale rule associated with the given name from those used by the scheduler.

Parameters:

ruleName - name of the autoscale rule to remove

See Also:

Autoscaling

scheduleOnce

public SchedulingResult scheduleOnce(java.util.List<? extends TaskRequest> requests,
                                     java.util.List<VirtualMachineLease> newLeases)
                              throws java.lang.IllegalStateException

Schedule a list of task requests by using any newly-added resource leases in addition to any previously-unused leases. This is the main scheduling method that attempts to assign resources to task requests. Resource leases are associated with a host name. A host can have zero or more leases. Leases that the scheduler does not use in this scheduling run it stores for later use until they expire.

You cannot add a lease object with an Id equal to that of a stored lease object; scheduleOnce() will throw an IllegalStateException. Upon throwing this exception, if you provided multiple leases in the newLeases argument, the state of internally maintained list of unused leases will be in an indeterminate state - some of the leases may have been successfully added.

The task scheduler rejects any expired leases before scheduling begins. Then, it combines all leases of a host to determine the total available resources on the host. The scheduler then tries each task request, in the order that they appear in the given list, for assignment against the available hosts until successful. For each task the scheduler returns either a successful assignment result, or, a set of assignment failures.

After the scheduler evaluates all assignments, it will reject remaining leases if they are unused and their offer time is further in the past than lease expiration interval. This prevents the scheduler from hoarding leases. If you provided an autoscaler, the scheduler then launches autoscale evaluation to run asynchronously, which runs each registered autoscale rule based on its policy.

The successful assignments contain hosts to which tasks have been successfully assigned and the offers for that host that were used for the assignments. Fenzo removes those offers from its internal state. Normally, you would use those offers to launch the tasks. For any reason if you do not launch those tasks, you must either reject the offers to Mesos, or, re-add them to Fenzo with the next call to scheduleOnce(List, List). Otherwise, those offers would be "leaked out".

Unexpected exceptions may arise during scheduling, for example, due to uncaught exceptions in user provided plugins. The scheduling routine stops upon catching any unexpected exceptions. These exceptions are surfaced to you in one or both of two ways.

• The returned result object will contain the exceptions encountered in SchedulingResult.getExceptions(). In this case, no assignments would have been made.
• This method may throw IllegalStateException with its cause set to the uncaught exception. In this case the internal state of Fenzo will be undefined.

Parameters:

requests - a list of task requests to match with resources, in their given order

newLeases - new resource leases from hosts that the scheduler can use along with any previously ununsed leases

Returns:

a SchedulingResult object that contains a task assignment results map and other summaries

Throws:

java.lang.IllegalStateException - if you call this method concurrently, or, if you try to add an existing lease again, or, if there was unexpected exception during the scheduling iteration, or, if using TaskSchedulingService, which will instead invoke scheduling from within. Unexpected exceptions can arise from uncaught exceptions in user defined plugins. It is also thrown if the scheduler has been shutdown via the shutdown() method.

getResourceStatus

public java.util.Map<java.lang.String,java.util.Map<VMResource,java.lang.Double[]>> getResourceStatus()
                                                                                               throws java.lang.IllegalStateException

Returns the state of resources on all known hosts. You can use this for debugging or informational purposes (occasionally). This method obtains and holds a lock for the duration of creating the state information. Scheduling runs are blocked around the lock.

Returns:

a Map of state information with the hostname as the key and a Map of resource state as the value. The resource state Map contains a resource as the key and a two element Double array - the first element of which contains the amount of the resource used and the second element contains the amount still available (available does not include used).

Throws:

java.lang.IllegalStateException - if called concurrently with scheduleOnce(List, List) or if called when using a TaskSchedulingService.

See Also:

How to Learn Which Resources Are Available on Which Hosts

getVmCurrentStates

public java.util.List<VirtualMachineCurrentState> getVmCurrentStates()
                                                              throws java.lang.IllegalStateException

Returns the current state of all known hosts. You might occasionally use this for debugging or informational purposes. If you call this method, it will obtain and hold a lock for as long as it takes to create the state information. Scheduling runs are blocked around the lock.

Returns:

a list containing the current state of all known VMs

Throws:

java.lang.IllegalStateException - if called concurrently with scheduleOnce(List, List) or if called when using a TaskSchedulingService.

See Also:

How to Learn the Amount of Resources Currently Available on Particular Hosts

expireLease

public void expireLease(java.lang.String leaseId)
                 throws java.lang.IllegalStateException

Call this method to instruct the task scheduler to reject a particular resource offer.

Parameters:

leaseId - the lease ID of the lease to expire

Throws:

java.lang.IllegalStateException - if the scheduler is shutdown via the isShutdown method.

expireAllLeases

public void expireAllLeases(java.lang.String hostname)
                     throws java.lang.IllegalStateException

Call this method to instruct the task scheduler to reject all of the unused offers it is currently holding that concern resources offered by the host with the name hostname.

Parameters:

hostname - the name of the host whose leases you want to expire

Throws:

java.lang.IllegalStateException - if the scheduler is shutdown via the isShutdown method.

expireAllLeasesByVMId

public boolean expireAllLeasesByVMId(java.lang.String vmId)
                              throws java.lang.IllegalStateException

Call this method to instruct the task scheduler to reject all of the unused offers it is currently holding that concern resources offered by the host with the ID, vmId.

Parameters:

vmId - the ID of the host whose leases you want to expire

Returns:

true if the given ID matches a known host, false otherwise.

Throws:

java.lang.IllegalStateException - if the scheduler is shutdown via the isShutdown method.

expireAllLeases

public void expireAllLeases()
                     throws java.lang.IllegalStateException

Call this method to instruct the task scheduler to reject all of the unused offers it is currently holding.

Throws:

java.lang.IllegalStateException - if the scheduler is shutdown via the isShutdown method.

getTaskAssigner

public Action2<TaskRequest,java.lang.String> getTaskAssigner()
                                                      throws java.lang.IllegalStateException

Get the task assigner action. For each task you assign and launch, you must call your task scheduler's getTaskAssigner().call() method in order to notify Fenzo that the task has actually been deployed on a host. Pass two arguments to this call method: the TaskRequest object for the task assigned and the hostname.

In addition, in your framework's task completion callback that you supply to Mesos, you must call your task scheduler's getTaskUnassigner().call() method to notify Fenzo that the task is no longer assigned.

Some scheduling optimizers need to know not only which tasks are waiting to be scheduled and which hosts have resource offers available, but also which tasks have previously been assigned and are currently running on hosts. These two methods help Fenzo provide this information to these scheduling optimizers.

Note that you may not call the task assigner action concurrently with scheduleOnce(). If you do so, the task assigner action will throw an IllegalStateException.

Returns:

a task assigner action

Throws:

java.lang.IllegalStateException - if the scheduler is shutdown via the isShutdown method.

getTaskUnAssigner

public Action2<java.lang.String,java.lang.String> getTaskUnAssigner()
                                                             throws java.lang.IllegalStateException

Get the task unassigner action. Call this object's call() method to unassign an assignment you have previously set for each task that completes so that internal state is maintained correctly. Pass two String arguments to this call method: the taskId and the hostname.

For each task you assign and launch, you must call your task scheduler's getTaskAssigner().call() method in order to notify Fenzo that the task has actually been deployed on a host.

In addition, in your framework's task completion callback that you supply to Mesos, you must call your task scheduler's getTaskUnassigner().call() method to notify Fenzo that the task is no longer assigned.

Some scheduling optimizers need to know not only which tasks are waiting to be scheduled and which hosts have resource offers available, but also which tasks have previously been assigned and are currently running on hosts. These two methods help Fenzo provide this information to these scheduling optimizers.

This method is safe to be called concurrently with other calls to TaskScheduler. The tasks to be unassigned are stored internally and actually unassigned at the beginning of the next scheduling iteration, that is, the next time scheduleOnce(List, List) is called.

Returns:

the task un-assigner action

Throws:

java.lang.IllegalStateException - if the scheduler is shutdown via the isShutdown method.

disableVM

public void disableVM(java.lang.String hostname,
                      long durationMillis)
               throws java.lang.IllegalStateException

Disable the virtual machine with the specified hostname. If the scheduler is not yet aware of the host with that hostname, it creates a new object for it, and therefore your disabling of it will be remembered when offers that concern that host come in later. The scheduler will not use disabled hosts for allocating resources to tasks.

Parameters:

hostname - the name of the host to disable

durationMillis - the length of time, starting from now, in milliseconds, during which the host will be disabled

Throws:

java.lang.IllegalStateException - if the scheduler is shutdown via the isShutdown method.

disableVMByVMId

public boolean disableVMByVMId(java.lang.String vmID,
                               long durationMillis)
                        throws java.lang.IllegalStateException

Disable the virtual machine with the specified ID. If the scheduler is not yet aware of the host with that hostname, it creates a new object for it, and therefore your disabling of it will be remembered when offers that concern that host come in later. The scheduler will not use disabled hosts for allocating resources to tasks.

Parameters:

vmID - the ID of the host to disable

durationMillis - the length of time, starting from now, in milliseconds, during which the host will be disabled

Returns:

true if the ID matches a known VM, false otherwise.

Throws:

java.lang.IllegalStateException - if the scheduler is shutdown via the isShutdown method.

enableVM

public void enableVM(java.lang.String hostname)
              throws java.lang.IllegalStateException

Enable the VM with the specified host name. Hosts start in an enabled state, so you only need to call this method if you have previously explicitly disabled the host.

Parameters:

hostname - the name of the host to enable

Throws:

java.lang.IllegalStateException - if the scheduler is shutdown via the isShutdown method.

setActiveVmGroupAttributeName

public void setActiveVmGroupAttributeName(java.lang.String attributeName)

Set how the scheduler determines to which group the VM (host) belongs. You can group hosts. Which group a host belongs to is determined by the value of a particular attribute in its offers. You can set which attribute defines group membership by naming it in this method.

Parameters:

attributeName - the name of the attribute that determines a VM's group

setActiveVmGroups

public void setActiveVmGroups(java.util.List<java.lang.String> vmGroups)

Set the list of VM group names that are active. VMs (hosts) that belong to groups that you do not include in this list are said to be disabled. The scheduler does not use the resources of disabled hosts when it allocates tasks. If you pass in a null list, this indicates that the scheduler should consider all groups to be enabled.

Parameters:

vmGroups - a list of VM group names that the scheduler is to consider to be enabled, or null if the scheduler is to consider every group to be enabled

shutdown

public void shutdown()

Mark task scheduler as shutdown and shutdown any thread pool executors created.