umontreal.iro.lecuyer.simprocs
Class Resource

java.lang.Object
  umontreal.iro.lecuyer.simprocs.Resource

public class Resource
extends Object

Objects of this class are resources having limited capacity, and which can be requested and released by Process objects. These resources act indirectly as synchonization devices for processes.

A resource is created with a finite capacity, specified when invoking the Resource constructor, and can be changed later on. A resource also has an infinite-capacity queue (waiting line) and a service policy that defaults to FIFO and can be changed later on.

A process must ask for a certain number of units of the resource (request), and obtain it before using it. When it is done with the resource, the process must release it so that others can use it (release). A process does not have to request [release] all the resource units that it needs by a single call to the request [release] method. It can make several successive requests or releases, and can also hold different resources simultaneously.

Each resource maintains two lists: one contains the processes waiting for the resource (the waiting queue) and the other contains the processes currently holding units of this resource. The methods waitList and servList permit one to access these two lists. These lists actually contain objects of the class UserRecord instead of SimProcess objects.

Constructor Summary

Resource(int capacity)
Constructs a new resource linked with the default simulator, with initial capacity capacity, and service policy FIFO.

Resource(int capacity, String name)
Constructs a new resource linked with the default simulator, with initial capacity capacity, service policy FIFO, and identifier name.

Resource(ProcessSimulator sim, int capacity)
Constructs a new resource linked with the simulator sim, with initial capacity capacity, and service policy FIFO.

Resource(ProcessSimulator sim, int capacity, String name)
Constructs a new resource linked with the simulator sim, with initial capacity capacity, service policy FIFO, and identifier (or name) name.

Method Summary

void	changeCapacity(int diff) Modifies by diff units (increases if diff > 0, decreases if diff < 0) the capacity (i.e., the number of units) of the resource.
int	getAvailable() Returns the number of available units, i.e., the capacity minus the number of units busy.
int	getCapacity() Returns the current capacity of the resource.
String	getName() Returns the name (or identifier) associated to this resource.
void	init() Reinitializes this resource by clearing up its waiting list and service list.
void	initStat() Reinitializes all the statistical collectors for this resource.
void	release(int n) The executing process that invokes this method releases n units of the resource.
String	report() Returns a string containing a complete statistical report on this resource.
void	request(int n) The executing process invoking this method requests for n units of this resource.
LinkedListStat	servList() Returns the list that contains the UserRecord objects for the processes in the service list for this resource.
void	setCapacity(int newcap) Sets the capacity to newcap.
void	setPolicyFIFO() Set the service policy to FIFO (first in, first out): the processes are placed in the list (and served) according to their order of arrival.
void	setPolicyLIFO() Set the service policy to LIFO (last in, first out): the processes are placed in the list (and served) according to their inverse order of arrival, the last arrived are served first.
void	setStatCollecting(boolean b) Starts or stops collecting statistics on the lists returned by waitList and servList for this resource.
Accumulate	statOnCapacity() Returns the statistical collector that measures the evolution of the capacity of the resource as a function of time.
Tally	statOnSojourn() Returns the statistical collector for the sojourn times of the UserRecord for this resource.
Accumulate	statOnUtil() Returns the statistical collector for the utilization of the resource (number of units busy) as a function of time.
LinkedListStat	waitList() Returns the list that contains the UserRecord objects for the processes in the waiting list for this resource.

Methods inherited from class java.lang.Object

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

Constructor Detail

Resource

public Resource(int capacity)

Constructs a new resource linked with the default simulator, with initial capacity capacity, and service policy FIFO.

Parameters:

capacity - initial capacity of the resource

Resource

public Resource(ProcessSimulator sim,
                int capacity)

Constructs a new resource linked with the simulator sim, with initial capacity capacity, and service policy FIFO.

Parameters:

sim - current simulator of the variable

capacity - initial capacity of the resource

Resource

public Resource(int capacity,
                String name)

Constructs a new resource linked with the default simulator, with initial capacity capacity, service policy FIFO, and identifier name.

Parameters:

capacity - initial capacity of the resource

name - identifier or name of the resource

Resource

public Resource(ProcessSimulator sim,
                int capacity,
                String name)

Constructs a new resource linked with the simulator sim, with initial capacity capacity, service policy FIFO, and identifier (or name) name.

Parameters:

sim - current simulator of the variable

capacity - initial capacity of the resource

name - identifier or name of the resource

Method Detail

setStatCollecting

public void setStatCollecting(boolean b)

Starts or stops collecting statistics on the lists returned by waitList and servList for this resource. If the statistical collection is turned ON, the method also constructs (if not yet done) and initializes three additional statistical collectors for this resource. These collectors will be updated automatically. They can be accessed via statOnCapacity, statOnUtil, and statOnSojourn, respectively. The first two, of class Accumulate, monitor the evolution of the capacity and of the utilization (number of units busy) of the resource as a function of time. The third one, of class Tally, collects statistics on the processes sojourn times (wait + service); it samples a new value each time a process releases all the units of this resource that it holds (i.e., when its UserRecord disappears).

