Overview | Package | Class | Tree | Deprecated | Index | Help
| SSJ V. 2.1.1.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 which 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 unitization (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 is 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 is 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

Overview | Package | Class | Tree | Deprecated | Index | Help
| SSJ V. 2.1.1.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

To submit a bug or ask questions, send an e-mail to Pierre L'Ecuyer.