com.cycling74.max
Class MaxQelem

java.lang.Object
  extended by com.cycling74.max.MaxQelem

public class MaxQelem
extends java.lang.Object

The MaxQelem object can be used to defer execution of a method from the timer thread to the main thread. This is critical when the method to execute is heavyweight: drawing to the screen, presenting the user with a dialog box, or performing a CPU-intensive series of calculations that could adversely affect a patch's timing. When the MaxQelem's set method is called the target function will be placed on the low priority queue. Once a MaxQelem is set it remains set until the target function is executed at which point it is "unset". Repeated calls to "set" when the MaxQuelem is already set will have no effect since it is already on the queue. This is useful in throttling operations that may take a relatively long time to execute. For more information on qelems and task scheduling in Max see the C developer's documentation.

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


Constructor Summary
MaxQelem()
          Constructs a MaxQelem that is set up to do nothing when executed.
MaxQelem(Executable e)
          Constructs a MaxQelem that executes Executable e.
MaxQelem(java.lang.Object o, java.lang.String methodName)
          Constructs a MaxQelem by creating a simple Callback that executes the parameterless method in the given Object with the name in the given String.
 
Method Summary
protected  void finalize()
          Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
 void front()
          This function is identical to set(), except that the MaxQelem's function is placed at the front of the list of routines to execute in the main thread instead of the back.
 Executable getExecutable()
          Returns the Executable currently associated with the MaxQelem.
 void qfn()
          This is the function that will be called when the MaxQelem is dequeued by the main thread.
 void release()
          Releases the MaxQelem when it's no longer needed.
 void set()
          Causes a MaxQelem to execute.
 void setExecutable(Executable e)
          Sets the MaxQelem's Executable.
 void unset()
          Cancels a MaxQelem's execution.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MaxQelem

public MaxQelem(Executable e)
Constructs a MaxQelem that executes Executable e.

Parameters:
e - the Executable that the MaxQelem will execute.

MaxQelem

public MaxQelem()
Constructs a MaxQelem that is set up to do nothing when executed. To make anything happen the code will have to associate the MaxQelem with a valid Executable using the setExecutable method.


MaxQelem

public MaxQelem(java.lang.Object o,
                java.lang.String methodName)
Constructs a MaxQelem 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

setExecutable

public void setExecutable(Executable e)
Sets the MaxQelem's Executable.

Parameters:
e - the new Executable.

getExecutable

public Executable getExecutable()
Returns the Executable currently associated with the MaxQelem.

Returns:
the Executable currently associated with the MaxQelem.

qfn

public void qfn()
This is the function that will be called when the MaxQelem is dequeued by the main thread. By default it calles the execute() method on its Executable member but can be overidden by a subclass if different behavior is desired. In normal use one would not override this function and would use the Executable member to accomplish whatever task is desired.


set

public void set()
Causes a MaxQelem to execute. If the MaxQelem has already been set, it will not be set again. This is useful if you want to redraw the state of some data when it changes, but not in response to changes that occur faster than can be drawn. A Qelem object is unset after its queue function has been called.


front

public void front()
This function is identical to set(), except that the MaxQelem's function is placed at the front of the list of routines to execute in the main thread instead of the back. Be polite and only use front() for special time-critical applications.


unset

public void unset()
Cancels a MaxQelem's execution.


release

public void release()
Releases the MaxQelem 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 MaxQelem when the host Max object is deleted. If you don't call this method a MaxQelem can execute 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 MaxQelem again by calling the set() method.
The below code is an example of proper usage.
                public class QelemExample extends MaxObject {
                private MaxQelem q = new MaxQelem(this, "doThis");

                public void bang() {
                        q.set();
                }

                private void doThis() {
                        post("the Qelem is working.");
                }

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


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