Parameters:

b - true to turn statistical collecting ON, false to turn it OFF

initStat

public void initStat()

Reinitializes all the statistical collectors for this resource. These collectors must exist, i.e., setStatCollecting (true) must have been invoked earlier for this resource.

init

public void init()

Reinitializes this resource by clearing up its waiting list and service list. The processes that were in these lists (if any) remain in the same states. If statistical collection is ``on'', initStat is invoked as well.

getCapacity

public int getCapacity()

Returns the current capacity of the resource.

Returns:

the capacity of the resource

setPolicyFIFO

public void setPolicyFIFO()

Set the service policy to FIFO (first in, first out): the processes are placed in the list (and served) according to their order of arrival.

setPolicyLIFO

public void setPolicyLIFO()

Set the service policy to LIFO (last in, first out): the processes are placed in the list (and served) according to their inverse order of arrival, the last arrived are served first.

changeCapacity

public void changeCapacity(int diff)

Modifies by diff units (increases if diff > 0, decreases if diff < 0) the capacity (i.e., the number of units) of the resource. If diff > 0 and there are processes in the waiting list whose request can now be satisfied, they obtain the resource. If diff < 0, there must be at least diff units of this resource available, otherwise an illegal argument exception will be thrown, printing an error message (this is not a strong limitation, because one can check first and release some units, if needed, before invoking changeCapacity). In particular, the capacity of a resource can never become negative.

Parameters:

diff - number of capacity units to add to the actual capacity, can be negative to reduce the capacity

Throws:

IllegalArgumentException - if diff is negative and the capacity cannot be reduced as required

IllegalStateException - if diff is negative and the capacity could not be reduced due to a lack of available units

setCapacity

public void setCapacity(int newcap)

Sets the capacity to newcap. Equivalent to changeCapacity (newcap - old) if old is the current capacity.

Parameters:

newcap - new capacity of the resource

Throws:

IllegalArgumentException - if the passed capacity is negative

IllegalStateException - if diff is negative and the capacity could not be reduced due to a lack of available units

getAvailable

public int getAvailable()

Returns the number of available units, i.e., the capacity minus the number of units busy.

Returns:

the number of available units

request

public void request(int n)

The executing process invoking this method requests for n units of this resource. If there are enough units available to fill up the request immediately, the process obtains the desired number of units and holds them until it invokes release for this same resource. The process is also inserted into the servList list for this resource. On the other hand, if there are less than n units of this resource available, the executing process is placed into the waitList list (the queue) for this resource and is suspended until it can obtain the requested number of units of the resource.

Parameters:

n - number of required units

release

public void release(int n)

The executing process that invokes this method releases n units of the resource. If this process is holding exactly n units, it is removed from the service list of this resource and its UserRecord object disappears. If this process is holding less than n units, the program throws an illegal argument exception. If there are other processes waiting for this resource whose requests can now be satisfied, they obtain the resource.

Parameters:

n - number of released units

Throws:

IllegalArgumentException - if the process did not request n units before releasing them

waitList

public LinkedListStat waitList()

Returns the list that contains the UserRecord objects for the processes in the waiting list for this resource.

Returns:

the list of process user records waiting for the resource

servList

public LinkedListStat servList()

Returns the list that contains the UserRecord objects for the processes in the service list for this resource.

Returns:

the list of process user records using this resource

statOnCapacity

public Accumulate statOnCapacity()

Returns the statistical collector that measures the evolution of the capacity of the resource as a function of time. This collector exists only if setStatCollecting (true) has been invoked previously.

Returns:

the probe for resource capacity

statOnUtil

public Accumulate statOnUtil()

Returns the statistical collector for the utilization of the resource (number of units busy) as a function of time. This collector exists only if setStatCollecting (true) has been invoked previously. The utilization rate of a resource can be obtained as the time average computed by this collector, divided by the capacity of the resource. The collector returned by servList().statSize() tracks the number of UserRecord in the service list; it differs from this collector because a process may hold more than one unit of the resource by given UserRecord.

Returns:

the probe for resource utilization

statOnSojourn

public Tally statOnSojourn()

Returns the statistical collector for the sojourn times of the UserRecord for this resource. This collector exists only if setStatCollecting (true) has been invoked previously. It gets a new observation each time a process releases all the units of this resource that it had requested by a single request call.

Returns:

the probe for the sojourn times

getName

public String getName()

Returns the name (or identifier) associated to this resource. If it was not given upon resource construction, this returns null.

Returns:

the name associated to this resource, or null if it was not given

report

public String report()

Returns a string containing a complete statistical report on this resource. The method setStatCollecting (true) must have been invoked previously, otherwise no statistics have been collected. The report contains statistics on the waiting times, service times, and waiting times for this resource, on the capacity, number of units busy, and size of the queue as a function of time, and on the utilization rate.

Returns:

a statistical report for this resource, represented as a string