Schedules (SARL Agent Oriented Programming Language 0.12.0-SNAPSHOT API)

All Superinterfaces:

Capacity

All Known Implementing Classes:

SchedulesSkill
```
public interface Schedules
extends Capacity
```
Schedules actions in time.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`AgentTask`	`at(task : AgentTask = null, time : long, procedure : (Agent)=>void)` Schedule a given task to be executed at the given time.
`AgentTask`	`atFixedDelay(task : AgentTask = null, delay : long, procedure : (Agent)=>void)` Schedule a single-execution task.
`boolean`	`cancel(task : AgentTask, mayInterruptIfRunning : boolean = true)` Attempts to cancel execution of this task.
`AgentTask`	`every(task : AgentTask = null, period : long, procedure : (Agent)=>void)` Schedule a periodic execution of the given task.
`AgentTask`	`execute(task : AgentTask = null, procedure : (Agent)=>void)` Schedule a single-execution task.
`ConcurrentSkipListSet<String>`	`getActiveTasks()` Replies the names of the active tasks.
`AgentTask`	`in(task : AgentTask = null, delay : long, procedure : (Agent)=>void)` Schedule a given task to be executed after the specified delay.
`boolean`	`isCanceled(task : AgentTask)` Replies if the given task was canceled.
`void`	`setName(task : AgentTask, name : String)` Change the name of the given task.
`AgentTask`	`task(name : String)` Create a named task that can be retrieved and schedule later.

- Method Detail
  - getActiveTasks
```
def getActiveTasks() : ConcurrentSkipListSet<String> 
```
    Description copied from interface: Schedules
    
    Replies the names of the active tasks.
    
    Returns:
    
    the names of the active tasks.
    
    Since:
    
    0.5
  - in
```
def in(task : AgentTask = null,
       delay : long,
       procedure : (Agent)=>void) : AgentTask 
```
    Description copied from interface: Schedules
    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.
  - task
```
def task(name : String) : AgentTask 
```
    Description copied from interface: Schedules
    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.
  - setName
```
def setName(task : AgentTask,
            name : String) : void 
```
    Description copied from interface: Schedules
    
    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
  - cancel
```
def cancel(task : AgentTask,
           mayInterruptIfRunning : boolean = true) : boolean 
```
    Description copied from interface: Schedules
    
    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
  - isCanceled
```
def isCanceled(task : AgentTask) : boolean 
```
    Description copied from interface: Schedules
    
    Replies if the given task was canceled.
    
    Parameters:
    
    task - the task.
    
    Returns:
    
    true if the task was canceled with Schedules.cancel(AgentTask,boolean) or Schedules.cancel(AgentTask); false otherwise.
    
    Since:
    
    0.5
  - every
```
def every(task : AgentTask = null,
          period : long,
          procedure : (Agent)=>void) : AgentTask 
```
    Description copied from interface: Schedules
    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:
```
 every(500) [ sleep(2000) ]
 
```
    At a given time, 4 instances (A, B, C, D) of the task may be run in parallel:
```
 t=0   0500   1000   1500   2000   2500   3000   3500   4000   4500
   |    |      |      |      |      |      |      |      |      |
   [-A-----------------------]
        [-B-------------------------]
               [-C-------------------------]
                      [-D-------------------------]
                             [-E-------------------------]
                                    [-F-------------------------]
 
```
    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.
  - atFixedDelay
```
def atFixedDelay(task : AgentTask = null,
                 delay : long,
                 procedure : (Agent)=>void) : AgentTask 
```
    Description copied from interface: Schedules
    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:
```
 atFixedDelay(500) [ sleep(2000) ]
 
```
    At a given time, 3 instances (A, B, C) of the task are run in sequence, and each run is separated by 500 milliseconds:
```
 t=0   0500   1000   1500   2000   2500   3000   3500   4000   4500   5000
   |    |      |      |      |      |      |      |      |      |      |
   [-A-----------------------]
                                    [-B-------------------------]
                                                                       [-C-------------------------]
 
```
    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
  - execute
```
def execute(task : AgentTask = null,
            procedure : (Agent)=>void) : AgentTask 
```
    Description copied from interface: Schedules
    
    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
  - at
```
def at(task : AgentTask = null,
       time : long,
       procedure : (Agent)=>void) : AgentTask 
```
    Description copied from interface: Schedules
    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

Capacity Schedules

Method Summary

Method Detail

getActiveTasks

in

task

setName

cancel

isCanceled

every

atFixedDelay

execute

at