@GuardedBy annotation with java.util.concurrent.locks.ReadWriteLock

Question

What is a proper/preferred way to annotate fields that are protected with a ReadWriteLock so that tools like FindBugs can leverage the annotation? Should the name of the ReadWriteLock simply be written in the @GuardedBy annotation. Is there ever a reason to write the name of just the read lock, or just the write lock, in the @GuardedBy annotation? Does FindBugs, or other tools, even support ReadWriteLock in @GuardedBy?

Solution 1

At the time of this writing, @GuardedBy isn't fully implemented by Findbugs, and is mostly just for documentation. (It is partially implemented.)

I always use @GuardedBy("readwritelock") or the object that I use to synchronize.

For example of the latter:

class Example {
    private Object lock = new Object();

    @GuardedBy("lock")
    private Stuff innards = ...;

    public void work() {
        synchronized(lock) {
            workWith(innards.goop());
        }
    }        
}

Solution 2

Find bugs supports the following annotations:

net.jcip.annotations.GuardedBy
net.jcip.annotations.Immutable
net.jcip.annotations.NotThreadSafe
net.jcip.annotations.ThreadSafe

Usage of these GuardedBy annotation should be as follows:

@ThreadSafe  
public class Queue<E> implements java.util.Queue<E>  
{  
    private ConcurrentLinkedQueue readWriteLock;  

    @GuardedBy( value="readWriteLock" )  
    public boolean offer(E o)  
    {  
        return queue.offer( o ); 
    }  

}  

Comments

[Greg Mattes]

These annotations are also captured in JSR305. They can be seen in this reference implementation: code.google.com/p/jsr-305/source/browse/trunk/ri/src/main/ja‌​va/…

[Greg Mattes]

The name of the lock can be written more compactly like this: @GuardedBy("readWriteLock") -- the "value=" portion isn't explicitly required.

[Greg Mattes]

My question isn't really about basic usage. I'm trying to figure out whether a java.util.concurrent.locks.ReadWriteLock, which contains both a read lock and a write lock should be referred to in a @GuardedBy annotation as the whole ReadWriteLock, or by the individual read and write locks. And whether any of this is effective.

[Greg Mattes]

Thanks! Just a quick note, I don't know the state of the FindBugs art (hence I asked this question! :), but the link that mentions that the annotation might not be implemented appears to be four years old.

[Michael Deardeuff]

That project is very active, judging by the activity on the linked-to bug-tracker.

[Greg Mattes]

You mean the FindBugs project? Oh sure, it's alive and well. I meant the specific statement from four years ago that the GuardedBy annotation might not be implemented. I'm saying that the most recent FindBugs code might implemented it. Sorry if I misread/misunderstood something.

[Michael Deardeuff]

Likewise, but the link is still to their bug tracker. If it were my bug tracker, I would have searched for @guardedby when I did any updates to it. But then again, it isn't my bug tracker

[David Harkness]

@GregMattes - If one or the other, specify the individual read/write lock. Otherwise, specify the master lock.

[yvolk]

Unfortunately, it appears that the GuardedBy annotation does not work in FindBugs anymore. I stumbled upon this problem (FindBugs ignoring obvious bugs) and found this open ticket: sourceforge.net/p/findbugs/bugs/765