Seize


Seizes a given number of resource units from a given ResourcePool. Optionally sends the seized resources to a specified location. There are several ways to define resource pools and units the agent has to seize:

Once the resource is granted, the agent leaves the object immediately. Use Release object to release the resources. All seized resources must be released before the agent is disposed.

The seized resource units are added to the LinkedList<Agent> resourceUnits collection of the agent. This list has public access, but it is not recommended to modify it.

Seize embeds a Queue object where the agents wait for the resources. The resource is requested for the first agent in the queue and, until it is granted (or that agent leaves the object for another reason), the request for the next agent is not sent to the pool. Note that if agents need different non-conflicting resources, you probably should use different Seize objects for them. 

The rich interface of Queue (ability to use priorities, timeouts, remove agents, etc.) is fully exposed by Seize.

If the agent is going to use the seized resource for a period of time and then release it, consider using Service object, which is equivalent to a sequence [Seize, Delay, Release].

Parameters

Seize
Define the seize mode: (Alternative) resource sets or Units of the same pool.
Please refer to the details above.
Syntax: boolean seizeFromOnePool
Resource sets [dynamic]
[Visible if Seize is set to (Alternative) resource sets] Here you can define several alternative resource sets (add new list by clicking the Add list button). The resource set is chosen based on the availability of units. 
Please refer to the details above.
Local variable: agent - the agent
Resource pool [dynamic]
[Visible if Seize resources is set to Units of the same pool] ResourcePool block from where the resources are requested.
Please refer to the details above.
Local variable: agent - the agent.
Number of units [dynamic]
[Visible if Seize resources is set to Units of the same pool] Expression evaluated to obtain the required number of resource units for the agent.
Value type: int
Local variable: agent - the agent
Seize policy
Defines the policy of seize:
Seize whole set at once - agent waits unit some set becomes fully available, and at that time it seizes all units.
Seize units one by one - agent tries seizing units of any alternative set, once units become available. When unit is seized it may e.g. start some "preparation flowchart" while other units are not yet seized and even the resulting resource set choice is unknown (when there are alternatives).
Get value: seizePolicy
Default value: Seize whole set at once (Seize.SEIZE_WHOLE_SET)
Valid values: Seize.SEIZE_WHOLE_SET
           Seize.SEIZE_UNITS_ONE_BY_ONE
Queue capacity
[Visible if Maximum capacity is not chosen] The capacity of the embedded queue.
Syntax: int capacity
Default value: 100
Maximum queue capacity
If the option is selected, the capacity of the embedded queue is maximum possible (limited to Integer.MAX_VALUE).
Syntax: boolean maximumCapacity
Send seized resources [dynamic]
If selected (true), the seized resources will be sent to the specified location.
Value type: boolean
Local variables: agent - the agent
                          Agent unit - the unit
Destination is
[Visible if Send seized resources is selected]
Defines where the resources will be sent: The resources can be sent to:
Agent - resources are sent to the current agent location.
Network node - resources are sent to the specified network node.
Attractor
- resources are sent to the specified attractor.
Other seized resource unit - resources are sent to the current location of another seized resource (specified below in the Resource field).
Home of seized resource unit - resources are sent to the home location of the seized resource unit.
(x, y, z) - resources are sent to the specified coordinates.
Get value: destinationType
Set new value dynamically: set_destinationType( new value )
Valid values: AgentSeize.DEST_ENTITY
                      Network nodeSeize.DEST_NODE
                      AttractorSeize.DEST_ATTRACTOR
                      Seized resource unitSeize.DEST_RESOURCE
                      Home of seized resource unit  - Seize.DEST_RESOURCE_HOME
                      (x,y,z)Seize.DEST_XYZ
Node [dynamic]
[Visible if Destination is the Network node] Network node where the seized resources will be sent.
Value type: Node
Local variables: agent - the agent
                          Agent unit - the unit
