Doug Lea writes:

In a discussion with David Holmes and Dave Dice, I noticed that we
need improved documentation about LockSupport.park to warn people
that they can't use, and should avoid, implicitly nested park/unpark
constructions.

Any objections to the following clarification?

Index: LockSupport.java
===================================================================
RCS file:
/export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/locks/LockSupport.java,v
retrieving revision 1.19
diff -c -r1.19 LockSupport.java
*** LockSupport.java 14 Sep 2005 20:15:30 -0000 1.19
--- LockSupport.java 22 Mar 2006 12:51:30 -0000
***************
*** 47,53 ****
    *
    * <p>These methods are designed to be used as tools for creating
    * higher-level synchronization utilities, and are not in themselves
! * useful for most concurrency control applications.
    *
    * <p><b>Sample Usage.</b> Here is a sketch of a First-in-first-out
    * non-reentrant lock class.
--- 47,59 ----
    *
    * <p>These methods are designed to be used as tools for creating
    * higher-level synchronization utilities, and are not in themselves
! * useful for most concurrency control applications. The <tt>park</tt> method
! * is designed for use only in constructions of the form:
! * <pre>while (!canProceed()) { ... LockSupport.park(this); }</pre>
! * where neither <tt>canProceed</tt> nor any other actions prior to
! * the call to <tt>park</tt> entail locking or blocking. Because only
! * one permit is associated with each thread, any intermediary uses of
! * <tt>park</tt> could interfere with its intended effects.
    *
    * <p><b>Sample Usage.</b> Here is a sketch of a First-in-first-out
    * non-reentrant lock class.