org.cloudbus.cloudsim.brokers

Interface DatacenterBroker

All Superinterfaces:

Cloneable, Comparable<SimEntity>, Identifiable, Nameable, Runnable, SimEntity

All Known Implementing Classes:

DatacenterBrokerAbstract, DatacenterBrokerBestFit, DatacenterBrokerFirstFit, DatacenterBrokerHeuristic, DatacenterBrokerSimple

public interface DatacenterBroker
extends SimEntity

Represents a broker acting on behalf of a cloud customer. It hides VM management such as vm creation, submission of cloudlets to VMs and destruction of VMs.

A broker implements the policies for selecting a VM to run a Cloudlet and a Datacenter to run the submitted VMs.

Since:

CloudSim Plus 1.0

Author:

Rodrigo N. Calheiros, Anton Beloglazov, Manoel Campos da Silva Filho

Nested Class Summary

Nested classes/interfaces inherited from interface org.cloudbus.cloudsim.core.SimEntity

SimEntity.State

Field Summary

Fields

Modifier and Type	Field and Description
static double	DEF_VM_DESTRUCTION_DELAY A default delay value to indicate that NO VM should be immediately destroyed after becoming idle.
static org.slf4j.Logger	LOGGER
static DatacenterBroker	NULL An attribute that implements the Null Object Design Pattern for DatacenterBroker objects.

Method Summary

Modifier and Type	Method and Description
DatacenterBroker	addOnVmsCreatedListener(EventListener<DatacenterBrokerEventInfo> listener) Adds an EventListener that will be notified every time VMs in the waiting list are all created (placed) in some Host.
boolean	bindCloudletToVm(Cloudlet cloudlet, Vm vm) Specifies that an already submitted cloudlet, which is in the waiting list, must run in a specific virtual machine.
List<Cloudlet>	destroyVm(Vm vm) Destroys the passed VM.
List<Cloudlet>	getCloudletCreatedList() Gets a read-only list of cloudlets created inside some Vm.
<T extends Cloudlet> List<T>	getCloudletFinishedList() Gets a copy of the list of cloudlets that have finished executing, to avoid the original list to be changed.
List<Cloudlet>	getCloudletSubmittedList()
<T extends Cloudlet> List<T>	getCloudletWaitingList() Gets the list of cloudlets submitted to the broker that are waiting to be created inside some Vm yet.
<T extends Vm> List<T>	getVmCreatedList() Gets the list of all VMs created so far, independently if they are running yet or were already destroyed.
Function<Vm,Double>	getVmDestructionDelayFunction() Gets a Function which defines when an idle VM should be destroyed.
<T extends Vm> List<T>	getVmExecList() Gets the list of VMs in execution, if they are running Cloudlets or not.
<T extends Vm> List<T>	getVmFailedList() Gets a List of VMs submitted to the broker that have failed to be created inside some Datacenter due to lack of suitable Hosts.
int	getVmsNumber() Gets the total number of VMs submitted to the broker, including created, waiting and failed VMs.
<T extends Vm> List<T>	getVmWaitingList() Gets a List of VMs submitted to the broker that are waiting to be created inside some Datacenter yet.
Vm	getWaitingVm(int index) Gets a VM from the waiting list.
boolean	isRetryFailedVms() Checks if the broker has to retry allocating VMs that couldn't be placed due to lack of suitable Hosts.
boolean	isSelectClosestDatacenter() Checks if the broker has to try selecting the closest Datacenter to place Vms, based on their timezone.
boolean	isShutdownWhenIdle() Checks if the broker must be shut down after becoming idle.
DatacenterBroker	removeOnVmsCreatedListener(EventListener<? extends EventInfo> listener) Removes an EventListener to stop it to be notified when VMs in the waiting list are all created.
DatacenterBroker	requestIdleVmDestruction(Vm vm) Checks if a VM is idle VM and request it to be destroyed at the time defined by the getVmDestructionDelayFunction().
void	requestShutdownWhenIdle() Requests the broker shutdown if it's idle.
void	setCloudletComparator(Comparator<Cloudlet> comparator) Sets a Comparator that will be used to sort every list of submitted Cloudlets before mapping each Cloudlet to a Vm.
DatacenterBroker	setDatacenterMapper(BiFunction<Datacenter,Vm,Datacenter> datacenterMapper) Sets the BiFunction that selects and returns a Datacenter to place submitted VMs.
void	setRetryFailedVms(boolean retryFailedVms) Sets if the broker has to retry allocating VMs that couldn't be placed due to lack of suitable Hosts.
DatacenterBroker	setSelectClosestDatacenter(boolean select) Defines if the broker has to try selecting the closest Datacenter to place Vms, based on their timezone.
DatacenterBroker	setShutdownWhenIdle(boolean shutdownWhenIdle) Indicates if the broker must be shut down after becoming idle.
DatacenterBroker	setVmComparator(Comparator<Vm> comparator) Sets a Comparator that will be used to sort every list of submitted VMs before requesting the creation of such VMs in some Datacenter.
DatacenterBroker	setVmDestructionDelay(double delay) Sets the delay after which an idle VM should be destroyed.
DatacenterBroker	setVmDestructionDelayFunction(Function<Vm,Double> function) Sets a Function to define the delay after which an idle VM should be destroyed.
DatacenterBroker	setVmMapper(Function<Cloudlet,Vm> vmMapper) Sets a Function that maps a given Cloudlet to a Vm.
DatacenterBroker	submitCloudlet(Cloudlet cloudlet) Submits a single Cloudlet to the broker.
DatacenterBroker	submitCloudletList(List<? extends Cloudlet> list) Sends a list of cloudlets to the broker so that it requests their creation inside some VM, following the submission delay specified in each cloudlet (if any).
DatacenterBroker	submitCloudletList(List<? extends Cloudlet> list, double submissionDelay) Sends a list of cloudlets to the broker so that it requests their creation inside some VM just after a given delay.
DatacenterBroker	submitCloudletList(List<? extends Cloudlet> list, Vm vm) Sends a list of cloudlets to the broker so that it requests their creation inside a specific VM, following the submission delay specified in each cloudlet (if any).
DatacenterBroker	submitCloudletList(List<? extends Cloudlet> list, Vm vm, double submissionDelay) Sends a list of cloudlets to the broker so that it requests their creation inside a specific VM just after a given delay.
DatacenterBroker	submitVm(Vm vm) Submits a single Vm or VmGroup to the broker.
DatacenterBroker	submitVmList(List<? extends Vm> list) Submits a list of Vm or VmGroup that their creation inside a Host will be requested to some Datacenter.
DatacenterBroker	submitVmList(List<? extends Vm> list, double submissionDelay) Submits a list of Vm or VmGroup to the broker so that their creation inside some Host will be requested just after a given delay.

