Queue

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.

Capacity

[Visible if Maximum capacity is not chosen]
The capacity of the queue (maximum number of agents that can wait in 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: AnimationStaticLocationProvider entityLocation

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: Queue.QueuingMode 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).

Value 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.

Value 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: false

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
Default value: true

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

On enter

Code executed when the agent enters the block (and has been placed in the queue).

Local variable: T agent — the agent.

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.

Local variable: T agent — the agent.

On exit

Code executed when the agent exits the block via out port (in the normal way).

Local variable: T agent — the agent.

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.

Local variable: T agent — the agent.

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.

Local variable: T agent — the agent.

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.

Local variable: T agent — the agent.

StatisticsContinuous statsSize

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

Block state

Function	Description
int size()	Returns the number of agents in the queue.
boolean canEnter()	Returns true if a new agent can enter the Queue block.
void sortAgents()	Reorders the queue elements by sorting them according to the queue rules. FIFO or LIFO queue: Does nothing. Agent comparison queue: Compares agents with each other. Priority-based queue: Recalculates agent priorities.

Agents in queue

Function	Description
T get(int index)	Returns the agent at the position index (0 is at the exit). index — The position of the agent to get.
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 specified agent from the queue and returns it. If the agent is not contained in the queue, returns null. agent — The agent to remove.
T remove(int index)	Removes the agent at the specified position in the queue and returns it. index — The position of the agent to remove.
boolean release(T agent)	Tells the queue to release the specified agent and send it to the out port. Since this method is called, the agent can leave the Queue block via the out port, but it “holds” the capacity of the queue until it is actually removed from this Queue block. In addition, if the Queue block has the appropriate configuration, the agent can be preempted or timed out of the queue while waiting on the out port. The On at exit action is performed for the specified agent. This method returns true if the agent was successfully released and false if there is no such agent in the queue or the agent has already left the queue due to timeout or preemption or this agent is already waiting on the out port. agent — The agent to release.
Iterator<T> iterator()	Returns the iterator over agents (order: the first is at the exit, the last has the most time left in the delay).

Statistics

Function	Description
boolean isStatisticsCollected()	Returns true if the block collects statistics.
void resetStats()	Resets the statistics collected for this block.

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?

Send