org.jikesrvm.scheduler

Class Monitor

java.lang.Object

org.jikesrvm.scheduler.Monitor

Direct Known Subclasses:

NoYieldpointsMonitor

public class Monitor
extends Object

Implementation of a heavy lock and condition variable implemented using the primitives available from the operating system. Currently we use a pthread_mutex_t and pthread_cond_it. When instantiated, the mutex and cond are allocated. There is currently no way to destroy either (thus, pool and reuse accordingly).

It is perfectly safe to use this throughout the VM for locking. It is meant to provide roughly the same functionality as Java monitors, except:

• This class provides a faster slow path than Java monitors.
• This class provides a slower fast path than Java monitors.
• This class does not have any interaction with Thread.interrupt() or Thread.stop(). Thus, if you block on a lock or a wait and the calling thread is stopped or interrupted, nothing will happen until the lock is acquired or the wait is notified.
• This class will work in the inner guts of the RVM runtime because it gives you the ability to lock and unlock, as well as wait and notify, without using any other VM runtime functionality.
• This class allows you to optionally block without letting the thread system know that you are blocked. The benefit is that you can perform synchronization without depending on RVM thread subsystem functionality. However, most of the time, you should use the methods that inform the thread system that you are blocking. Methods that have the "WithHandshake" suffix will inform the thread system if you are blocked, while methods that do not have the suffix will either not block (as is the case with unlock() and broadcast()) or will block without letting anyone know (like lockNoHandshake() and waitNoHandshake()). Not letting the threading system know that you are blocked may cause things like GC to stall until you unblock.

Field Summary

Fields

Modifier and Type	Field and Description
int	acquireCount
(package private) int	holderSlot
(package private) Word	monitor
(package private) int	recCount

Constructor Summary

Constructors

Constructor and Description
Monitor() Allocate a heavy condition variable and lock.

Method Summary

Modifier and Type	Method and Description
void	broadcast() Send a broadcast, which should awaken anyone who is currently blocked in any of the wait methods.
protected void	finalize() Frees the data structures that were allocated in C code when the object was created.
void	lockedBroadcastNoHandshake() Send a broadcast after first acquiring the lock.
void	lockNoHandshake() Wait until it is possible to acquire the lock and then acquire it.
static boolean	lockNoHandshake(Monitor l)
void	lockWithHandshake() Wait until it is possible to acquire the lock and then acquire it.
static void	lockWithHandshake(Monitor m1, Word priority1, Monitor m2, Word priority2)
private void	lockWithHandshakeNoRec()
private void	lockWithHandshakeNoRecImpl()
void	relockNoHandshake(int recCount) Relocks the mutex after using unlockCompletely().
void	relockWithHandshake(int recCount) Relocks the mutex after using unlockCompletely() and notify the threading subsystem.
private void	relockWithHandshakeImpl(int recCount)
void	timedWaitAbsoluteNoHandshake(long whenWakeupNanos) Wait until someone calls broadcast(), or until the clock reaches the given time.
void	timedWaitAbsoluteWithHandshake(long whenWakeupNanos) Wait until someone calls broadcast(), or until the clock reaches the given time.
private void	timedWaitAbsoluteWithHandshakeImpl(long whenWakeupNanos)
void	timedWaitRelativeNoHandshake(long delayNanos) Wait until someone calls broadcast(), or until at least the given number of nanoseconds pass.
void	timedWaitRelativeWithHandshake(long delayNanos) Wait until someone calls broadcast(), or until at least the given number of nanoseconds pass.
private void	timedWaitRelativeWithHandshakeImpl(long delayNanos)
void	unlock() Release the lock.
static void	unlock(boolean b, Monitor l)
int	unlockCompletely() Completely releases the lock, ignoring recursion.
void	waitNoHandshake() Wait until someone calls broadcast().
void	waitWithHandshake() Wait until someone calls broadcast().
private void	waitWithHandshakeImpl()

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

monitor

Word monitor

holderSlot

int holderSlot

recCount

int recCount

acquireCount

public int acquireCount

Constructor Detail

Monitor

public Monitor()

Allocate a heavy condition variable and lock. This involves allocating stuff in C that gets deallocated only when the finalizer is run. Thus, don't instantiate too many of these.

Method Detail

finalize

protected void finalize()
                 throws Throwable

Frees the data structures that were allocated in C code when the object was created.

Overrides:

finalize in class Object

Throws:

Throwable

lockNoHandshake

public void lockNoHandshake()

Wait until it is possible to acquire the lock and then acquire it. There is no bound on how long you might wait, if someone else is holding the lock and there is no bound on how long they will hold it. As well, even if there is a bound on how long a thread might hold a lock but there are multiple threads contending on its acquisition, there will not necessarily be a bound on how long any particular thread will wait until it gets its turn.

This blocking method method does not notify the threading subsystem that it is blocking. Thus, if someone (like, say, the GC) requests that the thread is blocked then their request will block until this method unblocks. If this sounds like it might be undesirable, call lockWithHandshake() instead.

relockNoHandshake

public void relockNoHandshake(int recCount)

Relocks the mutex after using unlockCompletely().

Parameters:

recCount - the recursion count

lockWithHandshake

public void lockWithHandshake()

Wait until it is possible to acquire the lock and then acquire it. There is no bound on how long you might wait, if someone else is holding the lock and there is no bound on how long they will hold it. As well, even if there is a bound on how long a thread might hold a lock but there are multiple threads contending on its acquisition, there will not necessarily be a bound on how long any particular thread will wait until it gets its turn.

This blocking method method notifies the threading subsystem that it is blocking. Thus, it may be safer than calling lock. But, its reliance on threading subsystem accounting methods may mean that it cannot be used in certain contexts (say, the threading subsystem itself).

