United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-7065550 : Clarify AtomicBoolean.lazySet() so it's clear how this method compares to set()

Details
Type:
Enhancement
Submit Date:
2011-07-11
Status:
Open
Updated Date:
2012-03-20
Project Name:
JDK
Resolved Date:
Component:
core-libs
OS:
windows_7
Sub-Component:
java.util.concurrent
CPU:
x86
Priority:
P4
Resolution:
Unresolved
Affected Versions:
7
Targeted Versions:

Related Reports
Relates:

Sub Tasks

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

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.
                                     
2011-07-13
PUBLIC COMMENTS

Accepting for now. Possibly update the lazySet docs to reference the description in the atomic package documentation.
                                     
2011-07-13



Hardware and Software, Engineered to Work Together