com.cycling74.max
Class MaxClock

java.lang.Object
  com.cycling74.max.MaxClock

public class MaxClock
extends java.lang.Object

MaxClock provides a way for your mxj classes to set up the execution of events in the future. For instance, the following class creates a MaxClock and when it receives a bang will post a message every 500 milliseconds to the Max console.

 public class MaxClockExample extends MaxObject() {
        MaxClock cl;
        
        MaxClockExample() {
                cl = new MaxClock(this, "runForever");
        }
 
        public void bang() {
        cl.delay(500.);
        }
 
        public void runForever() {
                post("forever");
                cl.delay(500.);
        }
 
        public void notifyDeleted() {
                post("never");
                cl.release();
        }
 }
 

It is critical that the release() method be called when a clock is no longer needed.

Constructor Summary

MaxClock()
creates a MaxClock that is set up to do nothing when executed.

MaxClock(Executable e)
creates a MaxClock that executes Executable e.

MaxClock(java.lang.Object o, java.lang.String methodName)
creates a MaxClock by creating a simple Callback that executes the parameterless method in the given Object with the name in the given String.

Method Summary

void	delay(double time) Set up a clock tick for some time in the future.
protected void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
Executable	getExecutable() gets the Executable currently associated with the MaxClock.
static double	getTime() Gets the current logical time of the scheduler.
void	release() Releases the clock when it's no longer needed.
void	setExecutable(Executable e) sets the MaxClock's Executable.
void	tick() executes the Executable currently associated with the MaxClock.
void	unset() Unsets the clock.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MaxClock

public MaxClock(Executable e)

creates a MaxClock that executes Executable e.

Parameters:

e - the Executable that the MaxClock will execute.

MaxClock

public MaxClock()

creates a MaxClock that is set up to do nothing when executed. To make anything happen the code will have to associate the MaxClock with a valid Executable using the setExecutable method.

MaxClock

public MaxClock(java.lang.Object o,
                java.lang.String methodName)

creates a MaxClock by creating a simple Callback that executes the parameterless method in the given Object with the name in the given String.

Parameters:

o - the Object that contains the method to be executed

methodName - the name of the method to execute

Method Detail

getExecutable

public Executable getExecutable()

gets the Executable currently associated with the MaxClock.

Returns:

the Executable currently associated with the MaxClock.

setExecutable

public void setExecutable(Executable e)

sets the MaxClock's Executable. For instance, the following class uses the setExecutable method to change the output that's posted to the Max console based on integer input:

public class SetExecutableExample extends MaxObject {

        private class IntHolderExe implements Executable {
                private int val;
                private MaxClock cl;
                private double delayTime;

                IntHolderExe(int val, MaxClock cl, double delayTime) {
                        this.val = val;
                        this.cl = cl;
                        this.delayTime = delayTime;
                }

                public void execute() {
                        post("the last number passed in was "+val);
                        cl.delay(delayTime);
                }
        }

        private MaxClock cl = new MaxClock(new Executable() {
                public void execute() {
                        post("no input yet.");
                }
        });

        public void inlet(int val) {
                cl.setExecutable(new IntHolderExe(val, cl, 500.));
        }

        public void bang() {
                cl.tick();
        }

        protected void notifyDeleted() {

        }
}

Parameters:

e - the new Executable.

tick

public void tick()

executes the Executable currently associated with the MaxClock.

release

public void release()

Releases the clock when it's no longer needed. It is highly recommended to call this method in your class's notifyDeleted method to free the resources associated with a MaxClock when the host Max object is deleted. If you don't call this method a MaxClock can continue to operate when the host object no longer exists, and behaviour can be unpredictable. It is also catastrophic to call this method and then subsequently use the MaxClock again by calling the delay method.
The below code is an example of proper usage.

 
public class ReleaseExample extends MaxObject {
        private static final double DELAY_TIME = 250.;  
        private MaxClock cl = new MaxClock(this, "doThis");
        private int i=0;

        public void bang() {
                cl.delay(DELAY_TIME);
        }

        public void doThis() {
                i++;
                post("i've printed out "+i+" numbers.");
                cl.delay(DELAY_TIME);
        }

        protected void notifyDeleted() {
                post("ouch!");
                cl.release();
        }
}

delay

public void delay(double time)

Set up a clock tick for some time in the future. Cancels any previous delay calls that have not yet executed.

Parameters:

time - milliseconds until the next clock tick (execution of the Executable.)

unset

public void unset()

Unsets the clock. Cancels any previous delay calls that have not yet executed.

getTime

public static double getTime()

Gets the current logical time of the scheduler.

Returns:

the current logical time of the scheduler in milliseconds

finalize

protected void finalize()
                 throws java.lang.Throwable

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable