Interface Vm

All Superinterfaces:
ChangeableId, Comparable<Vm>, CustomerEntity, ExecDelayable, Identifiable, Lifetimed, Machine<Resource>, Resourceful, ResourceStatsComputer<VmResourceStats>, Startable, SubmissionDelayable, TimeZoned, UniquelyIdentifiable
All Known Implementing Classes:
NetworkVm, VmAbstract, VmGroup, VmSimple
public interface Vm extends Machine<Resource>, UniquelyIdentifiable, Comparable<Vm>, CustomerEntity, TimeZoned, ResourceStatsComputer<VmResourceStats>
An interface to be implemented by each class that provides basic features for Virtual Machines (VMs). The interface implements the Null Object Design Pattern in order to start avoiding NullPointerException when using the NULL object instead of attributing null to Vm variables.
Since:
CloudSim Plus 1.0
Author:
Rodrigo N. Calheiros, Anton Beloglazov, Manoel Campos da Silva Filho

  • Field Details

    • LOGGER

      static final org.slf4j.Logger LOGGER

    • NULL

      static final Vm NULL
      An attribute that implements the Null Object Design Pattern for Vm objects.

  • Method Details

    • getDescription

      String getDescription()
      Gets the Vm description, an optional text which can be used to provide details about this VM.
      Returns:

    • setDescription

      Vm setDescription(String description)
      Sets the Vm description, an optional text which can be used to provide details about this VM.
      Parameters:
      description - the Vm description to set

    • getGroup

      VmGroup getGroup()
      Gets the group this Vm belongs to
      Returns:
      the VmGroup or NULL if the VM doesn't belong to a group

    • addStateHistoryEntry

      void addStateHistoryEntry(VmStateHistoryEntry entry)
      Adds a VM state history entry.
      Parameters:
      entry - the data about the state of the VM at given time

    • getCloudletScheduler

      CloudletScheduler getCloudletScheduler()
      Gets the Cloudlet scheduler the VM uses to schedule cloudlets execution.
      Returns:
      the cloudlet scheduler

    • getFreePesNumber

      long getFreePesNumber()
      Gets the current number of free PEs.
      Returns:
      the current free pes number

    • getExpectedFreePesNumber

      long getExpectedFreePesNumber()
      Gets the expected free pes number before the VM starts executing. This value is updated as cloudlets are assigned to VMs but not submitted to the broker yet for running.
      Returns:
      the expected free pes number

    • getCurrentRequestedBw

      long getCurrentRequestedBw()
      Gets the current requested bw.
      Returns:
      the current requested bw

    • getCurrentRequestedMips

      MipsShare getCurrentRequestedMips()
      Gets a copy list of current requested MIPS of each virtual Pe, avoiding the original list to be changed.
      Returns:
      the current requested MIPS of each Pe

    • getCurrentRequestedRam

      long getCurrentRequestedRam()
      Gets the current requested ram (in Megabytes).
      Returns:

    • getTotalCpuMipsRequested

      double getTotalCpuMipsRequested()
      Gets the current requested total MIPS. It is the sum of MIPS capacity requested for every virtual Pe.
      Returns:
      the current requested total MIPS
      See Also:

    • getHost

      Host getHost()
      Gets the Host where the Vm is or will be placed. To know if the Vm was already created inside this Host, call the isCreated() method.
      Returns:
      the Host
      See Also:

    • addOnHostAllocationListener

      Vm addOnHostAllocationListener(EventListener<VmHostEventInfo> listener)
      Adds a listener object that will be notified when a Host is allocated to the Vm, that is, when the Vm is placed into a given Host. That happens when the VM is placed for the first time into a Host or when it's migrated to another Host.
      Parameters:
      listener - the listener to add
      Returns:
      See Also:

    • addOnMigrationStartListener

      Vm addOnMigrationStartListener(EventListener<VmHostEventInfo> listener)
      Adds a listener object that will be notified when a VM starts migrating to a target Host. When the listener is notified, it receives a VmHostEventInfo object informing the target Host where the VM is being migrated.
      Parameters:
      listener - the listener to add
      Returns:
      See Also:

    • addOnMigrationFinishListener

      Vm addOnMigrationFinishListener(EventListener<VmHostEventInfo> listener)
      Adds a listener object that will be notified when a VM finishes migrating to a target Host. When the listener is notified, it receives a VmHostEventInfo object informing the target Host where the VM has just migrated.
      Parameters:
      listener - the listener to add
      Returns:

    • addOnHostDeallocationListener

      Vm addOnHostDeallocationListener(EventListener<VmHostEventInfo> listener)
      Adds a listener object that will be notified when the Vm is moved/removed from a Host.
      Parameters:
      listener - the listener to add
      Returns:

    • addOnCreationFailureListener

      Vm addOnCreationFailureListener(EventListener<VmDatacenterEventInfo> listener)
      Adds a listener object that will be notified when the Vm fail in being placed, due to lack of a Host with enough resources in a specific Datacenter.

      The DatacenterBroker is accountable for receiving the notification from the Datacenter and notifying the Listeners.

      Parameters:
      listener - the listener to add
      Returns:
      See Also:

    • addOnUpdateProcessingListener

      Vm addOnUpdateProcessingListener(EventListener<VmHostEventInfo> listener)
      Adds a listener object that will be notified every time when the processing of the Vm is updated in its Host.
      Parameters:
      listener - the listener to add
      Returns:
      See Also:

    • notifyOnHostAllocationListeners

      void notifyOnHostAllocationListeners()
      Notifies all registered listeners when a Host is allocated to the Vm.

      This method is used just internally and must not be called directly.

    • notifyOnHostDeallocationListeners

      void notifyOnHostDeallocationListeners(Host deallocatedHost)
      Notifies all registered listeners when the Vm is moved/removed from a Host.

      This method is used just internally and must not be called directly.

      Parameters:
      deallocatedHost - the Host the Vm was moved/removed from

    • notifyOnCreationFailureListeners

      void notifyOnCreationFailureListeners(Datacenter failedDatacenter)
      Notifies all registered listeners when the Vm fail in being placed for lack of a Host with enough resources in a specific Datacenter.

      This method is used just internally and must not be called directly.

      Parameters:
      failedDatacenter - the Datacenter where the VM creation failed

    • removeOnMigrationStartListener

      boolean removeOnMigrationStartListener(EventListener<VmHostEventInfo> listener)
      Removes a listener from the onMigrationStartListener List.
      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was found and removed, false otherwise

    • removeOnMigrationFinishListener

      boolean removeOnMigrationFinishListener(EventListener<VmHostEventInfo> listener)
      Removes a listener from the onMigrationFinishListener List.
      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was found and removed, false otherwise

    • removeOnUpdateProcessingListener

      boolean removeOnUpdateProcessingListener(EventListener<VmHostEventInfo> listener)
      Removes a listener from the onUpdateVmProcessingListener List.
      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was found and removed, false otherwise

    • removeOnHostAllocationListener

      boolean removeOnHostAllocationListener(EventListener<VmHostEventInfo> listener)
      Removes a listener from the onHostAllocationListener List.
      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was found and removed, false otherwise

    • removeOnHostDeallocationListener

      boolean removeOnHostDeallocationListener(EventListener<VmHostEventInfo> listener)
      Removes a listener from the onHostDeallocationListener List.
      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was found and removed, false otherwise

    • removeOnCreationFailureListener

      boolean removeOnCreationFailureListener(EventListener<VmDatacenterEventInfo> listener)
      Removes a listener from the onVmCreationFailureListener List.
      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was found and removed, false otherwise

    • getBw

      Resource getBw()
      Gets bandwidth resource (in Megabits/s) assigned to the Vm, allowing to check its capacity and usage.
      Specified by:
      getBw in interface Machine<Resource>
      Returns:
      bandwidth resource.

    • getRam

      Resource getRam()
      Gets the RAM resource assigned to the Vm, allowing to check its capacity (in Megabytes) and usage.
      Specified by:
      getRam in interface Machine<Resource>
      Returns:
      the RAM resource

    • getStorage

      Resource getStorage()
      Gets the storage device of the VM, which represents the VM image, allowing to check its capacity (in Megabytes) and usage.
      Specified by:
      getStorage in interface Machine<Resource>
      Returns:
      the storage resource

    • getStateHistory

      List<VmStateHistoryEntry> getStateHistory()
      Gets a read-only list with the history of requests and allocation of MIPS for this VM. The VM state history is just collected and stored if the Host is storing such a data.
      Returns:
      the state history
      See Also:

    • getCpuPercentUtilization

      double getCpuPercentUtilization(double time)
      Gets the percentage of CPU capacity (MIPS %) used by all Cloudlets running on this VM at the given time. It represents the actual percentage of MIPS allocated for that time.
      Parameters:
      time - the time to get the CPU utilization percentage
      Returns:
      total CPU utilization percentage (between [0 and 1])

    • getCpuPercentUtilization

      double getCpuPercentUtilization()
      Gets the current percentage of CPU capacity (MIPS %) used by all Cloudlets running on this VM. It represents the actual percentage of MIPS allocated.
      Returns:
      total CPU utilization percentage (between [0 and 1]) for the current time

    • getCpuPercentRequested

      double getCpuPercentRequested(double time)
      Gets the percentage of CPU capacity (MIPS %) requested by all Cloudlets running on this VM at the given time. It represents the percentage of MIPS requested for that time, which may be higher than the percentage used (allocated) due to lack of capacity.
      Parameters:
      time - the time to get the CPU requested percentage
      Returns:
      the percentage (between [0 and 1]) of CPU capacity requested for the current time
      See Also:

    • getCpuPercentRequested

      double getCpuPercentRequested()
      Gets the percentage of CPU capacity (MIPS %) requested by all Cloudlets running on this VM at the current time. It represents the percentage of MIPS requested, which may be higher than the percentage used (allocated) due to lack of capacity.
      Returns:
      the percentage (between [0 and 1]) of CPU capacity requested
      See Also:

    • enableUtilizationStats

      void enableUtilizationStats()
      Enables the data collection and computation of utilization statistics. If you enable the statistics for the Host where the VM is placed, that will automatically enable the statistics for every VM on that Host.
      Specified by:
      enableUtilizationStats in interface ResourceStatsComputer<VmResourceStats>
      See Also:

    • getHostRamUtilization

      double getHostRamUtilization()
      Computes the relative percentage of the RAM the VM is using from the Host's total Capacity for the current simulation time.
      Returns:
      the relative VM RAM usage percent (from 0 to 1)

    • getHostBwUtilization

      double getHostBwUtilization()
      Computes the relative percentage of the Bandwidth the VM is using from the Host's total capacity for the current simulation time.
      Returns:
      the relative VM BW usage percent (from 0 to 1)

    • getHostCpuUtilization

      default double getHostCpuUtilization()
      Computes the current relative percentage of the CPU the VM is using from the Host's total MIPS capacity. If the capacity is 1000 MIPS and the VM is using 250 MIPS, it's equivalent to 25% of the Host's capacity.
      Returns:
      the relative VM CPU usage percent (from 0 to 1)
      See Also:

    • getHostCpuUtilization

      double getHostCpuUtilization(double time)
      Computes the relative percentage of the CPU the VM is using from the Host's total MIPS capacity for the current simulation time. If the capacity is 1000 MIPS and the VM is using 250 MIPS, it's equivalent to 25% of the Host's capacity.
      Parameters:
      time - the time to get the relative VM CPU utilization
      Returns:
      the relative VM CPU usage percent (from 0 to 1)

    • getExpectedHostCpuUtilization

      double getExpectedHostCpuUtilization(double vmCpuUtilizationPercent)
      Computes what would be the relative percentage of the CPU the VM is using from a PM's total MIPS capacity, considering that the VM 's CPU load is at a given percentage.
      Parameters:
      vmCpuUtilizationPercent - the VM's CPU utilization percentage for a given time
      Returns:
      the relative VM CPU usage percent (from 0 to 1)

    • getTotalCpuMipsUtilization

      double getTotalCpuMipsUtilization()
      Gets the current total CPU MIPS utilization of all PEs from all cloudlets running on this VM.
      Returns:
      total CPU utilization in MIPS
      See Also:

    • getTotalCpuMipsUtilization

      double getTotalCpuMipsUtilization(double time)
      Gets the total CPU MIPS utilization of all PEs from all cloudlets running on this VM at the given time.
      Parameters:
      time - the time to get the utilization
      Returns:
      total CPU utilization in MIPS
      See Also:

    • getVmm

      String getVmm()
      Gets the Virtual Machine Monitor (VMM) that manages the VM.
      Returns:
      VMM

    • isCreated

      boolean isCreated()
      Checks if the VM was created and placed inside the Host. If so, resources required by the Vm already were provisioned.
      Returns:
      true, if it was created inside the Host, false otherwise

    • isSuitableForCloudlet

      boolean isSuitableForCloudlet(Cloudlet cloudlet)
      Checks if the VM has enough capacity to run a Cloudlet.
      Parameters:
      cloudlet - the candidate Cloudlet to run inside the VM
      Returns:
      true if the VM can run the Cloudlet, false otherwise TODO the Method is not being called anywhere to check if a VM has enough capacity to run a Cloudlet

    • isInMigration

      boolean isInMigration()
      Checks if the VM is in migration process or not, that is, if it is migrating in or out of a Host.
      Returns:

    • setInMigration

      Vm setInMigration(boolean migrating)
      Defines if the VM is in migration process or not.
      Parameters:
      migrating - true to indicate the VM is migrating into a Host, false otherwise

    • setBw

      Vm setBw(long bwCapacity)
      Sets the bandwidth capacity (in Megabits/s)
      Parameters:
      bwCapacity - new BW capacity (in Megabits/s)
      Returns:

    • setRam

      Vm setRam(long ramCapacity)
      Sets RAM capacity in Megabytes.
      Parameters:
      ramCapacity - new RAM capacity
      Returns:

    • setSize

      Vm setSize(long size)
      Sets the storage size (capacity) of the VM image in Megabytes.
      Parameters:
      size - new storage size
      Returns:

    • updateProcessing

      double updateProcessing(double currentTime, MipsShare mipsShare)
      Updates the processing of cloudlets running on this VM.
      Parameters:
      currentTime - current simulation time
      mipsShare - list with MIPS share of each Pe available to the scheduler
      Returns:
      the predicted completion time of the earliest finishing cloudlet (which is a relative delay from the current simulation time), or Double.MAX_VALUE if there is no next Cloudlet to execute

    • updateProcessing

      double updateProcessing(MipsShare mipsShare)
      Updates the processing of cloudlets running on this VM at the current simulation time.
      Parameters:
      mipsShare - list with MIPS share of each Pe available to the scheduler
      Returns:
      the predicted completion time of the earliest finishing cloudlet (which is a relative delay from the current simulation time), or Double.MAX_VALUE if there is no next Cloudlet to execute

    • setCloudletScheduler

      Vm setCloudletScheduler(CloudletScheduler cloudletScheduler)
      Sets the Cloudlet scheduler the Vm uses to schedule cloudlets execution. It also sets the Vm itself to the given scheduler.
      Parameters:
      cloudletScheduler - the cloudlet scheduler to set
      Returns:

    • setFailed

      void setFailed(boolean failed)
      Sets the status of VM to FAILED.
      Parameters:
      failed - true to indicate that the VM is failed, false to indicate it is working

    • isFailed

      boolean isFailed()
      Checks if the Vm is failed or not.
      Returns:
      See Also:

    • isWorking

      boolean isWorking()
      Checks if the Vm is working or failed.
      Returns:
      See Also:

    • isIdleEnough

      default boolean isIdleEnough(double time)
      Description copied from interface: Machine
      Checks if the Machine has been idle for a given amount of time (in seconds).
      Specified by:
      isIdleEnough in interface Machine<Resource>
      Parameters:
      time - the time interval to check if the Machine has been idle (in seconds). If time is zero, it will be checked if the Machine is currently idle. If it's negative, even if the Machine is idle, it's considered that it isn't idle enough. This is useful if you don't want to perform any operation when the machine becomes idle (for instance, if idle machines might be shut down and a negative value is given, they won't).
      Returns:
      true if the Machine has been idle as long as the given time; false if it's active or isn't idle long enough

    • getHorizontalScaling

      HorizontalVmScaling getHorizontalScaling()
      Gets a HorizontalVmScaling that will check if the Vm is overloaded, based on some conditions defined by a Predicate given to the HorizontalVmScaling, and then request the creation of new VMs to horizontally scale the Vm.

      If no HorizontalVmScaling is set, the Broker will not dynamically create VMs to balance arrived Cloudlets.

      Returns:

    • setHorizontalScaling

      Vm setHorizontalScaling(HorizontalVmScaling horizontalScaling) throws IllegalArgumentException
      Sets a HorizontalVmScaling that will check if the Vm is overloaded, based on some conditions defined by a Predicate given to the HorizontalVmScaling, and then request the creation of new VMs to horizontally scale the Vm.
      Parameters:
      horizontalScaling - the HorizontalVmScaling to set
      Returns:
      Throws:
      IllegalArgumentException - if the given VmScaling is already linked to a Vm. Each VM must have its own HorizontalVmScaling object or none at all.

    • setRamVerticalScaling

      Vm setRamVerticalScaling(VerticalVmScaling ramVerticalScaling) throws IllegalArgumentException
      Sets a VerticalVmScaling that will check if the Vm's Ram is under or overloaded, based on some conditions defined by Predicates given to the VerticalVmScaling, and then request the RAM up or down scaling.
      Parameters:
      ramVerticalScaling - the VerticalVmScaling to set
      Returns:
      Throws:
      IllegalArgumentException - if the given VmScaling is already linked to a Vm. Each VM must have its own VerticalVmScaling objects or none at all.

    • setBwVerticalScaling

      Vm setBwVerticalScaling(VerticalVmScaling bwVerticalScaling) throws IllegalArgumentException
      Sets a VerticalVmScaling that will check if the Vm's Bandwidth is under or overloaded, based on some conditions defined by Predicates given to the VerticalVmScaling, and then request the Bandwidth up or down scaling.
      Parameters:
      bwVerticalScaling - the VerticalVmScaling to set
      Returns:
      Throws:
      IllegalArgumentException - if the given VmScaling is already linked to a Vm. Each VM must have its own VerticalVmScaling objects or none at all.

    • setPeVerticalScaling

      Vm setPeVerticalScaling(VerticalVmScaling peVerticalScaling) throws IllegalArgumentException
      Sets a VerticalVmScaling that will check if the Vm's Pe is under or overloaded, based on some conditions defined by Predicates given to the VerticalVmScaling, and then request the Pe up or down scaling.

      The Pe scaling is performed by adding or removing PEs to/from the VM. Added PEs will have the same MIPS than the already existing ones.

      Parameters:
      peVerticalScaling - the VerticalVmScaling to set
      Returns:
      Throws:
      IllegalArgumentException - if the given VmScaling is already linked to a Vm. Each VM must have its own VerticalVmScaling objects or none at all.

    • getRamVerticalScaling

      VerticalVmScaling getRamVerticalScaling()
      Gets a VerticalVmScaling that will check if the Vm's RAM is overloaded, based on some conditions defined by a Predicate given to the VerticalVmScaling, and then request the RAM up scaling.
      Returns:

    • getBwVerticalScaling

      VerticalVmScaling getBwVerticalScaling()
      Gets a VerticalVmScaling that will check if the Vm's Bandwidth is overloaded, based on some conditions defined by a Predicate given to the VerticalVmScaling, and then request the BW up scaling.
      Returns:

    • getPeVerticalScaling

      VerticalVmScaling getPeVerticalScaling()
      Gets a VerticalVmScaling that will check if the Vm's Pe is overloaded, based on some conditions defined by a Predicate given to the VerticalVmScaling, and then request the RAM up scaling.
      Returns:

    • getProcessor

      Processor getProcessor()
      Gets the Processor of this VM. It is its Virtual CPU which may be compounded of multiple Pes.
      Returns:

    • getBroker

      DatacenterBroker getBroker()
      Gets the DatacenterBroker that represents the owner of this Vm.
      Specified by:
      getBroker in interface CustomerEntity
      Returns:
      the broker or DatacenterBroker.NULL if a broker has not been set yet

    • setBroker

      CustomerEntity setBroker(DatacenterBroker broker)
      Sets a DatacenterBroker that represents the owner of this Vm.
      Specified by:
      setBroker in interface CustomerEntity
      Parameters:
      broker - the DatacenterBroker to set

    • getTotalExecutionTime

      double getTotalExecutionTime()
      Gets the total time (in seconds) the Vm spent executing. It considers the entire VM execution even if in different Hosts it has possibly migrated.
      Specified by:
      getTotalExecutionTime in interface Startable
      Returns:
      the VM total execution time if the VM has stopped, the time executed so far if the VM is running yet, or 0 if it hasn't started.

    • getTimeZone

      double getTimeZone()
      Gets the time zone offset, a value between [TimeZoned.MIN_TIME_ZONE_OFFSET and TimeZoned.MAX_TIME_ZONE_OFFSET], in which the object is physically located. That is the timezone in which the VM is expected to be placed (if there is a Datacenter with enough capacity available at that timezone).

      To know the actual timezone where the VM is placed, check the timezone of the Datacenter of the Host where this is VM placed.

      Specified by:
      getTimeZone in interface TimeZoned
      Returns:
      the expected timezone to place this VM

    • setTimeZone

      Vm setTimeZone(double timeZone)
      Sets the time zone offset between [TimeZoned.MIN_TIME_ZONE_OFFSET and TimeZoned.MAX_TIME_ZONE_OFFSET]. That is the timezone in which the VM is expected to be placed (if there is a Datacenter with enough capacity available at that timezone).
      Specified by:
      setTimeZone in interface TimeZoned
      Parameters:
      timeZone - the new expected time zone offset
      Returns:

    • getLifeTime

      double getLifeTime()
      Gets the Vm Gets lifetime which indicates the maximum execution time.
      Specified by:
      getLifeTime in interface Lifetimed
      Returns:
      the lifeTime (in seconds) or Double.MAX_VALUE indicating no lifeTime is set
      See Also:

    • getBootModel

      BootModel getBootModel()
      Returns the VM boot model. It defines how the VM uses resources such as RAM, CPU and BW during the boot process.
      Returns:
      the VM boot model
      See Also:

    • setBootModel

      Vm setBootModel(BootModel model)
      Sets a model which defines how the VM uses resources such as RAM, CPU and BW during the boot process.

      If a model is not set, no resources are used during the boot time, which is just simulated if a startup delay is set.

      Parameters:
      model - the boot model to set
      Returns:
      this

    • setLifeTime

      Lifetimed setLifeTime(double lifeTime)
      Sets the Vm Sets the lifetime which indicates the maximum execution time. The lifetime must be larger than Datacenter.getSchedulingInterval()..

      The Vm will finish execution as soon as possible, after the given lifeTime has passed, since its Startable.getStartTime() start time}.

      NOTE: If the VM has a lifeTime set, and it's smaller than the Cloudlet lifeTime, the VM lifeTime is used instead of the Cloudlet one.

      Specified by:
      setLifeTime in interface Lifetimed
      Parameters:
      lifeTime - lifeTime to set (in seconds) or Double.MAX_VALUE to indicate there is no lifeTime
      Returns:

    • setStartupDelay

      ExecDelayable setStartupDelay(double delay)
      Set the time (in seconds) for the entity to finish starting up. This is the time the VM takes to boot up.

      INFO: When setting this attribute, call setBootModel(BootModel) first.

      Specified by:
      setStartupDelay in interface ExecDelayable
      Parameters:
      delay -
      Returns:
      See Also:

    • isStartingUp

      default boolean isStartingUp()
      Returns true or false. whether the VM is booting up or not.
      Specified by:
      isStartingUp in interface ExecDelayable
      Returns:
      true or false

    • shutdown

      void shutdown()
      Sends a request to the Datacenter to shut down (destroy) the VM.
      Specified by:
      shutdown in interface ExecDelayable
      See Also: