com.jogamp.common.util.locks

## Interface RecursiveThreadGroupLock

- All Superinterfaces:
    Lock, RecursiveLock, ThreadLock

      public interface RecursiveThreadGroupLock
      extends RecursiveLock

  Reentrance capable locking toolkit, supporting multiple threads as owner.

  See use case description at `addOwner(Thread)`.

- - ### Field Summary

    - ### Fields inherited from interface com.jogamp.common.util.locks.Lock

      `DEBUG, DEFAULT_TIMEOUT, TIMEOUT, TRACE_LOCK`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addOwner(Thread t)` Add a thread to the list of additional lock owners, which enables them to recursively claim this lock.
    `boolean` | `isOriginalOwner()` Returns true if the current thread is the original lock owner, ie.
    `boolean` | `isOriginalOwner(Thread thread)` Returns true if the passed thread is the original lock owner, ie.
    `void` | `removeOwner(Thread t)` Remove a thread from the list of additional lock owner threads.
    `void` | `unlock()` Wait's until all additional owners released this lock before releasing it.
    `void` | `unlock(Runnable taskAfterUnlockBeforeNotify)` Wait's until all additional owners released this lock before releasing it.

    - ### Methods inherited from interface com.jogamp.common.util.locks.RecursiveLock

      `getHoldCount, getQueueLength`

    - ### Methods inherited from interface com.jogamp.common.util.locks.ThreadLock

      `getOwner, isLockedByOtherThread, isOwner, validateLocked`

    - ### Methods inherited from interface com.jogamp.common.util.locks.Lock

      `isLocked, lock, tryLock`

- - ### Method Detail

    - #### isOriginalOwner

          boolean isOriginalOwner()

      Returns true if the current thread is the original lock owner, ie. successfully claimed this lock the first time, ie. `RecursiveLock.getHoldCount()` == 1.

    - #### isOriginalOwner

          boolean isOriginalOwner(Thread thread)

      Returns true if the passed thread is the original lock owner, ie. successfully claimed this lock the first time, ie. `RecursiveLock.getHoldCount()` == 1.

    - #### addOwner

          void addOwner(Thread t)
                        throws RuntimeException,
                               IllegalArgumentException

      Add a thread to the list of additional lock owners, which enables them to recursively claim this lock.

      The caller must hold this lock and be the original lock owner, see `isOriginalOwner()`.

      If the original owner releases this lock via `unlock()` all additional lock owners are released as well. This ensures consistency of spawn off additional lock owner threads and it's release.

      Use case:

           Thread2 thread2 = new Thread2();

           Thread1 {

             // Claim this lock and become the original lock owner.
             lock.lock();

             try {

               // Allow Thread2 to claim the lock, ie. make thread2 an additional lock owner
               addOwner(thread2);

               // Start thread2
               thread2.start();

               // Wait until thread2 has finished requiring this lock, but keep thread2 running
               while(!thread2.waitForResult()) sleep();

               // Optional: Only if sure that this thread doesn't hold the lock anymore,
               // otherwise just release the lock via unlock().
               removeOwner(thread2);

             } finally {

               // Release this lock and remove all additional lock owners.
               // Implicit wait until thread2 gets off the lock.
               lock.unlock();

             }

           }.start();

      Parameters:
        `t` - the thread to be added to the list of additional owning threads
      Throws:
        `RuntimeException` - if the current thread does not hold the lock.
        `IllegalArgumentException` - if the passed thread is the lock owner or already added.
      See Also:
        `removeOwner(Thread)`, `unlock()`, `Lock.lock()`

    - #### removeOwner

          void removeOwner(Thread t)
                           throws RuntimeException,
                                  IllegalArgumentException

      Remove a thread from the list of additional lock owner threads.

      The caller must hold this lock and be the original lock owner, see `isOriginalOwner()`.

      Only use this method if sure that the thread doesn't hold the lock anymore.

      Parameters:
        `t` - the thread to be removed from the list of additional owning threads
      Throws:
        `RuntimeException` - if the current thread does not hold the lock.
        `IllegalArgumentException` - if the passed thread is not added by `addOwner(Thread)`

    - #### unlock

          void unlock()
                      throws RuntimeException

      Wait's until all additional owners released this lock before releasing it.

      Release the lock.
      Specified by:
        `unlock` in interface `Lock`
      Throws:
        `RuntimeException` - in case the lock is not acquired by this thread.

    - #### unlock

          void unlock(Runnable taskAfterUnlockBeforeNotify)

      Wait's until all additional owners released this lock before releasing it.

      Execute the `Runnable taskAfterUnlockBeforeNotify` while holding the exclusive lock.

      Then release the lock.

      Specified by:
        `unlock` in interface `ThreadLock`