quicktime.std.clocks
Class QTCallBack

java.lang.Object
  |
  +--quicktime.QTObject
        |
        +--quicktime.std.clocks.QTCallBack
All Implemented Interfaces:
quicktime.jdirect.InterfaceLib, quicktime.jdirect.PrimitivesLib, quicktime.jdirect.QuickTimeLib, quicktime.jdirect.SharedLibrary, com.apple.jdirect.SharedLibrary
Direct Known Subclasses:
ExtremesCallBack, RateCallBack, TimeCallBack, TimeJumpCallBack

public abstract class QTCallBack
extends QTObject
implements quicktime.jdirect.QuickTimeLib

Provides users with a defined operation at some time record of a clock's time base. Its methods offer access to a quicktime structure and its fields. Refer to QTCallBack in QuickTime

When an application schedules a QTCallBack with the callMeWhen method it can cancel and reschedule the callback as required. However, after it no longer requires the services of the QTCallBack it MUST call the cancelAndCleanup method to both cancel any impending callbacks and to dispose of the native structures that are constructed to call back from QuickTime into Java.

There is a very important issue that must be understood by Application developers when using these or any of the call back capabilities of QuickTime in a Java environment. QuickTime native calls are dispatched through a single gateway/lock and run to their completion.

A callback from QuickTime into Java is invoked through the Java application calling a native QuickTime function - in the case of the QTCallBack call back these callbacks are invoked through a direct or indirect call of the QuickTime MoviesTask function.

When the MoviesTask function invokes a callback and calls into Java this occurs in the same thread of execution. Any other native QuickTime calls originating from another thread are queued until the MoviesTask call is completed (including any callbacks that do not spawn their own threads). There exists a potential thread deadlock issue that can arise with the use of callbacks due to this underlying modus operandi that an applications developer may cause and must deal with. This is not a bug but is a feature of the current implementation.

For Example: Thread 1 calls MoviesTask (Movie.task or Movie.taskAll) which invokes a callback on say a QTDrawer object which has a synchronized redraw call. The callback's action is to redraw this QTDrawer object (which will make a native call to QuickTime to draw).

In Thread 2 awt issues a paint call which goes through to the QTDrawer's synchronized redraw call. This redraw call goes through to a native QuickTime call which halts waiting for the currently executing MoviesTask call to complete in Thread 1.

However we have a deadlock - Thread 1 is unable to complete and halts at the QTDrawer's redraw call because Thread 2 already has the synchronization lock for the QTDrawer object. However, thread 2 is unable to continue because Thread 1 has the native QuickTime lock.

One alternative is to have the callback that redraws the QTDrawer spawn another thread and redraw the QTDrawer in this spawn thread. Once the thread is spawned the callback can then complete and in the above scenario Thread 1 can finish the MoviesTask and Thread 2 would then be able to continue and the QTDrawer would redraw itself.

Many of the Callback methods in QuickTime are required to execute in place, in that QuickTime requires a result code in order to proceed. These callbacks should provide meaningful feedback when their execute method returns. The Subclasses of the QTCallBack however can execute asynchronously; QuickTime does not require a result code in order to proceed. This is also true of any of the execute methods with no return value.


Field Summary
 float rateWhenCalled
          This variable is set by the dispatch mechanism when the callback is invoked by QuickTime.
 int timeWhenCalledMsecs
          This variable is set by the dispatch mechanism when the callback is invoked by QuickTime.
 quicktime.std.clocks.CBRunner upp
           
 
Fields inherited from interface quicktime.jdirect.QuickTimeLib
JDirect_MacOSX, libraryInstance, name
 
Method Summary
abstract  void callMeWhen()
          Registers the callback.
 void cancel()
          Cancel a callback event before it executes.
 void cancelAndCleanup()
          Cancel a callback event before it executes.
abstract  void execute()
          This method is called when the callback is executed.
 TimeBase getTimeBase()
          Retrieve the time base of a callback event.
 int getType()
          Retrieve a callback's event type.
 java.lang.String toString()
          A String representation of the class.
 
Methods inherited from class quicktime.QTObject
disposeQTObject, equals, ID
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

upp

public quicktime.std.clocks.CBRunner upp

timeWhenCalledMsecs

public int timeWhenCalledMsecs
This variable is set by the dispatch mechanism when the callback is invoked by QuickTime. In the execute method this variable can be queried to find out the time when the callback first appeared in Java.

rateWhenCalled

public float rateWhenCalled
This variable is set by the dispatch mechanism when the callback is invoked by QuickTime. In the execute method this variable can be queried to find out the rate of the call back's TimeBase when the call back was invoked.
Method Detail

callMeWhen

public abstract void callMeWhen()
                         throws StdQTException
Registers the callback. It will use the state of the subclass to set the parameters that control the callbacks activation. As a method on QTCallBack it does nothing.

QuickTime::CallMeWhen

Parameters:
cb - CallBack interface who's execute method will be called when the callback becomes active.

execute

public abstract void execute()
This method is called when the callback is executed. Subclasses define this method.

cancel

public final void cancel()
Cancel a callback event before it executes.

QuickTime::CancelCallBack()


cancelAndCleanup

public final void cancelAndCleanup()
Cancel a callback event before it executes. This call also cleans up the method closure object that is used to dispatch the callback into Java. If a callback has ever been scheduled it is the applications responsibility to ensure that the cleanup method is called to allow the call back to be garbage collected. The call back can be rescheduled after this call (provided of course you also cleanup again!)

QuickTime::CancelCallBack()


getTimeBase

public final TimeBase getTimeBase()
Retrieve the time base of a callback event.

QuickTime::GetCallBackTimeBase()

Returns:
the time base of the callback.

getType

public final int getType()
Retrieve a callback's event type.

QuickTime::GetCallBackType()

Returns:
the callback's type.

toString

public java.lang.String toString()
Description copied from class: QTObject
A String representation of the class.
Overrides:
toString in class QTObject