com.sleepycat.je.latch
Class SharedLatch

java.lang.Object
  extended by com.sleepycat.je.latch.SharedLatch

public class SharedLatch
extends Object

Simple thread-based non-transactional reader-writer/shared-exclusive latch. Latches provide simple exclusive or shared transient locks on objects. Latches are expected to be held for short, defined periods of time. No deadlock detection is provided so it is the caller's responsibility to sequence latch acquisition in an ordered fashion to avoid deadlocks. Nested latches for a single thread are supported, but upgrading a shared latch to an exclusive latch is not. This implementation is based on the section Reader-Writer Locks in the book Java Threads by Scott Oaks, 2nd Edition, Chapter 8.


Constructor Summary
SharedLatch(Object subject, String name, EnvironmentImpl env)
          Create a latch with a backpointer to its subject (the object that is protected by the latch along with a name (both for debugging purposes).
 
Method Summary
 void acquireExclusive()
          Acquire a latch for exclusive/write access.
 void acquireShared()
          Acquire a latch for shared/read access.
static void clearNotes()
           
static int countLatchesHeld()
          Only call under the assert system.
static void dumpLatchesHeld()
           
(package private)  LatchStats getLatchStats()
          Used for debugging latches.
 Object getSubject()
           
 boolean isOwner()
          Return true if the current thread holds this latch.
static String latchesHeldToString()
           
(package private)  int nWaiters()
          Return the number of threads waiting.
 Thread owner()
          Used only for unit tests.
 void release()
          Release an exclusive or shared latch.
 void setName(String name)
          Set the latch name, used for latches in objects instantiated from the log.
 String toString()
          Formats a latch owner and waiters.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SharedLatch

public SharedLatch(Object subject,
                   String name,
                   EnvironmentImpl env)
Create a latch with a backpointer to its subject (the object that is protected by the latch along with a name (both for debugging purposes).

Method Detail

setName

public void setName(String name)
Set the latch name, used for latches in objects instantiated from the log.


getSubject

public Object getSubject()

acquireExclusive

public void acquireExclusive()
                      throws DatabaseException
Acquire a latch for exclusive/write access. Nesting is allowed, that is, the latch may be acquired more than once by the same thread for exclusive access. However, if the thread already holds the latch for shared access, it cannot be upgraded and LatchException will be thrown. Wait for the latch if some other thread is holding it. If there are threads waiting for access, they will be granted the latch on a FIFO basis. When the method returns, the latch is held for exclusive access.

Throws:
LatchException - if the latch is already held by the current thread for shared access.
RunRecoveryException - if an InterruptedException exception occurs.
DatabaseException

acquireShared

public void acquireShared()
                   throws DatabaseException
Acquire a latch for shared/read access. Nesting is allowed, that is, the latch may be acquired more than once by the same thread.

Throws:
RunRecoveryException - if an InterruptedException exception occurs.
DatabaseException

release

public void release()
             throws LatchNotHeldException
Release an exclusive or shared latch. If there are other thread(s) waiting for the latch, they are woken up and granted the latch.

Throws:
LatchNotHeldException - if the latch is not currently held.

isOwner

public boolean isOwner()
Return true if the current thread holds this latch.

Returns:
true if we hold this latch. False otherwise.

owner

public Thread owner()
Used only for unit tests.

Returns:
the thread that currently holds the latch for exclusive access.

nWaiters

int nWaiters()
Return the number of threads waiting.

Returns:
the number of threads waiting for the latch.

getLatchStats

LatchStats getLatchStats()
Used for debugging latches.

Returns:
a LatchStats object with information about this latch.

toString

public String toString()
Formats a latch owner and waiters.

Overrides:
toString in class Object

countLatchesHeld

public static int countLatchesHeld()
Only call under the assert system. This records counts held latches.


dumpLatchesHeld

public static void dumpLatchesHeld()

latchesHeldToString

public static String latchesHeldToString()

clearNotes

public static void clearNotes()


Copyright 2004-2005 Sleepycat, Inc. All Rights Reserved.