A newer version of Max is available. Click here to access the latest version of the Max documentation

The Task Object

The Task Object

A task is a function that can be scheduled or repeated. You can set the arguments to the function as well as the object that will be this when the function is called.

Task Constructor

var tsk = new Task(function, object, arguments);

The object argument represents the this during the execution of the function. Use the this keyword (referring to the jsthis object) to be able to use outlets and other js object features. The function argument represents the function you want to execute, and arguments (an array) represents the arguments to pass to the function. The object and arguments arguments are optional. If not present, the parent of the function object (typically jsthis) will be assumed, and there will be no arguments supplied to the function.

Example: 

function ticker(a, b, c) {
  post("tick")
}

args = new Array(3)
args[0] = 1
args[1] = 2
args[2] = 3
t = new Task(ticker, this, args)

Although the overall timing accuracy of a Task function is high, the latency between the scheduled time and the actual execution time of a Task function is variable because the function runs in a low-priority thread. Therefore you should avoid using a Task function in a time-critical operation.

For convenience, a Task object is a property of the function executed in a Task. To access the Task from within its function, use the following standard Javascript syntax:

arguments.callee.task

We'll show you an example of this syntax for a Task that changes its interval below.

Task Properties

arguments [Array]

The arguments passed to the task function. arguments[0] is the first argument.

function [Function]

The function that is executed in the Task. You can even change this within the task function itself.

running [Boolean]

g/s(get)

Whether the Task is running or not. Within a function executing within a task, this will always be 1.

interval [number] (default: 500)

The time in milliseconds between repeats of the task function. The default interval is 500 ms. Here is an example of a Task with a function that causes the Task to run 10% more slowly each time the function is called, which uses the arguments.callee.task syntax mentioned above: 

function taskfun() {
  var intv = arguments.callee.task.interval
  arguments.callee.task.interval = intv + intv * 0.1
}

object [Object]

The object that is assigned to be the this in the task function. Most often this will be your jsthis object, so you can, for example access the outlet() method. You set up your jsthis object to be the this by creating a task with the keyword this as the first argument. Example: If the object property of a task is a js object, the following three lines of code are identical from within a task function: 

arguments.callee.task.object.outlet(1, "bang")
outlet(1, "bang")
this.outlet(1, "bang")

iterations [Number]

g/s(get)

The number of times the task function has been called. Outside of a task function, the value of iterations is always 0. The value resets each time the task is started (using the repeat(), execute(), or schedule() methods described in the next section).

valid [Boolean]

g/s(get)

Whether the Task object has been invalidated and is awaiting garbage collection. An invalid object will no longer respond to the execute() or schedule() methods. See the description of the freepeer() method below.

Task Methods

repeat

Repeat a task function. The optional number argument specifies the number of repetitions. If the argument is not present or is negative, the task repeats until it is cancelled. The optional initialdelay argument sets the delay in milliseconds until the first iteration. Example: 

tsk = new Task(repeater_function, this)
tsk.interval = 1000 // every second
tsk.repeat(3) // do it 3 times
Here is a repeater function that posts its iteration count to the Max window: 
function repeater_function() {
  post(arguments.callee.task.iterations)
}
In the above example, the Max window output would be:
1
2
3

execute

Run the task once, right now. Equivalent to calling the task function with its arguments.

schedule

Arguments

delay [number] (optional)

Run the task once, with a delay. The optional delay argument sets the time (in milliseconds) before the task function will be executed.

cancel

If a task is scheduled or repeating, any future executions are cancelled. This method can be used within a task function for a self-canceling Task. The following example is a task function that will run only once, even if it is started using the repeat() function. 

function once() {
  arguments.callee.task.cancel()
}

freepeer

Invalidate the Task and make it available for garbage collection by the JS engine. Task objects persist beyond their code scope (otherwise, the object could be garbage collected before its scheduled function is called). The user is responsible for invalidating the Task when it is no longer in use. All Tasks (valid or invalid) will be garbage collected and freed when the parent JS object reloads its script or is itself freed. 

function bang() {
  var tsk = new Task(cb) // Task will not be freed when the bang() function returns
  tsk.schedule(200)
}

function cb() {
  post("right on schedule!\n")
  arguments.callee.task.freepeer() // ensure that the caller can be GC'd
}

See Also

Name Description
JavaScript Usage JavaScript Usage