desmoj.core.advancedModellingFeatures

Class Res

java.lang.Object

desmoj.core.simulator.NamedObject

desmoj.core.simulator.ModelComponent

desmoj.core.simulator.Reportable

desmoj.core.simulator.QueueBased

desmoj.core.advancedModellingFeatures.Res

All Implemented Interfaces:

Subject<QueueBased,QueueBased.QueueAction>

Direct Known Subclasses:

ResourcePoolAnimation

public class Res
extends QueueBased

Res is the place where resources are stored in a pool. Processes can come by and the resource pool will provide() resources to them. Each process has to give back the same resources it once has acquired by calling the takeBack() method of the Res. Res is used to implement process synchronization between processes, which are using resources. The resource pool has a limited capacity. A process can acquire one or more resources and use them. After usage the process must release this or these same resources to make them available to other processes. If a process can not get the number of resources needed, it has to wait in a queue until enough resources are released by other processes. A process can release its resources anytime. After the resourcepool has "takenBack"() the used resources the waiting-queue is checked for processes waiting for them. The first sort criterion of the queue is highest queueing priorities first (i.e. not using scheduling priorities - note that this is a somewhat arbitrary choice, as the Res combines queueing and scheduling features). The second criterion, if a tie-breaker is needed, is the queueing discipline of the underlying queue, e.g. FIFO. The capacity limit can be determined by the user. Res is derived from QueueBased, which provides all the statistical functionality for a queue.

Version:

DESMO-J, Ver. 2.5.1c copyright (c) 2015

Author:

Soenke Claassen Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See Also:

QueueBased

Nested Class Summary

Nested classes/interfaces inherited from class desmoj.core.simulator.QueueBased

QueueBased.QueueAction

Field Summary

Fields inherited from class desmoj.core.simulator.QueueBased

FIFO, LIFO, RANDOM, UNDEFINED

Constructor Summary

Constructors

Constructor and Description
Res(Model owner, java.lang.String name, int capacity, boolean showInReport, boolean showInTrace) Constructor for a Res with a number of initial resources in it.
Res(Model owner, java.lang.String name, int sortOrder, int qCapacity, int capacity, boolean showInReport, boolean showInTrace) Constructor for a Res with a number of initial resources in it.

Method Summary

Modifier and Type	Method and Description
double	avgUsage() Returns the average usage of the Res.
void	changeLimit(int m) Changes the limit of the available resources in the Res.
Reporter	createDefaultReporter() Returns a Reporter to produce a report about this Res.
void	deadlockCheckOff() Turns the deadlock check off.
void	deadlockCheckOn() Turns the deadlock check on.
int	getAvail() Returns the number of resources available in the pool at the moment.
boolean	getDeadlockCheck() Returns if the deadlock check is enabled (true) or not ( false).
long	getidNumber() Returns the ID number of this Res object.
int	getLimit() Returns the initial number of resources in the Res pool.
int	getMinimum() Returns the minimum number of resources in the Res.
boolean	getPassBy() Returns whether entities can pass by other entities which are enqueued before them in the queue.
QueueList<SimProcess>	getQueue() Returns the QueueList actually storing the SimProcesses waiting for resources.
java.lang.String	getQueueStrategy() Returns the implemented queueing discipline of the underlying queue as a String, so it can be displayed in the report.
long	getRefused() Returns the number of entities refused to be enqueued in the queue, because the capacity limit is reached.
long	getUsers() Returns the number of users.
boolean	isDeadlockDetected() Returns true if a deadlock is detected, false otherwise.
boolean	provide(int n) Gets a number of n resources from the Res pool and provides them to the Sim-process to use them.
void	reset() Resets the statistics of this Res.
void	setDeadlockDetected(boolean dlDetected) Sets the boolean field deadlockDetected to the given value.
void	setPassBy(boolean newPassBy) Sets the flag passBy to a new value.
void	takeBack(int n) A process is using this method to put resources it has used back in the Res pool.
void	takeBack(Resource[] returnedRes) A process is using this method to put resources it has used back in the Res pool.

