desmoj.core.simulator

Class ProcessQueue<P extends SimProcess>

java.lang.Object

desmoj.core.simulator.NamedObject

desmoj.core.simulator.ModelComponent

desmoj.core.simulator.Reportable

desmoj.core.simulator.QueueBased

desmoj.core.simulator.ProcessQueue<P>

All Implemented Interfaces:

Subject<QueueBased,QueueBased.QueueAction>, java.lang.Iterable<P>

Direct Known Subclasses:

ProcessQueueAnimation, SpatialProcessQueue

public class ProcessQueue<P extends SimProcess>
extends QueueBased
implements java.lang.Iterable<P>

ProcessQueue provides models with a ready-to-use element to enqueue SimProcesses in. The sort order of the ProcessQueue is determined first by the priorities of the enqueued SimProcesses and second by the given sort order. The default sort order is FIFO (first in, first out) but others like LIFO (last in, first out) can be chosen, too. See the constants in class QueueBased and the derived classes from QueueList. The capacity of the ProcessQueue, that is the maximum number of SimProcesses enqueued, can be chosen, too. Note that in contrast to the 'plain' queue, this ProcessQueue always expects and returns objects that are derived from class SimProcess. When modelling using the process-, activity-, or transaction-oriented paradigm where SimProcesses are used to represent the model's entities, this ProcessQueue can be used instead of the standard Queue to reduce the amount of casts needed otherwise.

Version:

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

Author:

Tim Lechler, modified by 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, QueueList, QueueListFifo, QueueListLifo

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
ProcessQueue(Model owner, java.lang.String name, boolean showInReport, boolean showInTrace) Constructs a simple priority and FIFO based waiting-queue for SimProcesses with a maximum capacity of 2,147,483,647 waiting processes, which should serve as an approximation of infinite queues sufficiently well for most purposes.
ProcessQueue(Model owner, java.lang.String name, int sortOrder, int qCapacity, boolean showInReport, boolean showInTrace) Constructs a simple priority based waiting-queue for SimProcesses, the kind of queue implementation (FIFO or LIFO) and the capacity of the queue can be chosen.

Method Summary

Modifier and Type	Method and Description
boolean	contains(P p) Returns true if the given SimProcess is contained in the queue; false otherwise.
Reporter	createDefaultReporter() Returns a process-queue-reporter to produce a report about this process-queue.
P	first() Returns the first SimProcess queued in this process-queue or null in case the queue is empty.
P	first(Condition<P> c) Returns the first SimProcess queued in this process-queue that applies to the given condition.
P	get(int index) Returns the SimProcess queued at the named position.
int	get(P p) Returns the queue index of a given SimProcess.
QueueList<P>	getQueueList() Returns the underlying queue implementation, providing access to the QueueList implementation, e.g. to add PropertyChangeListeners.
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.
boolean	insert(P p) Enters a new SimProcess into the ProcessQueue.
boolean	insertAfter(P p, P after) Enters a new SimProcess into the process-queue and places it after the given SimProcess.
boolean	insertBefore(P p, P before) Enters a new SimProcess into the ProcessQueue and places it in front of the given SimProcess.
boolean	isEmpty() Returns a boolean value indicating if the process-queue is empty or if any number of SimProcess is currently enqueued in it.
java.util.Iterator<P>	iterator() Returns an iterator over the processes enqueued.
P	last() Returns the last SimProcess queued in this process-queue or null in case the process-queue is empty.
P	last(Condition<P> c) Returns the last SimProcess queued in this process-queue that applies to the given condition.
P	pred(P p) Returns the SimProcess enqueued directly before the given SimProcess in the process-queue.
P	pred(P p, Condition<P> c) Returns the SimProcess enqueued before the given SimProcess in the process-queue that also fulfills the condition given.
boolean	remove(int index) Removes the process queued at the given position.
void	remove(SimProcess p) Removes the given SimProcess from the process-queue.
void	removeAll() Removes all processes from the Queue.
P	removeFirst() Removes the first process from the queue and provides a reference to this process.
P	removeFirst(Condition<P> c) Removes the first process from the queue that fulfills to the given condition.
P	removeLast() Removes the last process from the queue and provides a reference to this process.
P	removeLast(Condition<P> c) Removes the last process from the queue that fulfills to the given condition, determined by traversing the queue from last to first until a process fulfilling the condition is found.
void	reset() Resets all statistical counters to their default values.
void	setQueueCapacity(int newCapacity) Sets the queue capacity to a new value.
void	setQueueStrategy(int sortOrder) Sets the sort order of this ProcessQueue to a new value and makes this ProcessQueue use another QueueList with the specified queueing discipline.
void	setRefused(long n) Sets the number of entities refused to be enqueued in the queue because the capacity limit is reached to a new value.
int	size() Returns the current length of the Queue.
P	succ(P p) Returns the SimProcess enqueued directly after the given SimProcess in the process-queue.
P	succ(P p, Condition<P> c) Returns the SimProcess enqueued after the given SimProcess in the process-queue that also fulfills the condition given.

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

ProcessQueue

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

Constructs a simple priority based waiting-queue for SimProcesses, the kind of queue implementation (FIFO or LIFO) and the capacity of the queue can be chosen.

The usage of the generic version ProcessQueue<Type> where Type is derived from SimProcess is recommended for type safety. Using the raw type ProcessQueue yields a queue in which any SimProcess can be enqueued, potentially requiring type casting on accessing processes enqueued.

Parameters:

owner - Model : The model this ProcessQueue is associated to

name - java.lang.String : The process-queue's name

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

qCapacity - int : The capacity of the Queue, that is how many processes can be enqueued. Zero (0) can be used as shortcut for for a capacity of Integer.MAX_VALUE = 2,147,483,647, which should approximate an infinite queue sufficiently well for most purposes.

showInReport - boolean : Flag if process-queue should produce a report

showInTrace - boolean : Flag for process-queue to produce trace messages

ProcessQueue

public ProcessQueue(Model owner,
                    java.lang.String name,
                    boolean showInReport,
                    boolean showInTrace)

Constructs a simple priority and FIFO based waiting-queue for SimProcesses with a maximum capacity of 2,147,483,647 waiting processes, which should serve as an approximation of infinite queues sufficiently well for most purposes.

The usage of the generic version ProcessQueue<Type> where Type is derived from SimProcess is recommended for type safety. Using the raw type ProcessQueue yields a queue in which any SimProcess can be enqueued, potentially requiring type casting on accessing processes enqueued.

Parameters:

owner - Model : The model this process-queue is associated to

name - java.lang.String : The process-queue's name

showInReport - boolean : Flag if process-queue should produce a report

showInTrace - boolean : Flag for process-queue to produce trace messages

Method Detail

createDefaultReporter

public Reporter createDefaultReporter()

Returns a process-queue-reporter to produce a report about this process-queue.

Returns:

desmoj.report.Reporter : The reporter for this process-queue

first

public P first()

Returns the first SimProcess queued in this process-queue or null in case the queue is empty.

Returns:

P : The first SimProcess in the process-queue or null if the process-queue is empty

first

public P first(Condition<P> c)

Returns the first SimProcess queued in this process-queue that applies to the given condition. The process-queue is searched from front to end and the first SimProcess that returns true when the condition is applied to it is returned by this method. If no SimProcess applies to the given condition or the process-queue is empty, null will be returned.

Parameters:

c - Condition : The condition that the SimProcess returned must confirm

Returns:

P :The first process queued in this process-queue applying to the given condition or null

contains

public boolean contains(P p)

Returns true if the given SimProcess is contained in the queue; false otherwise.

Parameters:

e - E : The Entity we are looking for in the queue.

Returns:

boolean : True if the given SimProcess is contained in the queue; false otherwise.

size

public int size()

Returns the current length of the Queue.

Returns:

int : The number of processes enqueued.

get

public int get(P p)

Returns the queue index of a given SimProcess.

Returns:

int :The position of the process as an int. Returns -1 if no such position exists.

get

public P get(int index)

Returns the SimProcess queued at the named position. The first position is 0, the last one size()-1.

Returns:

P :The SimProcess at the position of int or null if no such position exists.

getQueueList

