com.jogamp.newt.util

## Interface EDTUtil

-     public interface EDTUtil

  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.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static long` | `defaultEDTPollPeriod`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `getPollPeriod()`
    `boolean` | `invoke(boolean wait, Runnable task)` Appends task to the EDT task queue if current thread is not EDT, otherwise execute task immediately.
    `boolean` | `invokeStop(boolean wait, Runnable finalTask)` Append the final task to the EDT task queue, signals EDT to stop.
    `boolean` | `isCurrentThreadEDT()` Returns true if the current thread is the event dispatch thread (EDT).
    `boolean` | `isCurrentThreadEDTorNEDT()` Returns `true` if either `isCurrentThreadEDT()` or `isCurrentThreadNEDT()` is `true`, otherwise `false`.
    `boolean` | `isCurrentThreadNEDT()` Returns true if the current thread is the internal NEWT event dequeue thread (NEDT).
    `boolean` | `isRunning()`
    `void` | `setPollPeriod(long ms)`
    `void` | `start()` Starts the EDT after it's creation or after `stopping`.
    `boolean` | `waitUntilIdle()` Wait until the EDT task queue is empty. The last task may still be in execution when this method returns.
    `boolean` | `waitUntilStopped()` Wait until EDT task is stopped. No `stop` action is performed, `invokeStop(boolean, java.lang.Runnable)` should be used before.

- - ### Field Detail

    - #### defaultEDTPollPeriod

          static final long defaultEDTPollPeriod

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getPollPeriod

          long getPollPeriod()

      Returns:
        poll period in milliseconds

    - #### setPollPeriod

          void setPollPeriod(long ms)

      Parameters:
        `ms` - poll period in milliseconds

    - #### start

          void start()
                     throws IllegalStateException

      Starts the EDT after it's creation or after `stopping`.

      If the EDT is running, it must be `stopped` first and the caller should wait `until it's stopped`.

      Throws:
        `IllegalStateException` - if EDT is running and not subject to be stopped, i.e. `isRunning()` returns true
        `RuntimeException` - if EDT could not be started
      See Also:
        `invokeStop(boolean, java.lang.Runnable)`, `waitUntilStopped()`

    - #### isCurrentThreadEDT

          boolean isCurrentThreadEDT()

      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 `invoke(boolean, Runnable)`.

      Usually it is the same thread as used to dequeue informal `NEWTEvent`s (NEDT), see `isCurrentThreadNEDT()`, however, this may differ, e.g. SWT and AWT implementation.

    - #### isCurrentThreadNEDT

          boolean isCurrentThreadNEDT()

      Returns true if the current thread is the internal NEWT event dequeue thread (NEDT).

      The NEDT is the NEWT thread used to dequeue informal `NEWTEvent`s enqueued internally via `DisplayImpl.enqueueEvent(boolean, NEWTEvent)`.

      Usually it is the same thread as the EDT, see `isCurrentThreadEDT()`, however, this may differ, e.g. SWT and AWT implementation.

    - #### isCurrentThreadEDTorNEDT

          boolean isCurrentThreadEDTorNEDT()

      Returns `true` if either `isCurrentThreadEDT()` or `isCurrentThreadNEDT()` is `true`, otherwise `false`.

    - #### isRunning

          boolean isRunning()

      Returns:
        True if EDT is running and not subject to be stopped.

    - #### invokeStop

          boolean invokeStop(boolean wait,
                           Runnable finalTask)

      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.
      - `start()` may follow immediately, ie creating a new EDT
      Returns:
        true if `task` has been executed or queued for later execution, otherwise false

    - #### invoke

          boolean invoke(boolean wait,
                       Runnable task)

      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.
      Returns:
        true if `task` has been executed or queued for later execution, otherwise false

    - #### waitUntilIdle

          boolean waitUntilIdle()

      Wait until the EDT task queue is empty.
      The last task may still be in execution when this method returns.
      Returns:
        true if waited for idle, otherwise false, i.e. in case of current thread is EDT or NEDT

    - #### waitUntilStopped

          boolean waitUntilStopped()

      Wait until EDT task is stopped.
      No `stop` action is performed, `invokeStop(boolean, java.lang.Runnable)` should be used before.

      If caller thread is EDT or NEDT, this call will not block.

      Returns:
        true if stopped, otherwise false, i.e. in case of current thread is EDT or NEDT

Copyright 2010 JogAmp Community.