Methods inherited from interface org.cloudbus.cloudsim.core.SimEntity

getShutdownTime, getSimulation, getStartTime, getState, isAlive, isFinished, isStarted, processEvent, run, schedule, schedule, schedule, schedule, schedule, schedule, schedule, setName, setSimulation, setState, shutdown, start

Methods inherited from interface org.cloudbus.cloudsim.core.Nameable

getName

Methods inherited from interface org.cloudbus.cloudsim.core.Identifiable

getId

Methods inherited from interface java.lang.Comparable

compareTo

Field Detail

LOGGER

static final org.slf4j.Logger LOGGER

NULL

static final DatacenterBroker NULL

An attribute that implements the Null Object Design Pattern for DatacenterBroker objects.

DEF_VM_DESTRUCTION_DELAY

static final double DEF_VM_DESTRUCTION_DELAY

A default delay value to indicate that NO VM should be immediately destroyed after becoming idle.

This is used as the value returned by the getVmDestructionDelayFunction() if a Function is not set.

See Also:

setVmDestructionDelayFunction(Function), Constant Field Values

Method Detail

bindCloudletToVm

boolean bindCloudletToVm(Cloudlet cloudlet,
                         Vm vm)

Specifies that an already submitted cloudlet, which is in the waiting list, must run in a specific virtual machine.

Parameters:

cloudlet - the cloudlet to be bind to a given Vm

vm - the vm to bind the Cloudlet to

Returns:

