Service

Parameters
Functions
Internal blocks
Ports

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.

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.

¹ Each resource unit may receive requests from different sources. When a single resource unit receives multiple tasks, suspended and new, with identical priority values, some rules apply to the picking order:

The suspended tasks from the individual queue of the resource unit have the highest priority.
This queue is formed by agents waiting in blocks that have the Task preemption policy set to Wait for original resource.
After that, the suspended tasks from the queue of the ResourcePool block are processed.
This queue is formed by agents waiting in the blocks that have the Task preemption policy set to Seize any resource.

Once the suspended tasks from these queues are completed, the resource unit begins to process new tasks from their individual queues, and after that, the queue of the ResourcePool block.

If this order does not suit your needs, manually decrease the task’s priority by code, using the On task suspended action of the block.

For more information on different ways to define resources in the Service block, see Resources.

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, refer to the Resources article.
Syntax: boolean seizeFromOnePool
Resource sets (alternatives): [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.
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.
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
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: 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: 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 current 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:
Service.DEST_ENTITY
Service.DEST_NODE
Service.DEST_ATTRACTOR
Node: [Visible if Destination is: 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: [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: 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: 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: 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: 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
Local variable: agent — the agent
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
Auto suspend/resume agents: [Visible if Task preemption: 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: [Visible if Task preemption policy: 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: [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: [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' preemption policy: [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: [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: 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)
Local variables:
agent — the agent
ResourcePool pool — the resource pool
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
"unit1 is preferred to unit2": [Visible if Resource selection: 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: [Visible if Resource selection: 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 variables:
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: [Visible if Queue: exit on timeout is selected]
Expression evaluated to obtain the timeout time for the agent.
Valid value: double
Default value: infinity
Local variable: agent — the agent
Queue: 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 Service block.
Syntax: boolean restoreEntityLocationOnExit
Force statistics collection: This block contains internal blocks that collect statistics. If the statistics collection is turned off for all Process Modeling Library blocks in the model by the PML Settings 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
'Return home' usage is: Choose whether in the Service 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'
Local variables:
agent — the agent
Agent unit — the resource unit
Valid values:
Service.USAGE_BUSY
Service.USAGE_IDLE
Service.USAGE_NOT_COUNTED

Actions

On enter: Code executed when the agent enters the Service block.
Local variable: agent — the agent
On exit (timeout): [Visible if Queue: exit on timeout]
Code executed when the agent exits the Service block via outTimeout port as a result of timeout event.
Local variable: agent — the agent
On exit (preempted): [Visible if Queue: enable preemption]
Code executed when the agent exits the Service block via outPreempted port as a result of preemption.
Local variable: agent — the agent
On seize unit: Code executed when the new unit is seized.
Local variables:
agent — the agent
Agent unit — the resource unit
On enter delay: 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 executed when agent has finished its delay and ready to leave the Service block.
Local variable: agent — the agent
On exit: Code executed when the agent exits the Service block via out port (in the normal way).
Local variable: agent — the agent
On task suspended: [Visible if Task preemption: 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: 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: 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 the Service block by calling the agent's function remove(). This code is automatically executed after the remove() function call.
Local variable: agent — the agent

Functions

Queue

Function	Description
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.

Delay

Function	Description
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.

Agent removal

Function	Description
T remove(Agent agent)	Removes the given agent from the Service block and returns it. If the agent was not contained in the Service block, returns null.

Control

Function	Description
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.

Statistics

Function	Description
int size()	Returns the number of agents in the Service block.
double utilization()	Returns the mean utilization of the Service block. The returned value is the average (collected over time) of number of agents being serviced.
boolean isStatisticsCollected()	Returns true if the Service block collects statistics.
resetStats()	Resets the statistics collected for the Service block.

Resources

Function	Description
List getResourceUnits(T agent)	Returns resource units servicing the given agent in the Service block.
recalculateResourceChoiceConditions(Agent agent)	Recalculates choice conditions for the given agent which is currently waiting in the queue of the Service 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 the Service 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.

Internal blocks

Seize seize: Seizes resource units. This block, in turn, embeds a Queue block where agents wait for the resource.
Delay delay: Delays the agent.
Release release: Releases the seized resource units.

Ports

in: The input port.
out: The output port.
outTimeout: The output port for agents leaving the Service block as a result of timeout
outPreempted: The output port for agents leaving the Service block as a result of preemption.

How can we improve this article?

Service

Parameters

Resource sets (alternatives)

Resource pool

Number of units

Delay time

Send seized resources

Node

Attractor

On finish, moving resources

Priorities / preemption

Task priority

Task may preempt

Task preemption policy

Enter for terminated agents

Return home

'Wrap up' priority

'Wrap up' preemption policy

Advanced

Resource choice condition

Resource selection

"unit1 is preferred to unit2"

Unit rating

Timeout

'Return home' usage is

Actions

Functions

Internal blocks

Ports