Package jsl.modeling.resource

Class ResourceUnit

  • All Implemented Interfaces:
    SeizeableIfc, ObservableIfc, GetNameIfc, IdentityIfc
    public class ResourceUnit
extends SchedulingElement
implements SeizeableIfc
    A ResourceUnit is a single unit of a resource. A resource is something that is needed to allocate in the system. A resource unit can be idle (not allocated), busy (allocated), inactive (not available for allocation), failed (not available for allocation due to failure. The resource is initialized to be idle. Thus, prior to and starting at time zero, the resource is idle. A ResourceUnit might have failures processes associated with it. Failure processes must be consistent with the delay option of the resource.

    A ResourceUnit may follow a Schedule. Any schedule changes of a schedule that the resource unit is using is interpreted as the need for an inactive period. Since a resource can follow multiple schedules, there may be conditions where multiple inactive periods are to be handled by the resource unit. The basic rule is that a current inactive period is replaced by the newest incoming inactive period.

    If a resource unit is idle, the resource unit will become inactive upon getting a schedule change. If the resource unit is busy, when told to become inactive, it will wait until the busy period is over (unless preemption is permitted). If there is already a waiting inactive period, the currently waiting inactive period is (silently) replaced by the newest inactive period. If the resource is failed when an inactive period occurs, and if the notice is delayable it will (silently) replace an already inactive period and wait for the failure to end. If it is not delayable, it will be silently cancelled. If an inactive period occurs and the resource is already experiencing an inactive period the current inactive period is replaced (canceled) and the new inactive period started. The net effect is that the resource can only experience one inactive period at a time and newer inactive periods replace the current or waiting inactive period based on the state of the resource. If a failure occurs during an idle period, the resource is immediately put in the failed state. If a failure occurs during a busy period, the failure will wait until after the current request is finished if the allow failure delay option is true. If the failure delay option is false then then an attempt will be made to preempt the current request. If the request permits preemption via its preemption rule, it will be preempted. If not, an IllegalStateException will occur. If multiple failure notices occur they will be queued. Additional statistics can be reported on state changes and request processing.

    • Constructor Detail

      • ResourceUnit

        public ResourceUnit​(ModelElement parent,
                    java.lang.String name,
                    boolean failureDelayOption,
                    Queue.Discipline failuresQDiscipline,
                    boolean failureQStatOption,
                    boolean requestQCancelStatOption,
                    boolean inactivePeriodDelayOption,
                    boolean stateStatOption,
                    boolean requestStatOption,
                    Queue.Discipline requestQDiscipline,
                    boolean requestQStatsOption)
        It is highly recommended that the Resource.Builder class be used to construction ResourceUnits. This generic public method is available primarily to simplify sub-classing
        Parameters:
        parent - the model element parent
        name - the name
        failureDelayOption - whether failures can delay
        failuresQDiscipline - the discipline for failures
        failureQStatOption - whether failure enterWaitingState statistics are collected
        requestQCancelStatOption - whether request statistics are collected when the request is canceled
        inactivePeriodDelayOption - whether inactive periods can delay
        stateStatOption - whether statistics are collected on resource states
        requestStatOption - whether request statistics are collected
        requestQDiscipline - the enterWaitingState discipline for requests
        requestQStatsOption - whether enterWaitingState statistics are collected

    • Method Detail

      • initialize

        protected void initialize()
        Description copied from class: ModelElement
        This method should be overridden by subclasses that need actions performed to initialize prior to a replication. It is called once before each replication occurs if the model element wants initialization. It is called after beforeReplication() is called
        Overrides:
        initialize in class ModelElement

      • warmUp

        protected void warmUp()
        Description copied from class: ModelElement
        This method should be overridden by subclasses that need actions performed at the warm up event during each replication. It is called once during each replication if the model element reacts to warm up actions.
        Overrides:
        warmUp in class ModelElement

      • replicationEnded

        protected void replicationEnded()
        Description copied from class: ModelElement
        This method should be overridden by subclasses that need actions performed when the replication ends and prior to the calling of afterReplication() . It is called when each replication ends and can be used to collect data from the the model element, etc.
        Overrides:
        replicationEnded in class ModelElement

      • addTimeBasedFailure

        public TimeBasedFailure addTimeBasedFailure​(RandomIfc failureDuration,
                                            RandomIfc timeBtwFailures)
        Creates and adds a TimeBasedFailure to the ResourceUnit. The failure process will not start automatically
        Parameters:
        failureDuration - the time to spend down
        timeBtwFailures - the time between failures
        Returns:
        the TimeBasedFailure

      • addTimeBasedFailure

        public TimeBasedFailure addTimeBasedFailure​(RandomIfc failureDuration,
                                            RandomIfc timeToFirstFailure,
                                            RandomIfc timeBtwFailures)
        Creates and adds a TimeBasedFailure to the ResourceUnit. The failure process will start automatically when the replication is initialized.
        Parameters:
        failureDuration - the time to spend down
        timeToFirstFailure - the time of the first failure
        timeBtwFailures - the time between failures
        Returns:
        the TimeBasedFailure

      • addTimeBasedFailure

        public TimeBasedFailure addTimeBasedFailure​(RandomIfc failureDuration,
                                            RandomIfc timeToFirstFailure,
                                            RandomIfc timeBtwFailures,
                                            java.lang.String name)
        Creates and adds a TimeBasedFailure to the ResourceUnit.
        Parameters:
        failureDuration - the time to spend down
        timeToFirstFailure - the time of the first failure
        timeBtwFailures - the time between failures
        name - the name of the failures
        Returns:
        the TimeBasedFailure

      • getFailureQDiscipline

        public final Queue.Discipline getFailureQDiscipline()
        Returns:
        the enterWaitingState discipline of the failures if they can wait

      • getFailureQStatOption

        public final boolean getFailureQStatOption()
        Returns:
        true if statistics are reported on the failure enterWaitingState

      • getRequestQStatOption

        public final boolean getRequestQStatOption()
        Returns:
        true if statistics are reported on the request enterWaitingState

      • getCollectStateStatsOption

        public final boolean getCollectStateStatsOption()
        Returns:
        true if state statistics are collected

      • getRequestQCancelStatOption

        public final boolean getRequestQCancelStatOption()
        The default is false
        Returns:
        true means enter waiting state statistics include statistics on requests that were canceled.

      • getRequestStatisticsOption

        public final boolean getRequestStatisticsOption()
        Returns:
        true if statistics are collected on individual requests

      • isRequestWaiting

        public final boolean isRequestWaiting​(Request request)
        Parameters:
        request - the request to check, must not be null
        Returns:
        true if the request is in the resource's request queue

      • getCurrentRequest

        public final java.util.Optional<Request> getCurrentRequest()
        The request that is currently using the unit
        Returns:
        an Optional

      • getFailureDelayOption

        public final boolean getFailureDelayOption()
        Returns:
        returns true if attached FailureProcesss that allow failure delays are allowed to be attached to the resource

      • getInactivePeriodDelayOption

        public final boolean getInactivePeriodDelayOption()
        Returns:
        true if inactive periods caused by a Schedule are allowed to delay before occurring.

      • asString

        public java.lang.String asString()
        Description copied from class: ModelElement
        Allows sub-classes to provide more detail than toString() to represent the ModelElement as a String
        Overrides:
        asString in class ModelElement
        Returns:
        a detailed String representation

      • hasFailureProcesses

        public final boolean hasFailureProcesses()
        Returns:
        true if FailureProcesses have been added to the unit

      • isIdle

        public final boolean isIdle()
        Checks if the resource is idle.
        Returns:
        true if idle, false otherwise

      • isBusy

        public final boolean isBusy()
        Checks to see if the resource is busy
        Returns:
        true if current state is busy

      • isFailed

        public final boolean isFailed()
        Checks if the resource is failed
        Returns:
        true if idle, false otherwise

      • isInactive

        public final boolean isInactive()
        Checks to see if the resource is inactive
        Returns:
        true if current state is inactive

      • isPreviousStateIdle

        public final boolean isPreviousStateIdle()
        Checks if the resource was idle.
        Returns:
        true if idle, false otherwise

      • isPreviousStateBusy

        public final boolean isPreviousStateBusy()
        Checks to see if the resource was busy
        Returns:
        true if previous state was busy

      • isPreviousStateFailed

        public final boolean isPreviousStateFailed()
        Checks if the resource was failed
        Returns:
        true if idle, false otherwise

      • isPreviousStateInactive

        public final boolean isPreviousStateInactive()
        Checks to see if the resource was inactive
        Returns:
        true if previous state was inactive

      • isPreemptionRuleCompatible

        public boolean isPreemptionRuleCompatible​(Request request)
        Checks if the preemption rule of the request is compatible with the failure delay option. If the request doesn't allow preemption and failures cannot be delayed, this means that the request will be rejected.
        Parameters:
        request - the request to check
        Returns:
        true if compatible

      • seize

        public final Request seize​(RequestReactorIfc reactor)
        The default preemption rule is RESUME. Creates a simple request and seizes the resource for an indefinite amount of time. A convenience method to combine request building and seizing.
        Parameters:
        reactor - the reactor to use
        Returns:
        the request

      • seize

        public final Request seize​(RequestReactorIfc reactor,
                           double time)
        The default preemption rule is RESUME. Creates a simple request and seizes the resource. A convenience method to combine request building and seizing.
        Parameters:
        reactor - the reactor to use
        time - the time duration for the request
        Returns:
        the request

      • seize

        public final Request seize​(RequestReactorIfc reactor,
                           double time,
                           java.lang.Object entity)
        The default preemption rule is RESUME. Creates a simple request and seizes the resource. A convenience method to combine request building and seizing.
        Parameters:
        reactor - the reactor to use
        time - the time duration for the request
        entity - the object associated with the request
        Returns:
        the request

      • seize

        public final Request seize​(RequestReactorIfc reactor,
                           GetValueIfc timeValueGetter)
        The default preemption rule is RESUME. Creates a simple request and seizes the resource. A convenience method to combine request building and seizing.
        Parameters:
        reactor - the reactor to use
        timeValueGetter - the time duration for the request
        Returns:
        the request

      • seize

        public final Request seize​(RequestReactorIfc reactor,
                           GetValueIfc timeValueGetter,
                           java.lang.Object entity)
        The default preemption rule is RESUME. Creates a simple request and seizes the resource. A convenience method to combine request building and seizing.
        Parameters:
        reactor - the reactor to use
        timeValueGetter - the time duration for the request
        entity - the object associated with the request
        Returns:
        the request

      • seize

        public final Request seize​(RequestReactorIfc reactor,
                           GetValueIfc timeValueGetter,
                           Request.PreemptionRule rule,
                           java.lang.Object entity)
        Creates a simple request using Request default values and seizes the resource unit. A convenience method to combine request building and seizing.
        Parameters:
        reactor - the reactor to use
        timeValueGetter - the time duration for the request
        rule - the rule
        entity - the object associated with the request
        Returns:
        the request

      • seize

        public final Request seize​(Request request)
        Causes the request to enter the resource. If the resource is idle, the request will be using the resource. If the resource is not idle the request will wait. A Request will be rejected if its preemption rule is NONE and the ResourceUnit's failure delay option is false. This implies that the Request cannot be processed by the ResourceUnit because the request cannot be preempted and the resource unit does not permit its failures to delay (i.e. they must preempt).
        Specified by:
        seize in interface SeizeableIfc
        Parameters:
        request - a request made by this unit, must not be null
        Returns:
        the request is returned to emphasize that the user may want to check its state

      • cancel

        protected final void cancel​(Request request)
        Causes the resource to cancel the request. The request must have been made by this resource. Called from Request
        Parameters:
        request - a request made by this unit

      • release

        protected final void release​(Request request)
        Causes the resource to immediately finish the request. The request must have been made by this resource. Called from Request
        Parameters:
        request - the request

      • getTotalSeizes

        public final int getTotalSeizes()
        Returns:
        the number of times that the resource has been seized

      • getTotalTimeBusy

        public final double getTotalTimeBusy()
        Returns:
        the total time that the resource has been busy

      • getTotalTimeIdle

        public final double getTotalTimeIdle()
        Returns:
        the total time that the resource has been idle

      • getRequestQStatus

        public final Queue.Status getRequestQStatus()

      • getQRequestQResponses

        public final java.util.Optional<QueueResponse<Request>> getQRequestQResponses()

      • getUnmodifiableListforRequestQ

        public final java.util.List<Request> getUnmodifiableListforRequestQ()

      • changeRequestQDiscipline

        public final void changeRequestQDiscipline​(Queue.Discipline discipline)

      • getCurrentRequestQDiscipline

        public final Queue.Discipline getCurrentRequestQDiscipline()

      • changeRequestQPriority

        public final void changeRequestQPriority​(Request qObject,
                                         int priority)

      • getInitialRequestQDiscipline

        public final Queue.Discipline getInitialRequestQDiscipline()

      • setInitialRequestQDiscipline

        public final void setInitialRequestQDiscipline​(Queue.Discipline discipline)

      • requestQSize

        public final int requestQSize()

      • isRequestQEmpty

        public final boolean isRequestQEmpty()
        Returns:
        true if the request queue is empty

      • getTimeExitedIdle

        public final double getTimeExitedIdle()
        Returns:
        the time the idle state was last exited

      • getTimeEnteredIdle

        public final double getTimeEnteredIdle()
        Returns:
        the time the idle state was last entered

      • getTimeEnteredBusy

        public final double getTimeEnteredBusy()
        Returns:
        the time the busy state was last entered

      • getTimeExitedBusy

        public final double getTimeExitedBusy()
        Returns:
        the time the busy state was last exited

      • getTimeEnteredFailed

        public final double getTimeEnteredFailed()
        Returns:
        the time the failed state was last entered

      • getTimeExitedFailed

        public final double getTimeExitedFailed()
        Returns:
        the time the failed state was last exited

      • getTimeEnteredInactive

        public final double getTimeEnteredInactive()
        Returns:
        the time the inactive state was last entered

      • getTimeExitedInactive

        public final double getTimeExitedInactive()
        Returns:
        the time the inactive state was last exited

      • getNumTimesBusyExited

        public final double getNumTimesBusyExited()
        Returns:
        number of times the busy state was exited

      • getNumTimesBusyEntered

        public final double getNumTimesBusyEntered()
        Returns:
        number of times the busy state was entered

      • getNumTimesIdleExited

        public final double getNumTimesIdleExited()
        Returns:
        number of times the idle state was exited

      • getNumTimesIdleEntered

        public final double getNumTimesIdleEntered()
        Returns:
        number of times the idle state was entered

      • getNumTimesFailedExited

        public final double getNumTimesFailedExited()
        Returns:
        number of times the failed state was exited

      • getNumTimesFailedEntered

        public final double getNumTimesFailedEntered()
        Returns:
        number of times the failed state was entered

      • getNumTimesInactiveExited

        public final double getNumTimesInactiveExited()
        Returns:
        number of times the inactive state was exited

      • getNumTimesInactiveEntered

        public final double getNumTimesInactiveEntered()
        Returns:
        number of times the inactive state was entered

      • getTotalTimeFailed

        public final double getTotalTimeFailed()
        Returns:
        the total time that the resource has been failed

      • getTotalTimeInactive

        public final double getTotalTimeInactive()
        Returns:
        the total time that the resource has been inactive

      • getTotalTime

        public final double getTotalTime()
        Returns:
        the total time that the resource has been idle, busy, failed, or inactive

      • setState

        protected final void setState​(ResourceUnit.ResourceState state)
        Sets the state of the resource and notifies observers
        Parameters:
        state - the state

      • notifyFailureProcesses

        protected final void notifyFailureProcesses()
        Called from setState(). Notifies all attached FailureProcesses of the specifics of the state change so that they may react to the change in state. The reason that FailureProcesses are notified of the state change is to allow them to react accordingly. For example, if the resource is failed, a failure process might not accrue time toward failing again. In other words, the failure process may depend on the state of the resource

      • getCurrentFailureNotice

        protected final FailureNotice getCurrentFailureNotice()
        Returns:
        the current notice if the unit is failed or null

      • checkForWorkAfterRequestCompletion

        protected void checkForWorkAfterRequestCompletion()
        Checks if there something to do after a request is completed. The order of checking is:

        1) if there are both pending failures or pending inactive periods process the one that occurred first

        2) process pending requests

        3) if none of the above go idle

        Note: there cannot be a preemption pending after a normal request is completed.

      • checkForWorkAfterFailureNoticeCompletion

        protected void checkForWorkAfterFailureNoticeCompletion()
        Checks if there something to do after a failure notice is completed. Note that failure processing is given preference after a failure has occurred. The order of checking is:

        1) process pending failures

        2) process pending inactivity

        3) process a preemption

        4) process pending requests

        5) if none of the above go idle

      • isPreemptionWaiting

        public final boolean isPreemptionWaiting()
        Returns:
        true if there is a request that was preempted waiting

      • isFailureNoticeWaiting

        public final boolean isFailureNoticeWaiting()
        Returns:
        true if there is a failure notice that needs processing

      • isRequestWaiting

        public final boolean isRequestWaiting()
        Returns:
        true if there is a request that needs processing

      • isInactivePeriodPending

        public final boolean isInactivePeriodPending()
        Returns:
        true if there is a pending inactive period that needs processing

      • processPreemption

        protected void processPreemption()
        Processes the pending preemption

      • processNextRequest

        protected void processNextRequest()
        Processes the next request

      • processNextFailureNotice

        protected void processNextFailureNotice()
        Processes the next failure notice

      • processNextInactiveNotice

        protected void processNextInactiveNotice()
        Checks if there are waiting inactive period notices and processes the next one if there is one.

      • getNextInactivePeriodNotice

        protected InactivePeriodNotice getNextInactivePeriodNotice()
        Returns:
        the next inactive period needing processing or null

      • getNextFailureNotice

        protected FailureNotice getNextFailureNotice()
        Returns:
        the next failure notice needing processing or null

      • getNextRequest

        protected Request getNextRequest()
        Returns:
        the next request needing processing or null

      • collectFinalRequestStatistics

        protected void collectFinalRequestStatistics​(Request request)
        Collects statistics on requests after they have been completed, rejected, or canceled.
        Parameters:
        request - the request

      • scheduleEndOfFailure

        protected void scheduleEndOfFailure​(FailureNotice failureNotice)
        Places the unit in the failed state using the supplied failure notice
        Parameters:
        failureNotice - the notice

      • getCurrentDownTimeEvent

        protected final JSLEvent getCurrentDownTimeEvent()
        Returns the current down time event if it has been scheduled
        Returns:
        the event

      • scheduleEndOfService

        protected void scheduleEndOfService​(Request request)
        Causes the unit to become busy, makes the request the current request that is being processed and schedules the ending of the processing of the request
        Parameters:
        request - the request

      • scheduleEndOfInactivePeriod

        protected void scheduleEndOfInactivePeriod​(InactivePeriodNotice notice)

      • enqueueIncomingRequest

        protected void enqueueIncomingRequest​(Request request)
        Causes the request to wait in the request enterWaitingState
        Parameters:
        request - the request

      • enqueueIncomingFailureNotice

        protected void enqueueIncomingFailureNotice​(FailureNotice failureNotice)
        Causes an incoming failure notice to wait
        Parameters:
        failureNotice - the failure notice

      • failedWhileBusy

        protected void failedWhileBusy​(FailureNotice failureNotice)
        Handles what to do if the resource is told to fail while busy
        Parameters:
        failureNotice - the failure notice that caused the failure

      • failedWhileInactive

        protected void failedWhileInactive​(FailureNotice notice)
        Handles what to do if the resource is told to fail while inactive. The default behavior has the failure delay if it can be delayed; otherwise, it is ignored
        Parameters:
        notice - the failure notice

      • failedWhileFailed

        protected void failedWhileFailed​(FailureNotice notice)
        Handles what to do if the resource is told to fail while already failed. The default behavior has the failure delay if it can be delayed; otherwise, it is ignored, i.e. if the resource gets a failure notice when it is already failed, the notice is ignored (unless the notices are allowed to be delayed).
        Parameters:
        notice - the failure notice

      • inactivateWhileBusy

        protected void inactivateWhileBusy​(InactivePeriodNotice notice)
        Handles what to do if the resource is told to be inactive while busy, If the current request can be preempted, it is preempted and the inactive period begins immediately. If the current request cannot be delayed, the incoming request is checked if it can be delayed. If so, it replaces any pending inactive periods and becomes the pending period. In this case the previous pending notice is canceled. If the request and the notice both cannot be delayed, then an exception is thrown.
        Parameters:
        notice - the inactive period notice

      • inactivateWhileFailed

        protected void inactivateWhileFailed​(InactivePeriodNotice notice)
        Handles what to do if the resource is told to be inactive while failed. If the new notice can be delayed and if there already is a pending inactive period, the pending one is ignored and the new one becomes the pending period. If the incoming notice cannot be delayed, then it is canceled.
        Parameters:
        notice - the notice

      • inactivateWhileInactive

        protected void inactivateWhileInactive​(InactivePeriodNotice notice)
        Handles the arrival of a new inactive period notice, while the resource is already inactive. Since only one inactive period can be waiting at any time, this means that the current period was delayed so much that the next one arrived before the current was able to be completed. The default behavior is to cancel the current period and allow the new period to proceed in full. The state remains inactive.
        Parameters:
        notice - the notice

      • activateWhenInactive

        protected void activateWhenInactive​(InactivePeriodNotice notice)
        Called from activateWhenInActive()
        Parameters:
        notice - the notice

      • preemptCurrentRequest

        protected void preemptCurrentRequest()
        How to preempt the current request. Called from failedWhileBusy()

      • preemptResumableRequest

        protected void preemptResumableRequest()
        Called from preemptCurrentRequest(). How to preempt a request that can be resumed.

      • preemptCancelableRequest

        protected void preemptCancelableRequest()
        Called from preemptCurrentRequest(). How to preempt a request that must be canceled.

      • preemptRequest

        protected void preemptRequest()
        Called from preemptRestartableRequest() and preemptResumableRequest() because the behavior is currently the same.

      • preemptRestartableRequest

        protected void preemptRestartableRequest()
        Called from preemptCurrentRequest(). How to preempt a request that must be restarted.

      • hasSchedules

        public final boolean hasSchedules()
        Returns:
        true if the resource unit has schedules registered

      • useSchedule

        public final void useSchedule​(Schedule schedule)
        Tells the resource to listen and react to changes in the supplied Schedule. Any scheduled items on the schedule will be interpreted as changes to make the resource become inactive. Note the implications of having more that one schedule in the class documentation.
        Parameters:
        schedule - the schedule to use, must not be null

      • isUsingSchedule

        public final boolean isUsingSchedule​(Schedule schedule)
        Returns:
        true if already using the supplied Schedule

      • stopUsingSchedule

        public final void stopUsingSchedule​(Schedule schedule)
        If the resource is using a schedule, the resource stops listening for schedule changes and is no longer using a schedule

      • receiveInactivePeriodNotice

        protected void receiveInactivePeriodNotice​(InactivePeriodNotice notice)
        Called from scheduledItemStarted() when a Schedule notifies of an item (period) beginning
        Parameters:
        notice - the notice