true if the Cloudlet was found in the waiting list and was bind to the given Vm, false it the Cloudlet was not found in such a list (that may mean it wasn't submitted yet or was already created)

getCloudletWaitingList

<T extends Cloudlet> List<T> getCloudletWaitingList()

Gets the list of cloudlets submitted to the broker that are waiting to be created inside some Vm yet.

Type Parameters:

T - the class of Cloudlets inside the list

Returns:

the cloudlet waiting list

getCloudletFinishedList

<T extends Cloudlet> List<T> getCloudletFinishedList()

Gets a copy of the list of cloudlets that have finished executing, to avoid the original list to be changed.

Type Parameters:

T - the class of Cloudlets inside the list

Returns:

the list of finished cloudlets

getWaitingVm

Vm getWaitingVm(int index)

Gets a VM from the waiting list.

Parameters:

index - the index of the VM to get

Returns:

the waiting VM

getVmWaitingList

<T extends Vm> List<T> getVmWaitingList()

Gets a List of VMs submitted to the broker that are waiting to be created inside some Datacenter yet.

Type Parameters:

T - the class of VMs inside the list

Returns:

the list of waiting VMs

getVmExecList

<T extends Vm> List<T> getVmExecList()

Gets the list of VMs in execution, if they are running Cloudlets or not. These VMs can receive new submitted Cloudlets.

Type Parameters:

T - the class of VMs inside the list

Returns:

the list of running VMs

See Also:

getVmCreatedList()

getVmsNumber

int getVmsNumber()

Gets the total number of VMs submitted to the broker, including created, waiting and failed VMs.

Returns:

requestIdleVmDestruction

DatacenterBroker requestIdleVmDestruction(Vm vm)

Checks if a VM is idle VM and request it to be destroyed at the time defined by the getVmDestructionDelayFunction(). The request will be sent if the given delay function returns a value greater than DEF_VM_DESTRUCTION_DELAY. Otherwise, it doesn't send the request, meaning the VM should not be destroyed according to a specific delay.

Parameters:

vm - the VM to destroy

Returns:

See Also:

getVmDestructionDelayFunction()

requestShutdownWhenIdle

void requestShutdownWhenIdle()

Requests the broker shutdown if it's idle.

destroyVm

List<Cloudlet> destroyVm(Vm vm)

Destroys the passed VM.

Parameters:

vm - Virtual machine to be destroyed

Returns:

Cloudlets which were being queued or running on the target VM. All have reset state.

getVmCreatedList

<T extends Vm> List<T> getVmCreatedList()

Gets the list of all VMs created so far, independently if they are running yet or were already destroyed. This can be used at the end of the simulation to know which VMs have executed.

Type Parameters:

T - the class of VMs inside the list

Returns:

the list of created VMs

See Also:

getVmExecList()

submitVm

DatacenterBroker submitVm(Vm vm)

Submits a single Vm or VmGroup to the broker. When a VmGroup is given, it will try to place all VMs inside it into the same Host.

Parameters:

vm - the Vm to be submitted

Returns:

See Also:

VmGroup

submitVmList

DatacenterBroker submitVmList(List<? extends Vm> list)

Submits a list of Vm or VmGroup that their creation inside a Host will be requested to some Datacenter. The Datacenter that will be chosen to place a VM is determined by the setDatacenterMapper(BiFunction).

When a list of VmGroup is given, it will try to place all VMs from the same group into the same Host.

Parameters:

list - the list of VMs to request the creation

Returns:

See Also:

VmGroup

submitVmList

DatacenterBroker submitVmList(List<? extends Vm> list,
                              double submissionDelay)

Submits a list of Vm or VmGroup to the broker so that their creation inside some Host will be requested just after a given delay. Just the VMs that don't have a delay already assigned will have its submission delay changed. All VMs will be added to the getVmWaitingList().

When a list of VmGroup is given, it will try to place all VMs from the same group into the same Host.

Parameters:

list - the list of VMs to request the creation

submissionDelay - the delay the broker has to include when requesting the creation of VMs

Returns:

See Also:

submitVmList(java.util.List), Delayable.getSubmissionDelay(), VmGroup

submitCloudlet

DatacenterBroker submitCloudlet(Cloudlet cloudlet)

Submits a single Cloudlet to the broker.

Parameters:

cloudlet - the Cloudlet to be submitted

Returns:

submitCloudletList

DatacenterBroker submitCloudletList(List<? extends Cloudlet> list)

Sends a list of cloudlets to the broker so that it requests their creation inside some VM, following the submission delay specified in each cloudlet (if any). All cloudlets will be added to the getCloudletWaitingList().

Parameters:

list - the list of Cloudlets to request the creation

Returns:

See Also:

submitCloudletList(java.util.List, double)

submitCloudletList

DatacenterBroker submitCloudletList(List<? extends Cloudlet> list,
                                    double submissionDelay)

Sends a list of cloudlets to the broker so that it requests their creation inside some VM just after a given delay. Just the Cloudlets that don't have a delay already assigned will have its submission delay changed. All cloudlets will be added to the getCloudletWaitingList(), setting their submission delay to the specified value.

Parameters:

list - the list of Cloudlets to request the creation

submissionDelay - the delay the broker has to include when requesting the creation of Cloudlets

Returns:

See Also:

submitCloudletList(java.util.List), Cloudlet.getSubmissionDelay()

submitCloudletList

DatacenterBroker submitCloudletList(List<? extends Cloudlet> list,
                                    Vm vm)

Sends a list of cloudlets to the broker so that it requests their creation inside a specific VM, following the submission delay specified in each cloudlet (if any). All cloudlets will be added to the getCloudletWaitingList().

Parameters:

list - the list of Cloudlets to request the creation

vm - the VM to which all Cloudlets will be bound to

Returns:

See Also:

submitCloudletList(java.util.List, double)

submitCloudletList

DatacenterBroker submitCloudletList(List<? extends Cloudlet> list,
                                    Vm vm,
                                    double submissionDelay)

Sends a list of cloudlets to the broker so that it requests their creation inside a specific VM just after a given delay. Just the Cloudlets that don't have a delay already assigned will have its submission delay changed. All cloudlets will be added to the getCloudletWaitingList(), setting their submission delay to the specified value.

Parameters:

list - the list of Cloudlets to request the creation

vm - the VM to which all Cloudlets will be bound to

submissionDelay - the delay the broker has to include when requesting the creation of Cloudlets

Returns:

See Also:

submitCloudletList(java.util.List), Cloudlet.getSubmissionDelay()

setDatacenterMapper

DatacenterBroker setDatacenterMapper(BiFunction<Datacenter,Vm,Datacenter> datacenterMapper)

Sets the BiFunction that selects and returns a Datacenter to place submitted VMs.

It defines the policy to select a Datacenter to host a VM that is waiting to be created. It receives as parameter the last selected Datacenter, the VM trying to be created and should return:

• the Datacenter for the next VMs in the waiting list
• or Datacenter.NULL if no suitable Datacenter was found

The provided BiFunction is accountable to define when the last used Datacenter will be used for waiting VMs or a next one will be tried.

When there are VMs in the waiting list, the provided Function will be called. If it receives Datacenter.NULL it indicates that a Datacenter was never selected to place VMs or the previous selected Datacenter has not enough resources for all the waiting VMs. The Function you provide here should consider that when returning the Datacenter where the creation of waiting VMs will be tried.

Parameters:

datacenterMapper - the datacenterMapper to set

Returns:

setVmComparator

DatacenterBroker setVmComparator(Comparator<Vm> comparator)

Sets a Comparator that will be used to sort every list of submitted VMs before requesting the creation of such VMs in some Datacenter. After sorting, the VM creation requests will be sent in the order of the sorted VM list.

Parameters:

comparator - the VM Comparator to set

Returns:

setCloudletComparator

void setCloudletComparator(Comparator<Cloudlet> comparator)

Sets a Comparator that will be used to sort every list of submitted Cloudlets before mapping each Cloudlet to a Vm. After sorting, the Cloudlet mapping will follow the order of the sorted Cloudlet list.

Parameters:

comparator - the Cloudlet Comparator to set

setVmMapper

DatacenterBroker setVmMapper(Function<Cloudlet,Vm> vmMapper)

Sets a Function that maps a given Cloudlet to a Vm. It defines the policy used to select a Vm to host a Cloudlet that is waiting to be created.

Parameters:

vmMapper - the Vm mapper Function to set. Such a Function must receive a Cloudlet and return the Vm where it will be placed into. If the Function is unable to find a VM for a Cloudlet, it should return Vm.NULL.

Returns:

setSelectClosestDatacenter

DatacenterBroker setSelectClosestDatacenter(boolean select)

Defines if the broker has to try selecting the closest Datacenter to place Vms, based on their timezone. The default behaviour is to ignore Datacenters and Vms timezones.

Parameters:

select - true to try selecting the closest Datacenter to be selected, false to ignore distance

Returns:

isSelectClosestDatacenter

boolean isSelectClosestDatacenter()

Checks if the broker has to try selecting the closest Datacenter to place Vms, based on their timezone. The default behaviour is to ignore Datacenters and Vms timezones.

Returns:

true if the closest Datacenter selection is enabled, false if it's disabled

See Also:

setSelectClosestDatacenter(boolean)

getCloudletCreatedList

List<Cloudlet> getCloudletCreatedList()

Gets a read-only list of cloudlets created inside some Vm.

Returns:

the list of created Cloudlets

addOnVmsCreatedListener

DatacenterBroker addOnVmsCreatedListener(EventListener<DatacenterBrokerEventInfo> listener)

Adds an EventListener that will be notified every time VMs in the waiting list are all created (placed) in some Host.

Events are fired according to the following conditions:

• if all VMs are submitted before the simulation start and all those VMs are created after starting, then the event will be fired just once, in the entire simulation execution time, for every registered Listener;
• if new VMs are submitted during simulation execution, the event may be fired multiple times. For instance, consider new VMs are submitted during simulation execution at times 10 and 20. If for every submission time, all VMs could be created, then every Listener will be notified 2 times (one for VMs submitted at time 10 and other for those at time 20).

If all VMs submitted at a given time cannot be created due to lack of suitable Hosts, the event will not be fired for that submission.

Parameters:

listener - the Listener that will be notified

Returns:

See Also:

getVmWaitingList()

removeOnVmsCreatedListener

DatacenterBroker removeOnVmsCreatedListener(EventListener<? extends EventInfo> listener)

Removes an EventListener to stop it to be notified when VMs in the waiting list are all created.

Parameters:

listener - the Listener that will be removed

Returns:

See Also:

addOnVmsCreatedListener(EventListener)

getVmDestructionDelayFunction

Function<Vm,Double> getVmDestructionDelayFunction()

Gets a Function which defines when an idle VM should be destroyed. The Function receives a Vm and returns the delay to wait (in seconds), after the VM becomes idle, to destroy it.

Returns:

See Also:

DEF_VM_DESTRUCTION_DELAY, AbstractMachine.getIdleInterval()

setVmDestructionDelay

DatacenterBroker setVmDestructionDelay(double delay)

Sets the delay after which an idle VM should be destroyed. Using such a method, it defines the same delay for any VM that becomes idle. If you need to define different delays for distinct VMs use the setVmDestructionDelayFunction(Function) method.

Parameters:

delay - the time (in seconds) to wait before destroying idle VMs

Returns:

See Also:

DEF_VM_DESTRUCTION_DELAY, AbstractMachine.getIdleInterval()

setVmDestructionDelayFunction

DatacenterBroker setVmDestructionDelayFunction(Function<Vm,Double> function)

Sets a Function to define the delay after which an idle VM should be destroyed. The Function must receive a Vm and return the delay to wait (in seconds), after the VM becomes idle, to destroy it.

By providing a Function to define when idle VMs should be destroyed enables you to define different delays for every VM that becomes idle, according to desired conditions.

WARNING: The delay returned by the given function should be larger then the simulation minTimeBetweenEvents to ensure VMs are gracefully shutdown.

Parameters:

function - the Function to set (if null is given, no idle VM will be automatically destroyed)

Returns:

See Also:

DEF_VM_DESTRUCTION_DELAY, AbstractMachine.getIdleInterval(), setVmDestructionDelay(double)

getCloudletSubmittedList

List<Cloudlet> getCloudletSubmittedList()

getVmFailedList

<T extends Vm> List<T> getVmFailedList()

Gets a List of VMs submitted to the broker that have failed to be created inside some Datacenter due to lack of suitable Hosts. VMs are just moved to that list if retryFailedVms is not enabled.

Type Parameters:

T - the class of VMs inside the list

Returns:

the list of failed VMs

See Also:

setRetryFailedVms(boolean)}

isRetryFailedVms

boolean isRetryFailedVms()

Checks if the broker has to retry allocating VMs that couldn't be placed due to lack of suitable Hosts.

Returns:

setRetryFailedVms

void setRetryFailedVms(boolean retryFailedVms)

Sets if the broker has to retry allocating VMs that couldn't be placed due to lack of suitable Hosts. Setting the attribute to:

• true, the broker will retry to place the failed VM as soon as new VMs or Cloudlets are submitted.
• false, the VM will be just added to the getVmFailedList() and the user simulation have to deal with it. If the VM has an OnCreationFailureListener, the VM will be notified about the failure.

isShutdownWhenIdle

boolean isShutdownWhenIdle()

Checks if the broker must be shut down after becoming idle.

Returns:

setShutdownWhenIdle

DatacenterBroker setShutdownWhenIdle(boolean shutdownWhenIdle)

Indicates if the broker must be shut down after becoming idle.

Returns: