desmoj.core.simulator

Class Queue<E extends Entity>

java.lang.Object

desmoj.core.simulator.NamedObject

desmoj.core.simulator.ModelComponent

desmoj.core.simulator.Reportable

desmoj.core.simulator.QueueBased

desmoj.core.simulator.Queue<E>

All Implemented Interfaces:

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

Direct Known Subclasses:

QueueAnimation, SpatialQueue

public class Queue<E extends Entity>
extends QueueBased
implements java.lang.Iterable<E>

Queue provides models with a ready-to-use modelling element to enqueue entities in. The sort order of the queue is determined first by the priorities of the enqueued entities 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 Queue, that is the maximum number of entities enqueued, can be chosen, too.

For queueing SimProcesses the usage of class ProcessQueue is recommended.

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, ProcessQueue

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
Queue(Model owner, java.lang.String name, boolean showInReport, boolean showInTrace) Constructs a simple priority and FIFO based waiting-queue for entities with a maximum capacity of 2,147,483,647 waiting entities, which should serve as an approximation of infinite queues sufficiently well for most purposes.Note that since SimProcesses are derived from Entities, they can be queued inside this queue, too.
Queue(Model owner, java.lang.String name, int sortOrder, int qCapacity, boolean showInReport, boolean showInTrace) Constructs a simple priority based waiting-queue for entities, the kind of queue sort order and the capacity of the queue can be chosen.

Method Summary

Modifier and Type	Method and Description
boolean	contains(E e) Returns true if the given Entity is contained in the queue; false otherwise.
Reporter	createDefaultReporter() Returns a special queue reporter to produce a report about this queue.
E	first() Returns the first entity queued in this queue or null in case the queue is empty.
E	first(Condition<E> c) Returns the first entity queued in this queue that fulfills the given condition.
int	get(E e) Returns the queue index of a given Entity.
E	get(int index) Returns the Entity queued at the named position.
QueueList<E>	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.
boolean	insert(E e) Enters a new Entity into the queue.
boolean	insertAfter(E e, E after) Enters a new Entity into the queue and places it after the given Entity.
boolean	insertBefore(E e, E before) Enters a new Entity into the queue and places it in front of the given Entity.
boolean	isEmpty() Returns a boolean value indicating if the queue is empty or if any number of entities is currently enqueued in it.
java.util.Iterator<E>	iterator() Returns an iterator over the entities enqueued.
E	last() Returns the last Entity queued in this queue or null in case the queue is empty.
E	last(Condition<E> c) Returns the last Entity queued in this queue that fulfills the given condition.
E	pred(E e) Returns the entity enqueued directly before the given Entity in the queue.
E	pred(E e, Condition<E> c) Returns the entity enqueued before the given Entity in the queue that also fulfills the condition given.
void	remove(Entity e) Removes the given Entity from the Queue.
boolean	remove(int index) Removes the entity queued at the given position.
void	removeAll() Removes all entities from the Queue.
E	removeFirst() Removes the first entity from the queue and provides a reference to this entity.
E	removeFirst(Condition<E> c) Removes the first entity from the queue that fulfills the given condition.
E	removeLast() Removes the last entity from the queue and provides a reference to this entity.
E	removeLast(Condition<E> c) Removes the last entity from the queue that fulfills to the given condition, determined by traversing the queue from last to first until an entity fulfilling the condition is found.
void	reset() Resets all statistical counters to their default values.
void	setQueueStrategy(int sortOrder) Sets the sort order of this Queue to a new value and makes this Queue use another QueueList with the specified queueing discipline.
void	setSeed(long newSeed) Sets the seed of the underlying queue list's pseudo random number generator.
int	size() Returns the current length of the Queue.
E	succ(E e) Returns the entity enqueued directly after the given Entity in the queue.
E	succ(E e, Condition<E> c) Returns the entity enqueued after the given Entity in the 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

Queue

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

Constructs a simple priority based waiting-queue for entities, the kind of queue sort order and the capacity of the queue can be chosen. Note that since SimProcesses are derived from Entities, they can be queued inside this queue, too.

Queues can be sorted as follows:

• QueueBased.FIFO sorts entities by their priority, highest priority first. Entities with the same priority are enqueued based on "first in, first out".
• QueueBased.LIFO also sorts entities by their priority, highest priority first. However, entities with the same priority are enqueued based on "last in, first out".
• QueueBased.Random assigns a random position to each entity entering the queue, disregarding priority.

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

Parameters:

owner - Model : The model this queue is associated to

name - java.lang.String : The 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 entities 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 queue should produce a report

showInTrace - boolean : Flag for queue to produce trace messages

Queue

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

