Service

Seizes a given number of resource units, delays the agent, and releases the seized units. Is equivalent to a sequence Seize, Delay, Release and should be used if the agent does not need to do anything but execute a delay between seize and release. Most of parameters and extension points of these blocks are exposed by Service.

For more information on different ways to define resources in the Service block, please, refer here.

Note that when the agent finishes the delay, it will release exactly those units that were seized before the delay.

The capacity of the embedded delay is set to maximum possible (as it naturally is limited with the resource pool capacity).

Parameters

Seize

Define the seize mode: (Alternative) resource sets or Units of the same pool.
For more details, please, refer here.
Syntax: boolean seizeFromOnePool

Resource sets (alternatives) [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.
For more details, please, refer here.
Local variable: agent - the agent

Resource pool [dynamic]

[Visible if Seize is set to Units of the same pool] ResourcePool block from where the resources are requested.
For more details, please, refer here.
Local variable: agent - the agent

Number of units [dynamic]

[Visible if Seize 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
Default value: 1

Queue capacity

[Visible if Maximum capacity is not chosen] The capacity of the embedded queue.
Syntax: int queueCapacity
Default value: 100
Set new value dynamically: set_queueCapacity(new value)

Maximum queue capacity

If the option is selected (true), 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)

Delay time [dynamic]

Expression evaluated to obtain the delay time for the agent.
Value type: double
Local variable: agent - the current agent.
Default value: triangular( 0.5, 1, 1.5 ) second

Send seized resources [dynamic]

If selected (true), the seized resources will be sent to the specified location.
Value type: boolean
Default value: false
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 curent agent location.
Network node - resources are sent to the specified network node.
Attractor - resources are sent to the specified attractor.
Get value:destinationType
Default value: Agent (Service.DEST_ENTITY)
Valid values: self.DEST_ENTITY
self.DEST_NODE
self.DEST_ATTRACTOR

Node [dynamic]

[Visible if Destination is the Network node] Network node where the seized resources will be sent.
Valid value: Node
Local variables: agent - the agent
Agent unit - the resource unit

Attractor [dynamic]

[Visible if Destination is Attractor] Attractor where the seized resources will be sent.
Valid value: Attractor
Local variables: agent - the agent
Agent unit - the resource unit

On finish, moving resources [dynamic]

Defines, whether moving resources should Return to home location (if they are not immediately seized by another agent) or Stay where they are after being released.
Valid value: boolean
Default value: Return to home location (true)
Local variables: agent - the agent
Agent unit - the resource unit

Agent location (queue)

Space markup shape (node or path) where the agents are located while being in the embedded Queue block.
Syntax: AnimationStaticLocationProvider entityLocationQueue

Agent location (delay)

Space markup shape (node or path) where the agents are located while being in the embedded Delay block.
Syntax: AnimationStaticLocationProvider entityLocationDelay

Priorities / preemption

Task priority [dynamic]

The priority of the task for the incoming agent (the larger the higher).
Valid value: 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).
Valid value: boolean
Default value: true
Local variable: agent - the agent

Task preemption policy [dynamic]

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.
Continue without resource - the task is finished without resources assistance.
Default value: No preemption ()
Valid values: Service.PP_NO_PREEMPTION
Service.PP_WAIT_FOR_ORIGINAL_RESOURCE
Service.PP_TERMINATE_SERVING
Service.PP_SEIZE_ANY_RESOURCE
Service.PP_CONTINUE_WITHOUT_RESOURCE
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

Enter for terminated agents [dynamic]

[Visible if Task preemption policy is set to Terminate serving] Enter block for agents which lose all units obtained in this Service block because of Terminate serving preemption policy, when one of units in the resource set (defined in this Service) gets grabbed by another task with higher priority.
Local variables: agent - the agent
Agent unit - the unit which has originated termination

Return home [dynamic]

[Visible, if On finish, moving resources: Return to home location] Select whether resources should return home each time, if no other tasks or select custom and specify the priority and preemption parameters below.
Local variables: agent - the agent
Agent unit - the resource unit

'Wrap up' priority [dynamic]

[Visible, if Return home: custom] Here you can set up the priority for the 'return home' task.
Valid value:double
Local variables: agent - the agent
Agent unit - the resource unit

'Wrap up' preeemption policy [dynamic]

[Visible, if Return home: custom] Specifies the policy for the 'return home' task's preemption:
No preemption - 'return home' task cannot be preempted
Terminate - 'return home' task will be preempted by other incoming task and terminated
Local variables: agent - the agent
Agent unit - the resource unit

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), Service 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.
Valid value: boolean
Default value: true
Local variables: agent - the agent
Agent unit - the resource unit
ResourcePool pool - the resource pool

Resource selection [dynamic]

