Service

The Service block seizes a given number of resource units, delays the agent, and releases the seized units. It is equivalent to a Seize, Delay, Release sequence and should be used when the agent does not need to do anything but perform a delay between seizing and releasing. Most of the 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.

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

The capacity of the internal Delay block is set to the maximum possible (since it is naturally limited by the capacity of the ResourcePool block).

Seize

Define the seize mode: (Alternative) resource sets or Units of the same pool. For more details, see Using resources.

Name: seizeFromOnePool
Type: boolean

Resource sets (alternatives)

[Visible if Seize: (Alternative) resource sets]
Defines alternative resource sets. To add a new list, clicking Add list. The resource set is chosen based on the availability of units. For more details, see Using resources article.

Local variable: T agent — the agent

Resource pool

[Visible if Seize: Units of the same pool]
The ResourcePool block from where the resources are requested. For more details, see Using resources.

Local variable: T agent — the agent

Number of units

[Visible if Seize: Units of the same pool]
The expression evaluated to obtain the required number of resource units for the agent.

Type: int
Default value: 1
Local variable: T agent — the agent

Queue capacity

[Visible unless the Maximum capacity option is selected]
The capacity of the internal queue.

Name: queueCapacity
Type: int
Default value: 100
Set new value at runtime: set_queueCapacity(new value)

Maximum queue capacity

If the option is selected (true), the capacity of the internal queue is maximum possible (limited to Integer.MAX_VALUE).

Name: maximumCapacity
Type: boolean
Default value: false
Set new value at runtime: set_maximumCapacity(new value)

Delay time

The expression evaluated to obtain the delay time for the agent.

Type: double
Default value: triangular( 0.5, 1, 1.5 ) seconds
Local variable: T agent — the current agent

Send seized resources

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

Type: boolean
Default value: false
Local variables:
T agent — the agent
T unit — the resource unit

Destination is