public QueueList<P> getQueueList()

Returns the underlying queue implementation, providing access to the QueueList implementation, e.g. to add PropertyChangeListeners.

Returns:

QueueList : The underlying queue implementation of this ProcessQueue.

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.

insert

public boolean insert(P p)

Enters a new SimProcess into the ProcessQueue. If the capacity of the ProcessQueue is full, the entity will not be enqueued and false will be returned. The SimProcess will be stored in the ProcessQueue until method remove(SimProcess p) is called with this specific SimProcess. Simprocesses are ordered according to their priority. Higher priorities are sorted in front of lower priorities. Simprocesses with same priority are orderer according to the strategy specified in the constructor. The first SimProcess inside the process-queue will always be the one with the highest priority.

Parameters:

P - p : The SimProcess to be added to the ProcessQueue

Returns:

boolean : Is true if insertion was successful, false otherwise (i.e. capacity limit is reached).

insertAfter

public boolean insertAfter(P p,
                           P after)

Enters a new SimProcess into the process-queue and places it after the given SimProcess. If the capacity of the ProcessQueue is full, the entity will not be enqueued and false will be returned. Make sure that the SimProcess given as reference is already queued inside the process-queue, else the SimProcess will not be enqueued and false will be returned. The SimProcess will be stored in the ProcessQueue until method remove(SimProcess p) is called with this specific SimProcess.

Parameters:

p - P :The SimProcess to be added to the process-queue

after - P :The SimProcess after which SimProcess 'p' is to be inserted

Returns:

boolean : Is true if insertion was successful, false otherwise (i.e. capacity limit is reached).

insertBefore

public boolean insertBefore(P p,
                            P before)

Enters a new SimProcess into the ProcessQueue and places it in front of the given SimProcess. If the capacity of the ProcessQueue is full, the Entity will not be enqueued and false will be returned. Make sure that the SimProcess given as reference is already queued inside the ProcessQueue, else the SimProcess will not be enqueued and false will be returned. The SimProcess will be stored in the ProcessQueue until method remove(SimProcess p) is called with this specific SimProcess.

Parameters:

p - P : The SimProcess to be added to the processqQueue

before - P : The SimProcess before which the SimProcess 'p' is to be inserted

Returns:

boolean : Is true if insertion was successful, false otherwise (i.e. capacity limit is reached).

isEmpty

public boolean isEmpty()

Returns a boolean value indicating if the process-queue is empty or if any number of SimProcess is currently enqueued in it.

Returns:

boolean : Is true if the process-queue is empty, false otherwise

last

public P last()

Returns the last SimProcess queued in this process-queue or null in case the process-queue is empty.

Returns:

P : The last SimProcess in the process-queue or null if the process-queue is empty

last

public P last(Condition<P> c)

Returns the last SimProcess queued in this process-queue that applies to the given condition. The process-queue is searched from end to front and the first SimProcess that returns true when the condition is applied to it is returned by this method. If no SimProcess applies to the given condition or the process-queue is empty, null will be returned.

Parameters:

c - Condition : The condition that the SimProcess returned must fulfill

Returns:

P : The last SimProcess queued in this process-queue applying to the given condition or null

pred

public P pred(P p)

Returns the SimProcess enqueued directly before the given SimProcess in the process-queue. If the given SimProcess is not contained in this process-queue or is at the first position thus having no possible predecessor, null is returned.

Parameters:

p - P : An SimProcess in the process-queue

Returns:

P : The SimProcess directly before the given SimProcess in the process-queue or null.

pred

public P pred(P p,
              Condition<P> c)

Returns the SimProcess enqueued before the given SimProcess in the process-queue that also fulfills the condition given. If the given SimProcess is not contained in this process-queue or is at the first position thus having no possible predecessor, null is returned. If no other SimProcess before the given one fulfills the condition, null is returned, too.

Parameters:

p - P : A SimProcess in the process-queue

c - Condition : The condition that the preceeding SimProcess has to fulfill

Returns:

P : The SimProcess before the given SimProcess in the process-queue fulfilling to the condition or null.

remove

public void remove(SimProcess p)