This method will ensure that if it blocks, it does so with the mutex not held. This is useful for cases where the subsystem that requested you to block needs to acquire the lock you were trying to acquire when the blocking request came.

It is usually not necessary to call this method instead of lockNoHandshake() since most VM locks are held for short periods of time.

lockWithHandshakeNoRec

private void lockWithHandshakeNoRec()

lockWithHandshakeNoRecImpl

private void lockWithHandshakeNoRecImpl()

relockWithHandshake

public void relockWithHandshake(int recCount)

Relocks the mutex after using unlockCompletely() and notify the threading subsystem.

Parameters:

recCount - the recursion count

relockWithHandshakeImpl

private void relockWithHandshakeImpl(int recCount)

unlock

public void unlock()

Release the lock. This method should (in principle) be non-blocking, and, as such, it does not notify the threading subsystem that it is blocking.

unlockCompletely

public int unlockCompletely()

Completely releases the lock, ignoring recursion.

Returns:

the recursion count

waitNoHandshake

public void waitNoHandshake()

Wait until someone calls broadcast().

This blocking method method does not notify the threading subsystem that it is blocking. Thus, if someone (like, say, the GC) requests that the thread is blocked then their request will block until this method unblocks. If this sounds like it might be undesirable, call waitWithHandshake() instead.

timedWaitAbsoluteNoHandshake

public void timedWaitAbsoluteNoHandshake(long whenWakeupNanos)

Wait until someone calls broadcast(), or until the clock reaches the given time.

This blocking method method does not notify the threading subsystem that it is blocking. Thus, if someone (like, say, the GC) requests that the thread is blocked then their request will block until this method unblocks. If this sounds like it might be undesirable, call timedWaitAbsoluteWithHandshake(long) instead.

Parameters:

whenWakeupNanos - the absolute time point that must be reached before the wait is over when no call to broadcast() occurs in the meantime

timedWaitRelativeNoHandshake

public void timedWaitRelativeNoHandshake(long delayNanos)

Wait until someone calls broadcast(), or until at least the given number of nanoseconds pass.

This blocking method method does not notify the threading subsystem that it is blocking. Thus, if someone (like, say, the GC) requests that the thread is blocked then their request will block until this method unblocks. If this sounds like it might be undesirable, call timedWaitRelativeWithHandshake(long) instead.

Parameters:

delayNanos - the number of nanoseconds that need to pass from the call of this method until the wait is over when no call to broadcast() occurs in the meantime

waitWithHandshake

public void waitWithHandshake()

Wait until someone calls broadcast().

This blocking method notifies the threading subsystem that it is blocking. Thus, it is generally safer than calling waitNoHandshake(). But, its reliance on threading subsystem accounting methods may mean that it cannot be used in certain contexts (say, the threading subsystem itself).

This method will ensure that if it blocks, it does so with the mutex not held. This is useful for cases where the subsystem that requested you to block needs to acquire the lock you were trying to acquire when the blocking request came.

waitWithHandshakeImpl

private void waitWithHandshakeImpl()

timedWaitAbsoluteWithHandshake

public void timedWaitAbsoluteWithHandshake(long whenWakeupNanos)

Wait until someone calls broadcast(), or until the clock reaches the given time.

This blocking method method notifies the threading subsystem that it is blocking. Thus, it is generally safer than calling timedWaitAbsoluteNoHandshake(long). But, its reliance on threading subsystem accounting methods may mean that it cannot be used in certain contexts (say, the threading subsystem itself).

This method will ensure that if it blocks, it does so with the mutex not held. This is useful for cases where the subsystem that requested you to block needs to acquire the lock you were trying to acquire when the blocking request came.

Parameters:

whenWakeupNanos - the absolute time point that must be reached before the wait is over when no call to broadcast() occurs in the meantime

timedWaitAbsoluteWithHandshakeImpl

private void timedWaitAbsoluteWithHandshakeImpl(long whenWakeupNanos)

timedWaitRelativeWithHandshake

public void timedWaitRelativeWithHandshake(long delayNanos)

Wait until someone calls broadcast(), or until at least the given number of nanoseconds pass.

This blocking method method notifies the threading subsystem that it is blocking. Thus, it is generally safer than calling timedWaitRelativeWithHandshake(long). But, its reliance on threading subsystem accounting methods may mean that it cannot be used in certain contexts (say, the threading subsystem itself).

This method will ensure that if it blocks, it does so with the mutex not held. This is useful for cases where the subsystem that requested you to block needs to acquire the lock you were trying to acquire when the blocking request came.

Parameters:

delayNanos - the number of nanoseconds that need to pass from the call of this method until the wait is over when no call to broadcast() occurs in the meantime

timedWaitRelativeWithHandshakeImpl

private void timedWaitRelativeWithHandshakeImpl(long delayNanos)

broadcast

public void broadcast()

Send a broadcast, which should awaken anyone who is currently blocked in any of the wait methods. This method should (in principle) be non-blocking, and, as such, it does not notify the threading subsystem that it is blocking.

lockedBroadcastNoHandshake

public void lockedBroadcastNoHandshake()

Send a broadcast after first acquiring the lock. Release the lock after sending the broadcast. In most cases where you want to send a broadcast but you don't need to acquire the lock to set the condition that the other thread(s) are waiting on, you want to call this method instead of broadcast().

lockNoHandshake

public static boolean lockNoHandshake(Monitor l)

unlock

public static void unlock(boolean b,
                          Monitor l)

lockWithHandshake

public static void lockWithHandshake(Monitor m1,
                                     Word priority1,
                                     Monitor m2,
                                     Word priority2)