[Visible if the Send seized resources option 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

Name: destinationType
Type: Seize.DestinationType
Valid values:
Service.DEST_ENTITY — Agent
Service.DEST_NODE — Network node
Service.DEST_ATTRACTOR — Attractor

Node

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

Type: INode
Local variables:
T agent — the agent
T unit — the resource unit

Attractor

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

Type: Attractor
Local variables:
T agent — the agent
T unit — the resource unit

On finish, moving resources

Defines whether the moving resources should Return to home location (if they are not immediately seized by another agent) or Stay where they are after being released.

Type: boolean
Default value: true — Return to home location
Local variables:
T agent — the agent
T unit — the resource unit

Agent location (queue)

The space markup shape (node or path) where the agents are located while being in the internal Queue block.

Name: entityLocationQueue
Type: AnimationStaticLocationProvider

Agent location (delay)

The space markup shape (node or path) where the agents are located while being in the internal Delay block.

Name: entityLocationDelay
Type: AnimationStaticLocationProvider

Task priority

The priority of the task for the incoming agent (the larger the higher).

Type: double
Default value: 0
Local variable: T agent — the agent

Task may preempt

If selected, the task may preempt the currently performed task (if allowed in the task properties and the task priority is lower).

Type: boolean
Default value: true
Local variable: T agent — the agent

Task preemption policy

Defines what to do 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.

Type: TaskPreemptionPolicy
Local variable: T agent — the agent
Valid values:
Service.PP_NO_PREEMPTION — No preemption
Service.PP_WAIT_FOR_ORIGINAL_RESOURCE — Wait for original resource
Service.PP_TERMINATE_SERVING — Terminate serving
Service.PP_SEIZE_ANY_RESOURCE — Seize any resource
Service.PP_CONTINUE_WITHOUT_RESOURCE — Continue without resource

Auto suspend/resume agents

[Visible if Task preemption: Wait for original resource or Seize any resource]
This property 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.

Name: suspendResumeEntities
Type: boolean
Default value: true

Enter for terminated agents

[Visible if Task preemption policy: Terminate serving]
The Enter block for agents which lose all units obtained in this Service block because of the Terminate serving preemption policy when one of units in the resource set defined in this Service gets grabbed by another task with higher priority.

Type: Enter
Local variables:
T agent — the agent
T unit — the resource unit which has originated termination

Return home

[Visible if On finish, moving resources: Return to home location]
Select whether the resources should return home each time, if no other tasks, or select custom and specify the priority and preemption properties below.

Type: WrapUpPolicy
Valid values:
Service.WRAP_UP_ALWAYS — Each time
Service.WRAP_UP_IF_NO_TASKS — If no other tasks
Service.WRAP_UP_PRIORITY_BASED — Custom
Local variables:
T agent — the agent
T unit — the resource unit

'Wrap up' priority

[Visible if Return home: custom]
Defines the priority for the 'return home' task.

Type: double
Local variables:
T agent — the agent
T 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 — the 'return home' task cannot be preempted
Terminate — the 'return home' task will be preempted by other incoming task and terminated

Type: ResourcePreemptionPolicy
Valid values:
Service.WPP_NO_PREEMPTION — No preemption
Service.WPP_TERMINATE — Terminate
Local variables:
T agent — the agent
T unit — the resource unit

Customize resource choice

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

Name: customizeResourceChoice
Type: boolean
Default value: false

Resource choice condition

[Visible if the Customize resource choice option is selected]
Defines the Boolean expression that will be checked to find the specific resource unit(s) that may perform the operation. If no 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.

Type: boolean
Default value: true
Local variables:
T agent — the agent
T unit — the resource unit
ResourcePool pool — the resource pool

Resource selection

Defines 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 "unit1 is preferred to unit2" edit box.
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 edit box.

Type: ResourceSelectionMode
Default value: Service.RESOURCE_SELECTION_SOME_UNIT — Off (chooses some matching unit)
Valid values:
Service.RESOURCE_SELECTION_SOME_UNIT — Off (chooses some matching unit)
Service.RESOURCE_SELECTION_NEAREST — Nearest to the agent
Service.RESOURCE_SELECTION_NEAREST_BY_ROUTE — Nearest to the agent by route (GIS)
Service.RESOURCE_SELECTION_BASED_ON_COMPARISON — The most preferred
Service.RESOURCE_SELECTION_BASED_ON_RATING_VALUE — Unit with top rating
Local variables:
T agent — the agent
ResourcePool pool — the resource pool

"unit1 is preferred to unit2"

[Visible if Resource selection: The most preferred]
The comparison algorithm (or its call) that is used for selecting 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: boolean
Default value: false
Local variables:
T unit1 — the first resource to be compared
T 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 select a unit for the given agent (the larger the higher, the 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.

Type: double
Local variables:
T agent — the agent
T 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.

Name: enableTimeout
Type: boolean
Default value: false

Timeout

Visible if the Queue: exit on timeout option is selected]
The expression evaluated to obtain the timeout time for the agent.

Type: double
Default value: 100 seconds
Local variable: T 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.

Name: enablePreemption
Type: boolean
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 (a node or path) where they were before entering this Service block.

Name: restoreEntityLocationOnExit
Type: boolean

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

Name: forceStatisticsCollection
Type: boolean
Default value: false

'Return home' usage is

Select 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 are not collected at all.

Type: ResourceUsageState
Default value: Service.USAGE_BUSY — counted as 'busy'
Valid values:
Service.USAGE_BUSY — counted as 'busy'
Service.USAGE_IDLE — counted as 'idle'
Service.USAGE_NOT_COUNTED — not collected
Local variables:
T agent — the agent
T unit — the resource unit

On enter

The code executed when the agent enters the Service block.

Local variable: T agent — the agent

On exit (timeout)

[Visible if the Queue: exit on timeout option is selected]
The code executed when the agent exits the Service block via the outTimeout port as a result of a timeout event.

Local variable: T agent — the agent

On exit (preempted)

[Visible if the Queue: enable preemption option is selected]
The code executed when the agent exits the Service block via the outPreempted port as a result of preemption.

Local variable: T agent — the agent

On seize unit

The code executed when the new unit is seized.

Local variables:
T agent — the agent
T unit — the resource unit

On enter delay

The 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

The code executed when the agent has finished its delay and is ready to leave the Service block.

Local variable: T agent — the agent

On exit

The code executed when the agent exits the Service block normally via the out port.

Local variable: T agent — the agent

On task suspended

[Visible if Task preemption policy: Wait for original resource or Seize any resource]
The code executed when the agent task is suspended because of the Wait for original resource and Seize any resource preemption policy, when its unit gets grabbed by another task with a higher priority.

Local variables:
T agent — the agent
T unit — the resource unit

On task resumed

[Visible if Task preemption policy: Wait for original resource or Seize any resource]
The code executed when the agent resumes processing after it has been suspended because of the Seize any resource and Wait for original resource preemption policy.

Local variables:
T agent — the agent
T unit — the resource unit

On task terminated

[Visible if Task preemption policy: Terminate serving]
The code executed when the agent loses all units obtained in this Seize block because of the Terminate serving preemption policy, when one of units in the resource set (defined in this Seize) gets grabbed by another task with a higher priority.

Local variables:
T agent — the agent
T unit — the resource unit which has originated termination

On remove

The code executed when the agent is intentionally removed from the Service block by calling the remove() function of the agent. This code is automatically executed after the remove() function call.

Local variable: T agent — the agent

Queue

Function	Description
int queueSize()	Returns the number of agents in the internal Queue block.
T queueGet(int index)	Returns the agent from the specified position (0 is at the exit). index — the position of the agent to get
T queueRemove(T agent)	Removes the agent from the internal Queue block and returns it. agent — the agent to remove

Delay

Function	Description
int delaySize()	Returns the number of agents in the internal Delay block.
T delayGet(int index)	Returns the agent from the specified position position in the internal Delay block (the oldest agent is at the position 0). index — the position of the agent to get
T delayRemove(T agent)	Removes the given agent from the internal Delay block and returns it. agent — the agent to remove

Agent

Function	Description
int size()	Returns the number of agents in the Service block.
T remove(T agent)	Removes the given agent from the Service block and returns it. If the agent was not contained in the Service block, returns null. agent — the agent to remove
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.

Control

Function	Description
T resume(T agent)	Resumes the previously suspended agent. If the agent is not suspended, throws an error. agent — the agent whose flowchart movement is to be resumed
T suspend(T agent)	Suspends the specified agent. agent — the agent to suspend

Resources

Function	Description
List getResourceUnits(T agent)	Returns resource units serving the specified agent in the Service block. agent — the agent whose resource units are to be retrieved
void recalculateResourceChoiceConditions(T agent)	Recalculates choice conditions for the specified agent which is currently waiting in the queue of the Service block. You can use this function when some resource units that previously were not available for seizure by a particular agent may have become available due to changed conditions. agent — the agent whose selection conditions are to be recalculated
void 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 were not available for seizure may have become available due to changed conditions.

Statistics

Function	Description
boolean isStatisticsCollected()	Returns true if the Service block collects statistics.
void resetStats()	Resets the statistics collected for the Service block.

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.

in

The input port.

out

The output port.

outTimeout

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

outPreempted

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

How can we improve this article?

Send