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.