io.sarl.api.core
Capacity Schedules
All Superinterfaces:
Capacity
All Known Implementing Classes:
SchedulesSkill
capacity Schedules
implements Capacity
Schedules actions in time.
Property Summary
Modifier and type Property and description
ConcurrentSet<T> activeTasks
Replies the names of the active tasks.
Action Summary
Modifier and type Action and description
abstract AgentTask at([AgentTask],long,Procedure1<Param>)
Schedule a given task to be executed at the given time.
abstract AgentTask atFixedDelay([AgentTask],long,Procedure1<Param>)
Schedule a single-execution task.
abstract boolean cancel(AgentTask,[boolean])
Attempts to cancel execution of this task.
abstract AgentTask every([AgentTask],long,Procedure1<Param>)
Schedule a periodic execution of the given task.
abstract AgentTask execute([AgentTask],Procedure1<Param>)
Schedule a single-execution task.
abstract ConcurrentSet<T> getActiveTasks
Replies the names of the active tasks.
abstract AgentTask in([AgentTask],long,Procedure1<Param>)
Schedule a given task to be executed after the specified delay.
abstract boolean isCanceled(AgentTask)
Replies if the given task was canceled.
abstract void setName(AgentTask,String)
Change the name of the given task.
abstract AgentTask task(String)
Create a named task that can be retrieved and schedule later.
Property Details
activeTasks 
val activeTasks : ConcurrentSet<T>
Replies the names of the active tasks.

This property is an alias for the action: getActiveTasks

Returns:
the names of the active tasks.
Since:
0.5
Action Details
at([AgentTask],long,Procedure1<Param>) 
def at([AgentTask],long,Procedure1<Param>) : AgentTask
Schedule a given task to be executed at the given time.

If the given time is passed, according to Time then the task is not executed.

The given procedure takes one parameter: the agent associated to the task. It is name it by default.

The given time is expressed in milliseconds according to the time scale of the SRE. It means that the given number of milliseconds may be not real milliseconds, depending on the definition of the builtin capacity Time.

If this function is invoked from a Behavior and there is no provided task, the created task will be associated to the behavior instance. It means that the task will be automatically canceled when the behavior instance is unregistered from the the owning agent.

This function does nothing if one of the following conditions evaluates to true:
  • the agent is not alive.
Parameters:
task - the task that will run the given closure. If null, a new task is created.
time - the time in milliseconds at which to start the procedure execution.
procedure - the closure to execute.
Returns:
the task is given, or a new task if the procedure is schedule, or null if the procedure is not scheduled.
Since:
0.9
atFixedDelay([AgentTask],long,Procedure1<Param>) 
def atFixedDelay([AgentTask],long,Procedure1<Param>) : AgentTask
Schedule a single-execution task.

If the duration of the task is greater to the given delay length, then no multiple task's instance are run in parallel, in opposite to the every() function. For example, consider the following code: 
br atFixedDelay(500) [ sleep(2000) ]br
At a given time, 3 instances (A, B, C) of the task are run in sequence, and each run is separated by 500 milliseconds: 
br t=0   0500   1000   1500   2000   2500   3000   3500   4000   4500   5000br   |    |      |      |      |      |      |      |      |      |      |br   [-A-----------------------]br                                    [-B-------------------------]br                                                                       [-C-------------------------]br
For executing a task with a fixed rate, and not with a fixed delay between the task runs, you should use the every() function.

The given procedure takes one parameter: the agent associated to the task. It is name it by default.

The given delay is expressed in milliseconds according to the time scale of the SRE. It means that the given number of milliseconds may be not real milliseconds, depending on the definition of the builtin capacity Time.

It is recommended that the SARL run-time environment, which is providing the implementation of this function to provide an efficient implementation in the case the argument delay is equal to zero. Indeed, if the delay is equal to zero, the task should be run in an infinite loop until it is canceled, or the owning agent is killed.

This function does nothing if one of the following conditions evaluates to true:
  • the agent is not alive.
Parameters:
task - the task to associate to the procedure. If null a new task is created.
delay - the delay in milliseconds.
procedure - the procedure to launch. The parameter of the procedure is the agent.
Returns:
the given task.
Since:
0.5
cancel(AgentTask,[boolean]) 
def cancel(AgentTask,[boolean]) : boolean
Attempts to cancel execution of this task. This attempt will fail if the task has already completed, has already been canceled, or could not be canceled for some other reason. If successful, and this task has not started when cancel is called, this task should never run. If the task has already started, then the mayInterruptIfRunning parameter determines whether the thread executing this task should be interrupted in an attempt to stop the task.
Parameters:
task - the task to cancel.
mayInterruptIfRunning - true if the thread executing this task should be interrupted; otherwise, in-progress tasks are allowed to complete
Returns:
false if the task could not be canceled, typically because it has already completed normally; true otherwise
every([AgentTask],long,Procedure1<Param>) 
def every([AgentTask],long,Procedure1<Param>) : AgentTask
Schedule a periodic execution of the given task.

