Queue

Parameters
- Advanced
- Actions
Statistics
Functions
Ports

A queue (a buffer) of agents waiting to be accepted by the next block(s) in the process flow, or a general-purpose storage for the agents. Optionally, you may associate a maximum waiting time with an agent. You can also remove agents from your code from any position in the queue.

The queuing discipline may be FIFO (”First In, First Out”, the first stored agent will be the first agent to retrieve), LIFO (”Last In, First Out” - the last stored agent will be the first agent to retrieve), priority-based, or based on agent comparison. The priority may be explicitly stored in the agent or calculated based on the agent properties and external conditions. A priority queue always accepts an incoming agent, evaluates its priority and places it at the corresponding position in the queue. If the queue is full, the new agent may then cause the last agent to be thrown out of the queue via outPreempted port, or may itself immediately proceed there if its priority is lower or equal the priority of the last agent.

In case a timeout is associated with the agent, it will exit via outTimeout port if the maximum waiting time is reached.

You can also remove arbitrary agents from the queue by calling remove() function. In some cases, e.g. when the Queue block is used to model storage with arbitrary access, it makes sense to leave the out port of the Queue unconnected and use remove() as the primary way for the agents to exit the queue. You may insert the removed agents to other processes by using Enter blocks.

The queue capacity can be changed dynamically.

The agents in the queue may be animated as standing one behind another along the Path or as staying at the specified positions inside a Node.

The Queue block has several extension points, in particular you can execute the custom actions when the agent enters the queue, exits the queue via any of the three ports, and appears at the first position of the queue. Please note that when onEnter is executed, the agent is already placed in the queue. When onExit, or onExitTimeout, etc are executed, the agent is already removed from the queue.

Parameters

Capacity: [Visible if Maximum capacity is not chosen]
The capacity of the queue.
Syntax: int capacity
Default value: 100
Set new value at runtime: set_capacity(new value)
Maximum capacity: If the option is selected (true), the capacity of the queue is maximum possible (limited by Integer.MAX_VALUE).
Syntax: boolean maximumCapacity
Default value: false
Set new value at runtime: set_maximumCapacity(new value)
Agent location: Space markup shape (node or path) where the agents are located while being in this block.
Syntax: entityLocation

Advanced

Queuing: The queuing discipline for the queue. Possible disciplines are:
FIFO — First In, First Out. The default policy. The first stored agent will be the first agent to retrieve.
Priority-based — The agents will be placed into the queue according to their priorities (defined in the Agent priority field below).
Agent comparison — In this mode, the Boolean expression is evaluated for every incoming agent. It compares this agent with the agents that are already in the queue and finds the place depending on the results.
LIFO — Last In, First Out. The last stored agent will be the first agent to retrieve.

Get value: queuing
Valid values:
Queue.QUEUING_FIFO — FIFO
Queue.QUEUING_PRIORITY — Priority-based
Queue.QUEUING_COMPARISON — Agent comparison
Queue.QUEUING_LIFO — LIFO
Agent priority: [Visible if Queuing is Priority-based]
The priority of the incoming agent (the larger the higher).
Type: double
Default value: 0
Local variable: agent — the agent.
"agent1 is preferred to agent2": [Visible if Queuing is Agent comparison]
Here you specify the boolean expression that is evaluated for every agent getting into the queue. The expression compares this agent with the agents that are already in the queue and finds the place depending on the results. If the expression returns true, the new agent is put closer to the queue head than the agent from the queue being compared with it.
Type: boolean
Local variables:
agent1 — the incoming agent.
agent2 — the agent being compared with the incoming agent.
Enable exit on timeout: If the option is selected (true), the timeout option for the queue is on. After spending the specified time in the queue, the agent will leave the block through the outTimeout port.
Syntax: boolean enableTimeout
Default value: true
Timeout: [Visible if the timeout option is enabled]
Expression evaluated to obtain the timeout time for the agent.
Value type: double
Default value: 100 seconds
Local variable: agent — the agent.
Enable preemption: If the option is selected (true), the agents are placed in the queue according to their priorities and may be preempted by higher priority ones.
Syntax: boolean enablePreemption
Default value: false
Restore agent location on exit: If the option is selected, after being animated in the Agent location shape, the agents will return to their original location (node or path) where they were before entering this block.
Syntax: boolean restoreEntityLocationOnExit
Force statistics collection: This block collects the statistics on the queue size. If the statistics collection is turned off for all Process Modeling Library blocks in the model by the PML Settings block, this option enables you to override this setting and collect the statistics for this specific block. Otherwise, the statistics will be collected regardless this setting.
Syntax: boolean forceStatisticsCollection
Default value: false

Actions

On enter: Code executed when the agent enters the block (and has been placed in the queue).
On at exit: Code executed when the agent appears at the head of the queue (position 0), which may happen directly after it enters the queue.
On exit: Code executed when the agent exits the block via out port (in the normal way).
On exit (preempted): [Visible if the Enable preemption option is enabled]
Code executed when the agent exits via the outPreempted port as a result of preemption.
On exit (timeout): [Visible if the Enable exit on timeout option is enabled]
Code executed when the agent exits via the outTimeout port as a result of waiting too long.
On remove: Code executed when the agent is intentionally removed from this block by calling the agent’s function remove(). This code is automatically executed after the remove() function call.

Statistics

StatisticsContinuous statsSize: Continuous statistics on the queue size. Is collected if the statistics collection is not turned off by PML Settings block.

Functions

Function	Description
int size()	Returns the number of agents in the queue.
boolean canEnter()	Returns true if a new agent may be accepted by the queue.
T get(int index)	Returns the agent at position index (0 is at the exit).
T getLast()	Returns the last agent or null if the queue is empty.
T getFirst()	Returns the first agent or null if the queue is empty.
T removeFirst()	Removes the first agent from the queue and returns it.
T remove(Agent agent)	Removes the given agent from the queue and returns it. If the agent is not contained in the queue, returns null.
T remove(int index)	Removes the agent at the given position in the queue and returns it.
boolean release(T agent)	Tells the queue to release the given agent and forward it to the out port. Since this method is called, the agent may leave the Queue block via the out port, but it “holds” the queue capacity until it is actually pulled from this queue block. Moreover, if the Queue block has corresponding configuration, the given agent may be preempted or it may exit queue by timeout during waiting on the out port. On at exit code is called for the given agent. This method returns true if the agent has been successfully released and false in case when there is no such agent in the queue or the given agent is already exiting queue due to timeout or preemption or this agent is already waiting on the out port.
void sortAgents()	Reorders queue elements by sorting them according to this queue rules. In case of FIFO or LIFO queue, the function does nothing. For Agent comparison queue, agents are compared with each other. For Priority-based queue, agent priorities are recalculated.
boolean isStatisticsCollected()	Returns true if the block collects statistics.
void resetStats()	Resets the statistics collected for this block.
Iterator<T> iterator()	Returns the agent at position index (0 is at the exit).

Ports

in: The input port.
out: The output port.
outTimeout: The output port for agents leaving the block because of timeout.
outPreempted: The output port for agents leaving the block because of preemption.

How can we improve this article?