Methods inherited from class desmoj.core.simulator.QueueBased

addObserver, averageLength, averageWaitTime, deleteObserver, getQueueLimit, length, maxLength, maxLengthAt, maxWaitTime, maxWaitTimeAt, minLength, minLengthAt, notifyObservers, setQueueImpWarning, stdDevLength, stdDevWaitTime, zeroWaits

Methods inherited from class desmoj.core.simulator.Reportable

getCorrespondingSchedulable, getDescription, getObservations, getReporter, incrementObservations, incrementObservations, reportIsOn, reportOff, reportOn, resetAt, setCorrespondingSchedulable, setDescription, setReporter

Methods inherited from class desmoj.core.simulator.ModelComponent

current, currentEntity, currentEntityAll, currentEvent, currentModel, currentSimProcess, debugIsOn, debugOff, debugOn, getModel, isExperimentCompatible, isModelCompatible, presentTime, sendDebugNote, sendMessage, sendTraceNote, sendWarning, skipTraceNote, skipTraceNote, traceIsOn, traceOff, traceOn

Methods inherited from class desmoj.core.simulator.NamedObject

getName, getQuotedName, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Res

public Res(Model owner,
           java.lang.String name,
           int sortOrder,
           int qCapacity,
           int capacity,
           boolean showInReport,
           boolean showInTrace)

Constructor for a Res with a number of initial resources in it. The queueing discipline and the capacity limit of the underlying queue can be chosen, too.

Parameters:

owner - Model : The model this Res is associated to.

name - java.lang.String : The Res's name

sortOrder - int : determines the sort order of the underlying queue implementation. Choose a constant from QueueBased like QueueBased.FIFO or QueueBased.LIFO or ...

qCapacity - int : The capacity of the queue, that is how many processes can be enqueued. Zero (0) means unlimited capacity.

capacity - int : The number of resources the Res starts with. Must be positive and greater than 0.

showInReport - boolean : Flag, if Res should produce a report or not.

showInTrace - boolean : Flag for trace to produce trace messages.

Res

public Res(Model owner,
           java.lang.String name,
           int capacity,
           boolean showInReport,
           boolean showInTrace)

Constructor for a Res with a number of initial resources in it. The underlying queue has a Fifo queueing discipline and unlimited capacity.

Parameters:

owner - Model : The model this Res is associated to.

name - java.lang.String : The Res's name

capacity - int : The number of resources the Res starts with. Must be positive and greater than 0.

showInReport - boolean : Flag, if Res should produce a report or not.

showInTrace - boolean : Flag for trace to produce trace messages.

Method Detail

avgUsage

public double avgUsage()

Returns the average usage of the Res. That means: in average, which percentage of the resources were in use over the time?

Returns:

double : the average usage of the resources in the Res.

changeLimit

public void changeLimit(int m)

Changes the limit of the available resources in the Res. Sets the number of the maximum available resources to m. m must be positive. This is only allowed as long as the Res has not been used or the Res has just been reset.

Parameters:

m - int : The new limit (capacity) of the Res. Must be positive.

createDefaultReporter

public Reporter createDefaultReporter()

Returns a Reporter to produce a report about this Res.

Returns:

desmoj.report.Reporter : The Reporter for the queue inside this Res.

deadlockCheckOff

public void deadlockCheckOff()

Turns the deadlock check off. So whenever a SimProcess can not get the resources desired, there won't be checked if a deadlock situation might have occured.

deadlockCheckOn

public void deadlockCheckOn()

Turns the deadlock check on. So whenever a SimProcess can not get the resources desired, it will be checked if a deadlock situation might occur.

getAvail

public int getAvail()

Returns the number of resources available in the pool at the moment.

Returns:

int : The number of resources available at the moment.

getDeadlockCheck

public boolean getDeadlockCheck()

Returns if the deadlock check is enabled (true) or not ( false).

Returns:

boolean :true if the deadlock check is enabled, false if the deadlock check is not enabled

getidNumber

public long getidNumber()