If the duration of the task is greater to the given period length, then multiple task's instances will be run in parallel, in opposite to the atFixedDelay() function. For example, consider the following code: 
br every(500) [ sleep(2000) ]br
At a given time, 4 instances (A, B, C, D) of the task may be run in parallel: 
br t=0   0500   1000   1500   2000   2500   3000   3500   4000   4500br   |    |      |      |      |      |      |      |      |      |br   [-A-----------------------]br        [-B-------------------------]br               [-C-------------------------]br                      [-D-------------------------]br                             [-E-------------------------]br                                    [-F-------------------------]br
For executing a task with a fixed delay between the runs, and not at a fixed rate, you should use the atFixedDelay() function.

The given procedure takes one parameter: the agent associated to the task. It is name it by default.

The given period is expressed in milliseconds according to the time scale of the SRE. It means that the given number of milliseconds may be not real milliseconds, depending on the definition of the builtin capacity Time.

If this function is invoked from a Behavior and there is no provided task, the created task will be associated to the behavior instance. It means that the task will be automatically canceled when the behavior instance is unregistered from the the owning agent.

This function does nothing if one of the following conditions evaluates to true:
  • the agent is not alive.
Parameters:
task - the task to associate to the procedure. If null a new task is created.
period - the number of milliseconds between two launches of the given procedure.
procedure - the procedure to launch. The parameter of the procedure is the agent.
Returns:
the given task.
execute([AgentTask],Procedure1<Param>) 
def execute([AgentTask],Procedure1<Param>) : AgentTask
Schedule a single-execution task.

This function is the easy to use version and efficient implementation of the code in(0) [statements].

The given procedure takes one parameter: the agent associated to the task. It is name it by default.

This function is supposed to execute the given procedure, even if the agent is not alive.
Parameters:
task - the task to associate to the procedure. If null a new task is created.
procedure - the procedure to launch. The parameter of the procedure is the agent.
Returns:
the given task.
Since:
0.5
getActiveTasks 
def getActiveTasks : ConcurrentSet<T>
Replies the names of the active tasks.
Returns:
the names of the active tasks.
Since:
0.5
in([AgentTask],long,Procedure1<Param>) 
def in([AgentTask],long,Procedure1<Param>) : AgentTask
Schedule a given task to be executed after the specified delay.

The given procedure takes one parameter: the agent associated to the task. It is name it by default.

The given delay is expressed in milliseconds according to the time scale of the SRE. It means that the given number of milliseconds may be not real milliseconds, depending on the definition of the builtin capacity Time.

If this function is invoked from a Behavior and there is no provided task, the created task will be associated to the behavior instance. It means that the task will be automatically canceled when the behavior instance is unregistered from the the owning agent.

This function does nothing if one of the following conditions evaluates to true:
  • the agent is not alive.
Parameters:
task - the task that will run the given closure. If null, a new task is created.
delay - time in milliseconds to delay the procedure execution.
procedure - the closure to execute.
Returns:
the generated task.
isCanceled(AgentTask) 
def isCanceled(AgentTask) : boolean
Replies if the given task was canceled.
Parameters:
task - the task.
Returns:
true if the task was canceled with cancel(AgentTask,boolean) or cancel(AgentTask) ; false otherwise.
Since:
0.5
setName(AgentTask,String) 
def setName(AgentTask,String)
Change the name of the given task.

This function should not be directly invoked from a regular SARL code. It is provided for enabling a SRE to change the name of a task.
Parameters:
task - the task to change.
name - the new name of the task.
Since:
0.7
task(String) 
def task(String) : AgentTask
Create a named task that can be retrieved and schedule later. If a task with the specified name already exists, this task is returned.

If this function is invoked from a Behavior, the created task will be associated to the behavior instance. It means that the task will be automatically canceled when the behavior instance is unregistered from the the owning agent.

This function does nothing if one of the following conditions evaluates to true:
  • the agent is not alive.
Parameters:
name - the name of the task. If null or empty, a random name will be given to the task.
Returns:
the task instance, or null if one of the conditions in the function's comment evaluates to true.