com.jogamp.newt.util.EDTUtil Maven / Gradle / Ivy
/**
* Copyright 2010 JogAmp Community. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification, are
* permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice, this list of
* conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright notice, this list
* of conditions and the following disclaimer in the documentation and/or other materials
* provided with the distribution.
*
* THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
* FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
* ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
* The views and conclusions contained in the software and documentation are those of the
* authors and should not be interpreted as representing official policies, either expressed
* or implied, of JogAmp Community.
*/
package com.jogamp.newt.util;
import jogamp.newt.DisplayImpl;
import com.jogamp.newt.event.NEWTEvent;
/**
* EDT stands for Event Dispatch Thread.
*
* EDTUtil comprises the functionality of:
*
* - Periodically issuing an event dispatch command on the EDT.
* - Ability to enqueue tasks, executed on the EDT.
* - Controlling the EDT, ie start and stop in a sane manner.
*
* The EDT pattern is a common tool to comply with todays windowing toolkits,
* where the common denominator in regards to multithreading is to:
*
* - Create a Window on one thread
* - Modify the Window within the same thread
* - Handle incoming events from within the same thread
*
* Note: This is not true on MacOSX, where all these actions have to be
* performed by a unique, so called main thread.
*/
public interface EDTUtil {
public static final long defaultEDTPollPeriod = 10; // 10ms, 1/100s
/**
* @return poll period in milliseconds
*/
public long getPollPeriod();
/**
* @param ms poll period in milliseconds
*/
public void setPollPeriod(long ms);
/**
* Starts the EDT after it's creation or after {@link #invokeStop(boolean, Runnable) stopping}.
*
* If the EDT is running, it must be {@link #invokeStop(boolean, Runnable) stopped} first
* and the caller should wait {@link #waitUntilStopped() until it's stopped}.
*
*
* @throws IllegalStateException if EDT is running and not subject to be stopped, i.e. {@link #isRunning()} returns true
* @throws RuntimeException if EDT could not be started
*
* @see #invokeStop(boolean, java.lang.Runnable)
* @see #waitUntilStopped()
*/
public void start() throws IllegalStateException;
/**
* Returns true if the current thread is the event dispatch thread (EDT).
*
* The EDT is the platform specific thread dispatching toolkit-events
* and executing toolkit-tasks enqueued via {@link #invoke(boolean, Runnable)}.
*
*
* Usually it is the same thread as used to dequeue informal {@link NEWTEvent}s (NEDT), see {@link #isCurrentThreadNEDT()},
* however, this may differ, e.g. SWT and AWT implementation.
*
*/
public boolean isCurrentThreadEDT();
/**
* Returns true if the current thread is the internal NEWT event dequeue thread (NEDT).
*
* The NEDT is the NEWT thread used to dequeue informal {@link NEWTEvent}s enqueued internally
* via {@link DisplayImpl#enqueueEvent(boolean, NEWTEvent)}.
*
*
* Usually it is the same thread as the EDT, see {@link #isCurrentThreadEDT()},
* however, this may differ, e.g. SWT and AWT implementation.
*
*/
public boolean isCurrentThreadNEDT();
/**
* Returns true if either {@link #isCurrentThreadEDT()} or {@link #isCurrentThreadNEDT()} is true,
* otherwise false.
*/
public boolean isCurrentThreadEDTorNEDT();
/**
* @return True if EDT is running and not subject to be stopped.
*/
public boolean isRunning();
/**
* Append the final task to the EDT task queue,
* signals EDT to stop.
*
* If wait is true methods
* blocks until EDT is stopped.
*
*
* task maybe null
* Due to the nature of this method:
*
* - All previous queued tasks will be finished.
* - No new tasks are allowed, an Exception is thrown.
* - Can be issued from within EDT, ie from within an enqueued task.
* - {@link #start()} may follow immediately, ie creating a new EDT
*
*
* @return true if task has been executed or queued for later execution, otherwise false
*/
public boolean invokeStop(boolean wait, Runnable finalTask);
/**
* Appends task to the EDT task queue if current thread is not EDT,
* otherwise execute task immediately.
*
* Wait until execution is finished if wait == true.
*
* Can be issued from within EDT, ie from within an enqueued task.
* @return true if task has been executed or queued for later execution, otherwise false
*/
public boolean invoke(boolean wait, Runnable task);
/**
* Wait until the EDT task queue is empty.
* The last task may still be in execution when this method returns.
* @return true if waited for idle, otherwise false, i.e. in case of current thread is EDT or NEDT
*/
public boolean waitUntilIdle();
/**
* Wait until EDT task is stopped.
* No stop action is performed, {@link #invokeStop(boolean, java.lang.Runnable)} should be used before.
*
* If caller thread is EDT or NEDT, this call will not block.
*
* @return true if stopped, otherwise false, i.e. in case of current thread is EDT or NEDT
*/
public boolean waitUntilStopped();
}