Seize

The Seize block captures a given number of resource units from a given ResourcePool block. Optionally, it sends the seized resources to a specified location. There are several ways to define the resource pools and units that the agent must seize. For more information about selecting resources, see the Using resources article.

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

The seized resource units are added to the LinkedList<Agent> resourceUnits collection of the agent. This list is publicly accessible, but it is not recommended that you modify it.

Seize embeds a Queue block in which 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 block for some other reason), the request for the next agent is not sent to the pool.

The rich interface of the Queue block (including the ability to use priorities, timeouts, remove agents, and so on) is fully exposed by Seize.

A set of resources may have multiple tasks with different priorities and preemption policies.

• If all tasks have the same priority, they will be executed in the usual way following their occurrence schedule. If there are enough resource units available, tasks can be executed simultaneously. If two tasks have the same priority, but one of them was suspended for some reason, this suspended task will be picked¹.
• If you have configured no preemption policy for the tasks, these tasks will be executed one after another following their occurrence schedule. If there are enough resource units available, tasks can be executed simultaneously.
• The occurrence of one task does not reset the priorities for other tasks.

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

Seize

Define the seize mode: (alternative) resource sets or units of the same pool. For more details, refer to the Using resources article.

Syntax: boolean seizeFromOnePool

Resource sets

[Visible if Seize: (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. For more details, refer to the Resources article.

Value type: ResourcePool[][]
Local variable: agent — the agent

Resource pool

[Visible if Seize: units of the same pool]
ResourcePool block from where the resources are requested. For more details, refer to the Resources article.

Value type: ResourcePool
Local variable: agent — the agent

Number of units

[Visible if Seize: 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 until 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).

Syntax: SeizePolicy 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
Set new value dynamically: set_capacity(new value)

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
Default value: false
Set new value dynamically: set_maximumCapacity(new value)

Send seized resources

If selected (true), the seized resources will be sent to the specified location.

Value type: boolean
Local variables:
agent — the agent
Agent unit — the resource 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

Syntax: Seize.DestinationType destinationType
Valid values:
Seize.DEST_ENTITY
Seize.DEST_NODE
Seize.DEST_ATTRACTOR
Seize.DEST_RESOURCE
Seize.DEST_RESOURCE_HOME
Seize.DEST_XYZ

Node

[Visible if Destination is: Network node]
The network node where the seized resources will be sent.

Value type: INode
Local variables:
agent — the agent
Agent unit — the resource unit

Attractor

[Visible if Destination is: Attractor]
The attractor where the seized resources will be sent.

Value type: Attractor
Local variables:
agent — the agent
Agent unit — the resource unit

Resource

[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 resource unit

X, Y, Z

[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 resource unit

Attach seized resources

If selected (true), the seized resources will be attached to the agent before the agent exits this block.

Value type: boolean
Default value: false
Local variables:
agent — the agent
Agent unit — the resource unit

Agent location

Space markup shape (node or path) for the embedded Queue block.

Syntax: AnimationStaticLocationProvider entityLocationQueue

Task priority

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

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

Here you can choose what is done when a different task incomes for the currently busy resource unit(s).

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, taking into account the restrictions applied by the Resource choice condition property.
Continue without resource — The task is finished without resources assistance.

Get value: TaskPreemptionPolicy
Default value: No preemption
Local variable: agent — the agent
Valid values:
Seize.PP_NO_PREEMPTION
Seize.PP_WAIT_FOR_ORIGINAL_RESOURCE
Seize.PP_TERMINATE_SERVING
Seize.PP_SEIZE_ANY_RESOURCE
Seize.PP_CONTINUE_WITHOUT_RESOURCE

Auto suspend/resume agents

[Visible if Task preemption policy: 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: 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)
• Simply remove from flowchart
• Do nothing

If you select Do nothing, the task will be interrupted, and the agent will remain in the block until the specified delay time runs out. You should specify the agent's action in the On task terminated field.

Syntax: Seize.TerminatedTaskAction terminatedTaskProcessing
Valid values:
Seize.TERMINATED_SEND_TO_ENTER_BLOCK
Seize.TERMINATED_REMOVE_FROM_FLOWCHART
Seize.TERMINATED_DO_NOTHING

Enter for terminated agents

[Visible if Terminated task processing: 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.

Value type: Enter
Local variables:
agent — the agent
Agent unit — the resource unit which has originated termination

Customize resource choice

If the option is selected, you can choose some specific resource units for the operation (using the Resource choice condition below).

If the choice of tasks in your model belongs to the resources, you can use the Request choice condition option in the properties of the corresponding ResourcePool block.

Syntax: boolean customizeResourceChoice
Default value: false

Resource choice condition

[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 resource unit
ResourcePool pool — the resource pool

Resource selection

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.
Nearest to the agent by route (GIS) — The resource nearest to the current agent along the existing routes in GIS 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
Local variables:
agent — the agent
ResourcePool pool — the resource pool
Valid values:
Seize.RESOURCE_SELECTION_SOME_UNIT
Seize.RESOURCE_SELECTION_NEAREST
Seize.RESOURCE_SELECTION_NEAREST_BY_ROUTE
Seize.RESOURCE_SELECTION_BASED_ON_COMPARISON
Seize.RESOURCE_SELECTION_BASED_ON_RATING_VALUE

"unit1 is preferred to unit2"

[Visible and applies only if Dispatching policy: 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.

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

[Visible and applies only if Dispatching policy: 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).

Value type: double
Default value: 0
Local variables:
Agent unit — the resource unit
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: specifying list of blocks]
The list of ResourceTaskStart blocks that define the preparation tasks.

Syntax: ResourceTaskStart[] 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

[Visible if Enable exit on 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
• go to Release (wrap-up)

Syntax: Seize.CanceledUnitBehavior canceledUnitsBehavior
Set new value dynamically: set_canceledUnitsBehavior(new value)
Default value: stay where they are
Valid values:
Seize.CANCELED_UNITS_STAY_WHERE_THEY_ARE
Seize.CANCELED_UNITS_RETURN_TO_HOME_LOCATION
Seize.CANCELED_UNITS_GO_TO_RELEASE_WRAP_UP

Release for canceled units

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

Value type: Release
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 option is selected, after being animated in agent 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

This block contains the internal queue that collects statistics on the queue size. If the statistics collection is turned off for all Process Modeling Library blocks in the model by the PMLSettings 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 this flowchart block.

Local variable: agent — the agent

On exit (timeout)

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

Local variable: agent — the agent

On exit (preempted)

[Visible if the Enable preemption option is selected]
Code executed when the agent exits via outPreempted port as a result of preemption.

Local variable: agent — the agent

On seize unit

Code executed when resource unit is seized.

Local variables:
agent — the agent
Agent unit — just seized resource unit

On prepare unit

Code executed when resource unit is prepared.

Local variables:
agent — the agent
Agent unit — just seized resource unit

On exit

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

Local variable: agent — the agent

On task suspended

[Visible if Task preemption policy: 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 resource unit

On task resumed

[Visible if Task preemption policy: 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 resource unit

On task terminated

[Visible if Task preemption policy: 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 resource unit which has originated termination

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: agent — the agent

Agent

Function	Description
int size()	Returns the number of agents in the internal Queue block.
T get(int index)	Returns the agent from the specified position (0 is at the exit). index — The position of the agent to get.
T remove(Agent agent)	Removes the agent from the internal Queue block and returns it. If the agent was not in the block, returns null. agent — The agent to remove.
T resume(Agent agent)	Resumes the previously suspended agent in the internal Queue block (if the agent was not suspended, throws an error). agent — The agent whose flowchart movement is to be resumed.
T suspend(Agent agent)	Suspends the specified agent in the internal Queue block. agent — The agent to suspend.

Resource choice

Function	Description
recalculateResourceChoiceConditions(Agent agent)	Recalculates choice conditions for the specified agent currently waiting in the internal Queue block. You can use this function when some resource units that previously weren’t available for seizure by a particular agent may have become available due to changed conditions. This function also recalculates conditions for reserved units (Seize whole set at once policy), but doesn’t check the resource units that have already been seized (Seize units one by one policy). agent — The agent whose choice conditions to recalculate.
recalculateResourceChoiceConditions()	Recalculates choice conditions for all agents currently waiting in the internal Queue block. You can use this function when some resource units that previously weren't available for seizure may have become available due to changed conditions. This function also recalculates conditions for reserved units (Seize whole set at once policy), but doesn’t check the resource units that have already been seized (Seize units one by one policy).

Task priority

Function	Description
void recalculateAgentPriority(Agent agent)	Recalculates the task priority for the specified agent currently waiting in the queue of this block. This action may cause resource units to be preempted. If the Seize policy of this block is set to Seize units one by one and the agent has already seized one or more units, some of the resource sets (needed to start a task) may be discarded (namely, the sets that can no longer be completed due to the units currently seized). The priority recalculation does not reset the discarded resource sets. This means that the agent is only allowed to seize units that are needed to complete non-discarded resource sets. If the queue of the Seize block has limited capacity, the recalculation will not affect the agents waiting to enter the Seize block. agent — The agent whose task priority is to be recalculated.
void recalculatePriorities()	Recalculates the task priority for all agents currently waiting in the queue of this block. This action may cause resource units to be preempted. If the Seize policy of this block is set to Seize units one by one and the agent has already seized one or several units, some of the resource sets (needed to start a task) may be discarded (namely, the sets that can no longer be completed due to the units currently seized). Priority recalculation will not reset the discarded resource sets. This means the agent will only be eligible to seize units that are needed to complete non-discarded resource sets. Priorities are recalculated only for agents currently waiting in the queue of the Seize block. If the queue of the Seize block has limited capacity, the recalculation will not affect the agents waiting to enter the Seize block.

Statistics

Function	Description
boolean isStatisticsCollected()	Returns true if the block collects statistics.

Wait queue

The internal queue.

in

The input port.

outTimeout

The output port for agents leaving the block as a result of timeout.

outPreempted

The output port for agents leaving the block 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.

How can we improve this article?

Send