[concurrency-interest] Instrumentation for locks

Doug Lea dl@cs.oswego.edu
Wed, 17 Sep 2003 13:10:23 -0400


Adam (and anyone else interested in lock instrumentation),

I put out some tentative changes in ReentrantLock at:

http://gee.cs.oswego.edu/dl/concurrent/dist/docs/java/util/concurrent/locks/ReentrantLock.html
http://gee.cs.oswego.edu/dl/concurrent/dist/docs/java/util/concurrent/locks/ReentrantLock.ReentrantLockCondition.html

These establish what I hope is a useful basis for instrumentation and
monitoring without otherwise changing semantics or performance of main
locking methods. The monitoring-based ReentrantLock methods are also
pasted in below. (There are similar methods for Conditions).

The idea here, that we hadn't previously appreciated, is that most
people adding instrumentation do not want to make a full new
Lock/Condition class just to do so; they instead usually want to
subclass or adapt one of the standard ones. The new methods cannot
support all such usages, but I think should nicely support the most
common ones. If anyone believes otherwise, please let us know.

Thanks again for prodding us into this!


public boolean isLocked()
    Queries if this lock is held by any thread. This method is
    designed for use in monitoring of the system state, not for
    synchronization control.
    Returns:
        true if any thread holds this lock and false otherwise.

public int getLockQueueLength()
    Returns an estimate of the number of threads waiting to acquire
    this lock. The value is only an estimate because the number of
    threads may change dynamically while this method traverses
    internal data structures. This method is designed for use in
    monitoring of the system state, not for synchronization control.
    Returns:
        the estimated number of threads waiting for this lock

protected Collection getQueuedThreads()
    Returns a collection containing threads that may be waiting to
    acquire this lock. Because the actual set of threads may change
    dynamically while constructing this result, the returned
    collection is only a best-effort estimate. The elements of the
    returned collection are in no particular order. This method is
    designed to facilate construction of subclasses that provide more
    extensive lock monitoring facilities.
    Returns:
        the collection of threads

protected Thread getCurrentOwner()
    Returns the thread that currently owns the lock, or null if not
    owned. Note that the owner may be momentarily null even if there
    are threads trying to acquire the lock but have not yet done
    so. This method is designed to facilate construction of subclasses
    that provide more extensive lock monitoring facilities.
    Returns:
        the owner, or null if not owned.

-- 
Doug Lea, Computer Science Department, SUNY Oswego, Oswego, NY 13126 USA
dl@cs.oswego.edu 315-312-2688 FAX:315-312-5424 http://gee.cs.oswego.edu/