Match


Synchronizes two streams of agents by matching pairs according to a given criteria. The agents that have not yet been matched are stored in two queues (one for each stream). Once the new agent arrives at either of the input ports, it is checked for match against all agents in the queue for the other stream. If the match is found, onMatch is executed and both agents exit the Match object at the same time. The queues can be fully customized (timeout, priorities, preemption, etc.).

The default match condition is true. It means any two agents match, so the Match object works as a pure stream synchronizer: it will output pairs of agents.

Suppose agents in one of the streams are of type Passenger and in the other - Baggage, both types have field id. Then to match passenger with his baggage item you may write agent1.id == agent2.id (provided the generic parameters of Match are Passenger and Baggage).

Demo model: Match

Parameters

Match condition [dynamic]
Condition evaluated for a pair (just arrived agent, an agent in the opposite queue) when the new agent arrives.
Value type: boolean
Local variables: T1 agent1 - the agent in queue1
                          T2 agent2 - the agent in queue2
Default value: true
Capacity (1)
[Visible if Maximum capacity (1) is not chosen] The capacity of the first queue.
Syntax: int capacity1
Default value: 100
Maximum capacity (1)
If the option is selected (true),  the capacity of the first queue is maximum possible (limited by Integer.MAX_VALUE).
Syntax: boolean maximumCapacity1
Capacity (2)
[Visible if Maximum capacity (2) is not chosen] The capacity of the second queue.
Syntax: int capacity2
Default value: 100
Maximum capacity (2)
If the option is selected (true),  the capacity of the second queue is maximum possible (limited by Integer.MAX_VALUE).
Syntax: boolean maximumCapacity2
Agent location (queue 1)
Space markup shape (node or path) where the agents are located while being in the queue1.
Syntax: AnimationStaticLocationProvider entityLocation1
Agent location (queue 2)
Space markup shape (node or path) where the agents are located while being in the queue2.
Syntax: AnimationStaticLocationProvider entityLocation2
Advanced
Queuing (queue 1)
The queuing discipline for the first 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 alreay in the queue and finds the place depending on the results).
Get value: queuing1
Valid values: Match.QUEUING_FIFOFIFO
           Match.QUEUING_PRIORITYPriority-based
           Match.QUEUING_COMPARISONAgent comparison
           Match.QUEUING_LIFOLIFO
Agent priority (1) [dynamic]
[Visible if Queuing (queue 1) is Priority-based] The priority of the incoming agent in the first stream (the larger the higher).
Value type: double
Default value: 0
Local variable: T1 agent - the agent
"agent1 is preferred to agent2" (1) [dynamic]
[Visible if Queuing (queue 1) is Entity comparison] Here you specify the boolean expression that is evaluated for every agent getting into the queue1. The expression compares this agent with the agents that are alreay 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 queue1 being compared with it.
Value type: boolean
Local variables: T1 agent1 - the incoming agent
             T1 agent2 - the agent being compared with the incoming agent
Queuing (queue 2)
The queuing discipline for the first 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 alreay in the queue and finds the place depending on the results).
Get value: queuing2
Valid values: Match.QUEUING_FIFOFIFO
           Match.QUEUING_PRIORITYPriority-based
           Match.QUEUING_COMPARISONAgent comparison
           Match.QUEUING_LIFOLIFO
Agent priority (2) [dynamic]
[Visible if Queuing (queue 2) is Priority-based] The priority of the incoming agent in the second stream (the larger the higher).
Value type: double
Default value: 0
Local variable: T2 agent - the agent
"agent1 is preferred to agent2" (2) [dynamic]
[Visible if Queuing (queue 2) is Agent comparison] Here you specify the boolean expression that is evaluated for every agent getting into the queue2. The expression compares this agent with the agents that are alreay 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 queue2 being compared with it.
Value type: boolean
Local variables: T2 agent1 - the incoming agent
             T2 agent2 - the agent being compared with the incoming agent