Removes the given SimProcess from the process-queue. If the given SimProcess is not in the process-queue, a warning will be issued but nothing else will be changed.

Parameters:

p - P :The SimProcess to be removed from the process-queue

removeAll

public void removeAll()

Removes all processes from the Queue. Has no effect on empty queues.

removeFirst

public P removeFirst()

Removes the first process from the queue and provides a reference to this process. If the queue is empty, null is returned.

Returns:

P : The first process in this queue, which has been removed, or null in case the queue was empty

removeFirst

public P removeFirst(Condition<P> c)

Removes the first process from the queue that fulfills to the given condition. Also provides a reference to this process. If the queue does not contain a process that fulfills the condition (e.g. if the queue is empty), null is returned.

Parameters:

c - Condition : The condition that the process returned must fulfill

Returns:

P : The first process in this queue fulfilling the condition, which has been removed from the queue. Null in case no process fulfills the condition.

removeLast

public P removeLast()

Removes the last process from the queue and provides a reference to this process. If the queue is empty, null is returned.

Returns:

E : The last process in this queue, which has been removed, or null in case the queue was empty

removeLast

public P removeLast(Condition<P> c)

Removes the last process from the queue that fulfills to the given condition, determined by traversing the queue from last to first until a process fulfilling the condition is found. Also provides a reference to this process. If the queue does not contain a process that fulfills the condition (e.g. if the queue is empty), null is returned.

Parameters:

c - Condition : The condition that the entity returned must fulfill

Returns:

P : The last process in this queue fulfilling the condition, which has been removed from the queue. Null in case no process fulfills the condition.

remove

public boolean remove(int index)

Removes the process queued at the given position. The first position is 0, the last one length()-1.

Returns:

: The method returns true if a SimProcess exists at the given position or false> if otherwise.

reset

public void reset()

Resets all statistical counters to their default values. The mininum and maximum length of the queue are set to the current number of queued objects. The counter for the entities refused to be enqueued will be reset.

Overrides:

reset in class QueueBased

setQueueCapacity

public void setQueueCapacity(int newCapacity)

Sets the queue capacity to a new value. Only if the new capacity is equal or larger than the current length of the queue!

Parameters:

newCapacity - int : The new capacity of this ProcessQueue.

setQueueStrategy

public void setQueueStrategy(int sortOrder)

Sets the sort order of this ProcessQueue to a new value and makes this ProcessQueue use another QueueList with the specified queueing discipline. Please choose a constant from QueueBased (QueueBased.FIFO, QueueBased.FIFO or QueueBased.Random) The sort order of a ProcessQueue can only be changed if the queue is empty.

Parameters:

sortOrder - int : determines the sort order of the underlying QueueList implementation (QueueBased.FIFO, QueueBased.FIFO or QueueBased.Random)

setRefused

public void setRefused(long n)

Sets the number of entities refused to be enqueued in the queue because the capacity limit is reached to a new value.

Parameters:

n - long : the new number of entities refused to be enqueued in the queue because the capacity limit is reached.

succ

public P succ(P p)

Returns the SimProcess enqueued directly after the given SimProcess in the process-queue. If the given SimProcess is not contained in this process-queue or is at the last position thus having no possible successor, null is returned.

Parameters:

p - P : A SimProcess in the process-queue

Returns:

P : The SimProcess directly after the given SimProcess in the ProcessQueue or null

succ

public P succ(P p,
              Condition<P> c)

Returns the SimProcess enqueued after the given SimProcess in the process-queue that also fulfills the condition given. If the given SimProcess is not contained in this process-queue or is at the last position thus having no possible successor, null is returned. If no other SimProcess after the given one fulfills the condition, null is returned, too.

Parameters:

p - P : A SimProcess in the process-queue

c - Condition : The condition that the succeeding SimProcess has to fulfill

Returns:

P : The SimProcess after the given SimProcess in the process-queue fulfilling the condition or null.

iterator

public java.util.Iterator<P> iterator()

Returns an iterator over the processes enqueued.

Specified by:

iterator in interface java.lang.Iterable<P extends SimProcess>

Returns:

java.lang.Iterator<P> : An iterator over the processes enqueued.