Returns the ID number of this Res object.

Returns:

long : The ID number of this Res object.

getLimit

public int getLimit()

Returns the initial number of resources in the Res pool.

Returns:

int : The initial number of resources in the Res pool at the beginning.

getMinimum

public int getMinimum()

Returns the minimum number of resources in the Res.

Returns:

int : The minimum number of resources in the Res.

getPassBy

public boolean getPassBy()

Returns whether entities can pass by other entities which are enqueued before them in the queue.

Returns:

boolean : Indicates whether entities can pass by other entities which are enqueued before them in the queue.

getQueue

public QueueList<SimProcess> getQueue()

Returns the QueueList actually storing the SimProcesses waiting for resources.

Returns:

desmoj.QueueList : the queue actually storing the SimProcesses waiting for resources.

getQueueStrategy

public java.lang.String getQueueStrategy()

Returns the implemented queueing discipline of the underlying queue as a String, so it can be displayed in the report.

Returns:

String : The String indicating the queueing discipline.

getRefused

public long getRefused()

Returns the number of entities refused to be enqueued in the queue, because the capacity limit is reached.

Returns:

long : The number of entities refused to be enqueued in the queue.

getUsers

public long getUsers()

Returns the number of users.

Returns:

long : The number of Users. That are processes having acquired and released resources.

isDeadlockDetected

public boolean isDeadlockDetected()

Returns true if a deadlock is detected, false otherwise.

Returns:

boolean : is true if a deadlock is detected, false otherwise.

provide

public boolean provide(int n)
                throws SuspendExecution

Gets a number of n resources from the Res pool and provides them to the Sim-process to use them. Hint for developers: calls the private method deliver(). As not enough resources are available at the moment the SimProcess has to wait in a queue until enough products are available again. The order of resource providing (and, thus, process re-activation) depends on the order of the internal queue, which is based on the processes' queueing priorities and (if queueing priorities are equal, requiring a tie-breaker) by FIFO or a different discipline as defined in the constructor.

Parameters:

n - int : The number of resources the resourcepool will provide() to the SimProcess.

Returns:

boolean : Is true if the specified number of resources have been provided successfully, false otherwise (i.e. capacity limit of the queue is reached).

Throws:

SuspendExecution

reset

public void reset()

Resets the statistics of this Res. The number of available resources at this moment and the processes waiting in the queue are not changed. But all statistic counters are reset. The parent QueueBased is also reset.

Overrides:

reset in class QueueBased

setDeadlockDetected

public void setDeadlockDetected(boolean dlDetected)

Sets the boolean field deadlockDetected to the given value. If a deadlock for this Res is detected when an unsuccessfull seize statement for a resource has taken place, then the value of deadlockDetected will be set to true. The value will also been shown in the report of this Res.

Parameters:

dlDetected - boolean : the new value for the field deadlockDetected. Should be true if this Res is involved in a deadlock.

setPassBy

public void setPassBy(boolean newPassBy)

Sets the flag passBy to a new value. PassBy is indicating whether entities can pass by other entities which are enqueued before them in the queue.

Parameters:

newPassBy - boolean : The new value of passBy. Set it to true if you want entities to pass by other entities which are enqueued before them in the queue. Set it to false if you don't want entities to overtake other entities in the queue.

takeBack

public void takeBack(Resource[] returnedRes)

A process is using this method to put resources it has used back in the Res pool. The process can not put more resources back than it has acquired once. The array of returning resources can be provided by the method returnResources() of the class SimProcess.

Parameters:

returnedRes - Resource[] : The array of resources a process is returning to the resource pool. Can't be more resources than it once has acquired!

takeBack

public void takeBack(int n)

A process is using this method to put resources it has used back in the Res pool. The process can not put more resources back than it has acquired once. This method can be used as an alternative to the method takeBack(Resource[] returnedRes) in cases that the user does not want to provide an array of returning resources. This method is also compatible with older DESMO-J Versions.

Parameters:

n - int : The number of resources which should be returned to the Res pool. Can't be more than once were acquired!