Attractor [dynamic]
[Visible if Destination is AttractorAttractor where the seized resources will be sent.
Value type: Attractor
Local variables: agent - the agent
                          Agent unit - the unit
Resource [dynamic]
[Visible if Destination is Other seized resource unit] The name of the resource pool of the unit to whose location the agent will move. If several units of the same pool are seized, the first in the list will be chosen.
Value type: ResourcePool
Local variables: agent - the agent
                          Agent unit - the unit
X, Y, Z [dynamic]
[Visible if Destination is (x, y, z)] The coordinates where the seized resources will be sent.
Value type: double
Local variables: agent - the agent
                          Agent unit - the unit
Attach seized resources [dynamic]
If selected (true), the seized resources will be attached to the agent before the agent exits this object.
Value type: boolean
Default value: false
Local variables: agent - the agent
                          Agent unit - the unit
Agent location
Space markup shape (node or path) for the embedded Queue object.
Syntax: AnimationStaticLocationProvider entityLocationQueue
Priorities
Task priority [dynamic]
The priority of the task for the incoming agent (the larger the higher).
Value type: double
Default value: 0
Local variable: agent - the agent
Task may preempt [dynamic]
If selected, task may preempt the currently performed task (if allowed in the task properties & the task priority is lower).
Value type: boolean
Default value: true
Local variable: agent - the agent
Task preemption policy [dynamic]
Here you can choose what is done when some other task incomes for the resource unit(s) currently busy with the assembly operation.
No preemption
- the current task continues executing.
Wait for original resource - the task is interrupted and waits for the same resource unit to finish it.
Terminate serving - the task is interrupted and never continued.
Seize any resource - the task is interrupted and tries to seize any resource of the specified type.
Continue without resource - the task is finished without resources assistance.
Default value: No preemption (Seize.PP_NO_PREEMPTION)
Local variable: agent - the agent
Auto suspend/resume agents
[Visible if Task preemption policy is set to Wait for original resource or Seize any resource] This parameter defines whether the agent whose task is suspended should be automatically suspended in its current flowchart block and automatically resumed at the time there are available resources.
Syntax: boolean suspendResumeEntities
Default value: true
Terminated task processing
[Visible if Task preemption policy is set to Terminate serving] Choose here, what to do with the agent after the task is terminated: Redirect to Enter block (specify the Enter block in the parameter below), or Simply remove from flowchart, or Do nothing.
Syntax: terminatedTaskProcessing
Enter for terminated agents [dynamic]
[Visible if Terminated task processing is set to Redirect to Enter block] Enter block for agents which lose all units obtained in this Seize block because of Terminate serving preemption policy, when one of units in the resource set (defined in this Seize) gets grabbed by another task with higher priority.
Local variables: agent - the agent
                          Agent unit - the unit which has originated termination
Advanced
Customize resource choice
If the option is selected, you can choose some specific resource units for the operation (using the Resource choice condition below.) 
Syntax:
boolean customizeResourceChoice
Default value: false
Resource choice condition [dynamic]
[Visible if Customize resource choice is selected] Here you can specify boolean expression that will be checked to find the specific resource unit(s) that may perform the operation. If none currently available resource unit(s) satisfy the specified condition (the condition returns false), Seize will wait for the first resource unit that matches the condition.
Usually you define some field inside the agent type (say, myAssistant), store there the reference to the resource unit when it starts working with this agent (agent.myAssistant=unit), and then specify here the condition agent.myAssistant==unit enabling only this particular unit to continue working with this particular agent.
Value type: boolean
Default value: true
Local variables: agent - the agent
                          Agent unit - the unit
                          ResourcePool pool - the resource pool
Dispatching policy
Here you specify how the block chooses a resource to perform the agent operation. If the Customize resource choice option is set, the resource will be chosen from the subset returned by the algorithm in the Resource choice condition parameter.
The possible options are:
Off (chooses some matching unit) - The dispatching policy is not applied.
Nearest to the agent - The nearest to the current agent resource will be chosen.
The most preferred - The resource will be chosen by comparing resources to each other. The comparison algorithm should be placed in the "unit1 is preferred to unit2" parameter below.
Unit with top rating - The resource with the top rating will be chosen. You define the rating (or rating calculation algorithm) in the Resource rating parameter below.
Syntax: Seize.DispatchingPolicy dispatchingPolicy
Set new value at runtime: set_dispatchingPolicy(new value)
Valid values: Seize.DISPATCHING_POLICY_NEAREST; Seize.DISPATCHING_POLICY_BASED_ON_COMPARISON; Seize.DISPATCHING_POLICY_BASED_ON_RATING_VALUE; Seize.DISPATCHING_POLICY_SOME_UNIT
"unit1 is preferred to unit2" [dynamic]
[Visible and applies only if the Dispatching policy is set to The most preferred] The comparison algorithm (or its call) that is used for choosing a resource for the given agent. The algorithm compares resources to each other. It should return true if the resource unit1 has higher preference than the resource unit2 (and false otherwise, including the case of choice equality). The algorithm should provide transitiveness.
Type of value: boolean
Local variables:  Agent unit1 - the first resource unit to be compared
                           Agent unit2 - the second resource unit to be compared
                           T agent - the current agent
Unit rating [dynamic]
[Visible and applies only if the Dispatching policy is set to Unit with top rating] The rating value of this resource unit. The rating is used to choose a resource for the given agent (the larger the higher, a resource with the top rating value will be chosen).
Type of value: double
Default value: 0
Local variables:  Agent unit - the resource unit
                           T agent - the current agent
Define preparation tasks by
Choose here, how the user defines the preparation tasks: by connecting blocks, or by specifying list of blocks (specify the ResourceTaskStart blocks below).
Syntax: boolean taskStartBlocksAreConnected
Default value: true
ResourceTaskStart blocks
[Visible if Define preparation tasks by is set to Specifying list of blocks] The list of ResourceTaskStart blocks that define the preparation tasks.
Syntax: taskStartBlocks
Enable exit on timeout
If the option is selected, the timeout option for the queue is on. After spending the specified time in the queue, the agent will leave the object through the outTimeout port.
Syntax: boolean enableTimeout
Default value: false
Timeout [dynamic]
[Visible if the timeout option is enabled] Expression evaluated to obtain the timeout time for the agent.
Value type: double
Local variable: agent - the agent
Default value: 100 seconds
Enable preemption
If the option is selected, 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
Canceled units
This parameter defines what should be done with units which have been seized by the time the agent is removed from this Seize block either by timeout/preemption or by remove() function call. Choose, if the units should stay where they are, return to home location or go to Release (wrap-up).
Get value: canceledUnitsBehavior
Set new value dynamically: set_canceledUnitsBehavior( new value )
Default value: stay where they are
Valid values: stay where they are - Seize.CANCELED_UNITS_STAY_WHERE_THEY_ARE
                      return to home location - Seize.CANCELED_UNITS_RETURN_TO_HOME_LOCATION
                      go to Release (wrap-up) - Seize.CANCELED_UNITS_GO_TO_RELEASE_WRAP_UP
Release for canceled units [dynamic]
[Visible, if Canceled units go to Release (wrap-up)] Release block for units which have been seized but are canceled when agent is removed from this Seize block either by timeout/preemption or by remove() function call.
Local variables: agent - the agent.
                          Agent unit - the seized resource unit.
Forced pushing
If the option is selected (true), the agents created by this block will be pushed further regardless of the state of the succeeding block.
Syntax:
boolean pushProtocol
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 Seize block. 
Syntax: boolean restoreEntityLocationOnExit
Force statistics collection
If selected (true), statistics are collected for this and embedded objects, otherwise statistics collection is configured by PMLSettings 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 this flowchart block.
On exit (timeout) [code]
[Visible if the Enable exit on timeout option is selected] Code executed when the agent exits via outTimeout port as a result of timeout event.
On exit (preempted) [code]
[Visible if the Enable preemption option is selected] Code executed when the agent exits via outPreempted port as a result of preemption.
On seize unit [code]
Code executed when resource unit is seized.
Local variables: agent - the agent.
                          Agent unit - just seized resource unit.
On prepare unit [code]
Code executed when resource unit is prepared.
Local variables: agent - the agent.
                          Agent unit - just seized resource unit.
On exit [code]
Code executed when the agent exits the block via out port (in the normal way).
On task suspended [code]
[Visible if Task preemption policy is set to Wait for original resource or Seize any resource] Code executed when agent task is suspended because of Wait for original resource and Seize any resource preemption policy, when its unit gets grabbed by another task with higher priority. 
Local variables: agent - the agent
                          Agent unit - the unit
On task resumed [code]
[Visible if Task preemption policy is set to Wait for original resource or Seize any resource] Code executed when agent resumes processing after it has been suspended because of Seize any resource and Wait for original resource preemption policy.
Local variables: agent - the agent
                          Agent unit - the unit
On task terminated [code]
[Visible if Task preemption policy is set to Terminate serving] Code executed when agent loses all units obtained in this Seize block because of Terminate serving preemption policy, when one of units in the resource set (defined in this Seize) gets grabbed by another task with higher priority.
Local variables: agent - the agent
                          Agent unit - the unit which has originated termination.
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.
Local variable: agent - the agent

Functions

int size() - returns the number of agents in the embedded Queue

T get( int index ) -  returns the agent from the position at the specified index (0 is at the exit).

T remove(Agent agent) - removes agent from the embedded Queue object and returns it. If the agent was not contained in the block, returns null.

T resume(Agent agent) - Resumes previously suspended Delay (if was not suspended, throws error).

T suspend(Agent agent) - Suspends this delay for the given timeout dt.

Ports

in
The input port.
outTimeout
The output port for agents leaving the object as a result of timeout.
outPreempted
The output port for agents leaving the object as a result of preemption.
out
The output port.
preparedUnits
The port for the prepared resource units that have completed their tasks. Here you can connect the last block of the 'resources preparation flowchart'. This flowchart should start with the block ResourceTaskStart