Constructs a simple priority and FIFO based waiting-queue for entities with a maximum capacity of 2,147,483,647 waiting entities, which should serve as an approximation of infinite queues sufficiently well for most purposes.Note that since SimProcesses are derived from Entities, they can be queued inside this queue, too.

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

Parameters:

owner - Model : The model this queue is associated to

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

showInReport - boolean : Flag if queue should produce a report

showInTrace - boolean : Flag for queue to produce trace messages

Method Detail

createDefaultReporter

public Reporter createDefaultReporter()

Returns a special queue reporter to produce a report about this queue.

Returns:

desmoj.core.report.Reporter : The reporter for this queue

first

public E first()

Returns the first entity queued in this queue or null in case the queue is empty.

Returns:

E : The first entity in the queue or null if the queue is empty

first

public E first(Condition<E> c)

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

Parameters:

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

Returns:

E : The first entity queued in this queue applying to the given condition or null

contains

public boolean contains(E e)

Returns true if the given Entity 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 Entity is contained in the queue; false otherwise.

size

public int size()

Returns the current length of the Queue.

Returns:

int : The number of entities enqueued.

get

public int get(E e)

Returns the queue index of a given Entity.

Returns:

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

get

public E get(int index)

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

Returns:

E : The Entity at the position of int or null if no such position exists.

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.

Returns:

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

insert

public boolean insert(E e)

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

Parameters:

e - E : The Entity to be added to the queue.

Returns:

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

insertAfter

public boolean insertAfter(E e,
                           E after)

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

Parameters:

e - E : The Entity to be added to the queue

after - E : The Entity after which the entity e is to be inserted

Returns:

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

insertBefore

public boolean insertBefore(E e,
                            E before)

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

Parameters:

e - E : The Entity to be added to the queue

before - E : The Entity before which the entity e 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 queue is empty or if any number of entities is currently enqueued in it.

Returns:

boolean : Is true if the Queue is empty, false otherwise

last

public E last()

Returns the last Entity queued in this queue or null in case the queue is empty.

Returns:

E : The last Entity in the queue or null if the queue is empty

last

public E last(Condition<E> c)

Returns the last Entity queued in this queue that fulfills the given condition. The queue is searched from end to front and the first entity that returns true when the condition is applied to it is returned. If no Entity fulfills the given condition or the queue is empty, null will be returned.

Parameters:

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

Returns:

E : The last Entity queued in this queue applying to the given condition or null

pred

public E pred(E e)

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

Parameters:

e - E : An Entity in the queue

Returns:

E : The Entity directly before the given Entity in the queue or null.

pred

public E pred(E e,
              Condition<E> c)

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

Parameters:

e - E : An Entity in the queue

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

Returns:

E : The Entity before the given Entity in the queue fulfilling the condition or null.

remove

public void remove(Entity e)

Removes the given Entity from the Queue. If the given Entity is not in the Queue, a warning will be issued but nothing else will be changed.

Parameters:

e - Entity : The Entity to be removed

removeAll

public void removeAll()

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

removeFirst

public E removeFirst()

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

Returns:

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

removeFirst

public E removeFirst(Condition<E> c)

Removes the first entity from the queue that fulfills the given condition. Also provides a reference to this entity. If the queue does not contain an entity 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:

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

removeLast

public E removeLast()

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

Returns:

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

removeLast

public E removeLast(Condition<E> c)

Removes the last entity from the queue that fulfills to the given condition, determined by traversing the queue from last to first until an entity fulfilling the condition is found. Also provides a reference to this entity. If the queue does not contain an entity 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:

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

remove

public boolean remove(int index)

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

Returns:

: The method returns true if an Entity 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

setQueueStrategy

public void setQueueStrategy(int sortOrder)

Sets the sort order of this Queue to a new value and makes this Queue 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 Queue 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)

succ

public E succ(E e)

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

Parameters:

e - E : An Entity in the queue

Returns:

E : The Entity directly after the given Entity in the queue or null.

succ

public E succ(E e,
              Condition<E> c)

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

Parameters:

e - E : An Entity in the queue

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

Returns:

E : The Entity after the given Entity in the queue fulfilling the condition or null.

getQueueList

public QueueList<E> 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 Queue.

setSeed

public void setSeed(long newSeed)

Sets the seed of the underlying queue list's pseudo random number generator. Useful for queues with random sort order only; to other queues, calling this method has no effect, resulting in a warning.

Parameters:

newSeed - long : new seed of the underlying queue list's pseudo random number generator

iterator

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

Returns an iterator over the entities enqueued.

Specified by:

iterator in interface java.lang.Iterable<E extends Entity>

Returns:

java.lang.Iterator<E> : An iterator over the entities enqueued.