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
 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