Enable exit on timeout (1)
If the option is selected (true), the timeout option for the queue1 is on. After spending the specified time in the queue1, the agent will leave the object through the outTimeout1 port.
Syntax: boolean enableTimeout1
Timeout (1) [dynamic]
[Visible if Enable exit on timeout (1) is selected] Expression evaluated to obtain the timeout time for the agent in queue1.
Value type: double
Local variable: T1 agent - the agent
Enable exit on timeout (2)
If the option is selected (true), the timeout option for the queue2 is on. After spending the specified time in the queue2, the agent will leave the object through the outTimeout2 port.
Syntax: boolean enableTimeout2
Timeout (2) [dynamic]
[Visible if Enable exit on timeout (2) is selected] Expression evaluated to obtain the timeout time for the agent in queue2.
Value type: double
Local variable: T2 agent - the agent
Enable preemption (1)
If the option is selected (true), the agents are placed in the queue1 according to their priorities and may be preempted by the ones with higher priorities. 
Syntax: boolean enablePreemption1
Enable preemption (2)
If the option is selected (true), the agents are placed in the queue2 according to their priorities and may be preempted by the ones with higher priorities.  
Syntax: boolean enablePreemption2
Restore agent location on exit
If the option is selected, after being animated in the Agent location (queue1, queue 2) shapes, the agents will return to their original location (node or path) where they were before entering this block.
Syntax: boolean restoreEntityLocationOnExit
Force statistics collection
By default statistics is collected for all Process Modeling Library blocks. However, you may tune this and switch off the statistics collection to optimize your model performance. To do this, add PML Settings block and deselect there the option Enable statistics by default. This way you switch stats collecting off for all flowchart blocks in the model. However, you can choose some specific blocks to override this setting and collect statistics by selecting this particular option Force statistics collection in the block properties.
Syntax: boolean forceStatisticsCollection
Default value: false
Actions
On enter (1) [code]
Code executed when the agent enters the object via in1 (and has been placed in queue1).
Local variable: T1 agent - the agent. 
On enter (2) [code]
Code executed when the agent enters the object via in2 (and has been placed in queue2).
Local variable: T2 agent - the agent. 
On match [code]
Code executed for the two agents that match each other.
Local variables: T1 agent1 - the current agent in queue1.
                          T2 agent2 - the current agent in queue2.
On exit (1) [code]
Code executed when the agent in the first stream that was matched exits the object.
Local variable: T1 agent - the agent.
On exit (2) [code]
Code executed when the agent in the second stream that was matched exits the object.
Local variable: T2 agent - the agent.
On exit (timeout) (1) [code]
[Visible if the timeout 1 option is enabled] code executed when the agent exits via outTimeout1 port as a result of waiting too long.
Local variable: T1 agent - the agent.
On exit (timeout) (2) [code]
[Visible if the timeout 2 option is enabled] code executed when the agent exits via outTimeout2 port as a result of waiting too long.
Local variable: T2 agent - the agent.
On exit (preempted) (1) [code]
[Visible if the preemption 1 option is enabled] Code executed when the agent exits via outPreempted1 port as a result of preemption.
Local variable: T1 agent - the agent.
On exit (preempted) (2) [code]
[Visible if the preemption 2 option is enabled] Code executed when the agent exits via outPreempted2 port as a result of preemption.
Local variable: T2 agent - the agent.

Functions

int size1() - returns the number of agents in the queue1.

int size2() - returns the number of agents in the queue2.

T1 remove1( T1 agent ) - removes the given agent from the queue1 and returns it. If the agent is not contained in the queue, returns null.

T2 remove2( T2 agent ) - removes the given agent from the queue2 and returns it. If the agent is not contained in the queue, returns null.

Ports

in1
The first input port.
in2
The second input port.
out1
The first output port
out2
The second output.
outTimeout1
The output port for agents exiting the first queue because of timeout.
outTimeout2
The output port for agents exiting the second queue because of timeout.
outPreempted1
The output port for agents exiting the first queue because of preemption.
outPreempted2
The output port for agents exiting the second queue because of preemption..