Here you can choose which resource units may be selected for the given agent.
Off (chooses some matching unit) - no special preference for the selection.
Nearest to the agent - the resource unit which is the closest to the current agent.
Nearest to the agent by route (GIS) - the resource unit which is the closest to the current agent along the existing routes in GIS.
The most preferred - the resource unit is selected by comparing resources to each other. The comparison algorithm (or its call) is placed in the field "unit1 is preferred to unit2".
Unit with top rating - the resource unit with the highest rating is selected. The rating (or the algorithm that calculates it) is specified by the user in the Unit rating field.
Default value: Off (chooses some matching unit)
Valid values: Service.RESOURCE_SELECTION_SOME_UNIT
Service.RESOURCE_SELECTION_NEAREST
Service.RESOURCE_SELECTION_NEAREST_BY_ROUTE
Service.RESOURCE_SELECTION_BASED_ON_COMPARISON
Service.RESOURCE_SELECTION_BASED_ON_RATING_VALUE
Local variable: agent - the agent
ResourcePool pool - the resource pool

"unit1 is preferred to unit2" [dynamic]

[Visible if Resource selection is 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
Default value: false
Local variables: Agent unit1 - the first resource to be compared
Agent unit2 - the second resource to be compared
T agent - the current agent

Unit rating [dynamic]

[Visible if Resource selection is Unit with top rating] The rating value of this unit. The rating is used to choose a unit for the given agent (the larger the higher, unit with the top rating value will be chosen).
Usually an algorithm or a function call is placed here to calculate the rating with the help of the available local variables.
Value type: double
Local variable: agent - the agent
Agent unit - the resource unit

Queue: 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: false

Timeout [dynamic]

[Visible if Queue: exit on timeout is selected] Expression evaluated to obtain the timeout time for the agent.
Valid value: double
Local variable: agent - the agent
Default value: infinity

Queue: enable preemption

If the option is selected (true), the agents are placed in the queue according to theoir 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 Service block.
Syntax: boolean restoreEntityLocationOnExit

Force statistics collection

If selected (true), statistics are collected for this and embedded blocks, otherwise statistics collection is configured by PMLSettings block (where the default is true).
Syntax: boolean forceStatisticsCollection
Default value: false

'Return home' usage is [dynamic]

Choose whether in the block's usage statistics the 'return home' task should be counted as 'busy' time, or counted as 'idle' time, or the statistics for this task is not collected at all.
Default value: counted as 'busy'
Valid values: Service.USAGE_BUSY,
Service.USAGE_IDLE,
Service.USAGE_NOT_COUNTED
Local variables: agent - the agent
Agent unit - the resource unit

Actions

On enter [code]

Code executed when the agent enters the block.
Local variable: agent - the agent

On exit (timeout) [code]

[Visible if Queue: exit on timeout is enabled] Code executed when the agent exits via outTimeout port as a result of timeout event.
Local variable: agent - the agent

On exit (preempted) [code]

[Visible if Queue: enable preemption is enabled] Code executed when the agent exits via outPreempted port as a result of preemption.
Local variable: agent - the agent

On seize unit [code]

Code executed when the new unit is seized.
Local variables: agent - the agent
Agent unit - the resource unit

On enter delay [code]

Code executed when the agent enters the delay.
Local variables: T agent - the agent
double delayTime - the delay time evaluated for the agent

On at exit [code]

Code executed when agent has finished its delay and ready to leave this block.
Local variable: agent - the agent

On exit [code]

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

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 resource 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 resource 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 resource 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 queueSize() - returns the number of agents in the embedded Queue.

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

T queueRemove(Agent agent) - removes agent from the embedded Queue block and returns it.

int delaySize() - returns the number of agents in the embedded Delay block.

T delayGet(int index) - returns the agent at the index position in the Delay (the oldest agent is at the position 0)

T delayRemove(Agent agent) - removes the given agent from the embedded Delay block and returns it.

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

int size() - returns the number of agents in the block.

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.

double utilization() - Returns the mean utilization of this block. The returned value is the average (collected over time) of number of agents being serviced.

List getResourceUnits(T agent) - returns resource units servicing the given agent in this block.

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

recalculateResourceChoiceConditions(Agent agent) - Recalculates choice conditions for the given agent which is currently waiting in the queue of this block. You can use this function when some resource units that previously weren't available for seizure by a particular agent may have become seizable due to changed conditions.

recalculateResourceChoiceConditions() - Recalculates choice conditions for all agents currently waiting in the queue of this block. You can use this function when some resource units that previously weren't available for seizure may have become seizable due to changed conditions.

Embedded blocks

Seize

Seizes resource units. This block, in turn, embeds a Queue block where agents wait for the resource.

Delay

Delays the agent.

Release

Releases the seized resource units.

Ports

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.