Package org.apache.hadoop.util

Class InstrumentedLock

java.lang.Object

org.apache.hadoop.util.InstrumentedLock

All Implemented Interfaces:

java.util.concurrent.locks.Lock

Direct Known Subclasses:

InstrumentedReadLock, InstrumentedWriteLock

@Private
@Unstable
public class InstrumentedLock
extends java.lang.Object
implements java.util.concurrent.locks.Lock

This is a debugging class that can be used by callers to track whether a specific lock is being held for too long and periodically log a warning and stack trace, if so. The logged warnings are throttled so that logs are not spammed. A new instance of InstrumentedLock can be created for each object that needs to be instrumented.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	InstrumentedLock.SuppressedSnapshot	Immutable class to capture a snapshot of suppressed log message stats.

Constructor Summary

Constructors

Constructor	Description
InstrumentedLock(java.lang.String name, org.slf4j.Logger logger, long minLoggingGapMs, long lockWarningThresholdMs)	Create a instrumented lock instance which logs a warning message when lock held time is above given threshold.
InstrumentedLock(java.lang.String name, org.slf4j.Logger logger, java.util.concurrent.locks.Lock lock, long minLoggingGapMs, long lockWarningThresholdMs)

Method Summary

Modifier and Type	Method	Description
protected void	check(long acquireTime, long releaseTime, boolean checkLockHeld)	Log a warning if the lock was held for too long.
protected java.util.concurrent.locks.Lock	getLock()
protected Timer	getTimer()
void	lock()
void	lockInterruptibly()
java.util.concurrent.locks.Condition	newCondition()
protected void	startLockTiming()	Starts timing for the instrumented lock.
boolean	tryLock()
boolean	tryLock(long time, java.util.concurrent.TimeUnit unit)
void	unlock()

Methods inherited from class java.lang.Object

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

Constructor Detail

InstrumentedLock

public InstrumentedLock(java.lang.String name,
                        org.slf4j.Logger logger,
                        long minLoggingGapMs,
                        long lockWarningThresholdMs)

Create a instrumented lock instance which logs a warning message when lock held time is above given threshold.

Parameters:

name - the identifier of the lock object

logger - this class does not have its own logger, will log to the given logger instead

minLoggingGapMs - the minimum time gap between two log messages, this is to avoid spamming to many logs

lockWarningThresholdMs - the time threshold to view lock held time as being "too long"

InstrumentedLock

public InstrumentedLock(java.lang.String name,
                        org.slf4j.Logger logger,
                        java.util.concurrent.locks.Lock lock,
                        long minLoggingGapMs,
                        long lockWarningThresholdMs)

Method Detail

lock

public void lock()

Specified by:

lock in interface java.util.concurrent.locks.Lock

lockInterruptibly

public void lockInterruptibly()
                       throws java.lang.InterruptedException

Specified by:

lockInterruptibly in interface java.util.concurrent.locks.Lock

Throws:

java.lang.InterruptedException

tryLock

public boolean tryLock()

Specified by:

tryLock in interface java.util.concurrent.locks.Lock

tryLock

public boolean tryLock(long time,
                       java.util.concurrent.TimeUnit unit)
                throws java.lang.InterruptedException

Specified by:

tryLock in interface java.util.concurrent.locks.Lock

Throws:

java.lang.InterruptedException

unlock

public void unlock()

Specified by:

unlock in interface java.util.concurrent.locks.Lock

newCondition

public java.util.concurrent.locks.Condition newCondition()

Specified by:

newCondition in interface java.util.concurrent.locks.Lock

startLockTiming

protected void startLockTiming()

Starts timing for the instrumented lock.

check

protected void check(long acquireTime,
                     long releaseTime,
                     boolean checkLockHeld)

Log a warning if the lock was held for too long. Should be invoked by the caller immediately AFTER releasing the lock.

Parameters:

acquireTime - - timestamp just after acquiring the lock.

releaseTime - - timestamp just before releasing the lock.

checkLockHeld - checkLockHeld.

getLock

protected java.util.concurrent.locks.Lock getLock()

getTimer

protected Timer getTimer()