JDK-7065550 : Clarify AtomicBoolean.lazySet() so it's clear how this method compares to set()
  • Type: Enhancement
  • Component: core-libs
  • Sub-Component: java.util.concurrent
  • Affected Version: 7
  • Priority: P4
  • Status: Open
  • Resolution: Unresolved
  • OS: windows_7
  • CPU: x86
  • Submitted: 2011-07-11
  • Updated: 2012-03-20
Related Reports
Relates :  
JDK-6275329 - Add lazySet methods to atomic classes
Description
A DESCRIPTION OF THE REQUEST :
Please update the documentation of AtomicXXX.lazySet(). Currently it reads:
http://download.oracle.com/javase/6/docs/api/java/util/concurrent/atomic/AtomicReference.html#lazySet(V)
"Eventually sets to the given value." which doesn't really explain when it should be used versus set().

You can find a more detailed explanation of lazySet() here: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6275329

Please simplify the explanation and update the Javadoc so it's clear how this method compares to set(), and when it is appropriate to use it.

JUSTIFICATION :
It's unclear when it's appropriate to use the method.
Comments
PUBLIC COMMENTS Accepting for now. Possibly update the lazySet docs to reference the description in the atomic package documentation.
13-07-2011
PUBLIC COMMENTS Part of the documentation for lazySet is in the atomic package documentation where memory synchronization affects are described: - lazySet has the memory effects of writing (assigning) a volatile variable except that it permits reorderings with subsequent (but not previous) memory actions that do not themselves impose reordering constraints with ordinary non-volatile writes. Among other usage contexts, lazySet may apply when nulling out, for the sake of garbage collection, a reference that is never accessed again. This is essentially the documentation that arose from the description in 6275329. It seems to me that what may be missing here is a link from the laztSet method docs back to the relevant section of the package docs. Though there is a presumption on the part of the JSR-166 expert group that anyone attempting to use tha atomics package has familiarised themselves with the information provided in the package docs, as this is where all the core, common semantics are described.
13-07-2011