Queue

A queue (a buffer) of agents waiting to be accepted by the next object(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 programmatically from any position in the queue.

The queuing discipline may be FIFO (default), LIFO, or priority-based. 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 object 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. May be FIFO (default), LIFO, Priority-based, or Agent comparison (in the latter case 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).
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 [dynamic]: [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" [dynamic]: [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 [dynamic]: [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: If selected (true), statistics are collected for this and embedded blocks, otherwise statistics collection is configured by PML Settings block (where the default is true).
Syntax: boolean forceStatisticsCollection
Default value: false

Actions: In all these actions the current agent is available as local variable agent.
On enter [code]: Code executed when the agent enters the block (and has been placed in the queue).
On at exit [code]: 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]: Code executed when the agent exits the block via out port (in the normal way).

On exit (preempted) [code]: [Visible if the Enable preemption option is enabled] Code executed when the agent exits via outPreempted port as a result of preemption.
On exit (timeout) [code]: [Visible if the Enable exit on timeout option is enabled] Code executed when the agent exits via outTimeout port as a result of waiting too long.

On remove [code]: 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.

Variables

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

Functions

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

void resetStats() - Resets the statistics collected for this block.

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