[NEW BUG][JDK10] TimeUnit.timedWait(Object obj, long timeout) doc should emphasize possibility of IllegalMonitorStateException

[Christoph Dreis]

Hi,

I don't know if this is considered a real bug or just a lack of
documentation, but I found that although the example in the documentation of
TimeUnit.timedWait(Object obj, long timeout) shows the correct usage of the
method, I think at least the documentation should emphasize the possibility
of an IllegalMonitorStateException in case it isn't executed inside a
synchronized block.

The method seems to be not used inside the JDK itself after all, but people
might use it.

Please find a minimal reproduction and a possible documentation patch below.
In case it is considered worthwhile I'd be happy if this is sponsored.

Cheers,
Christoph

===== MINIMAL REPRO ======
public class Main {

    public static void main(String[] args) {
        Lock lock = new ReentrantLock();
        try {
            TimeUnit.MILLISECONDS.timedWait(lock, 1);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
    }

}

====== PATCH ==========
diff -r 67aa34b019e1
src/java.base/share/classes/java/util/concurrent/TimeUnit.java
--- a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java    Mon
Nov 06 17:48:00 2017 -0800
+++ b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java    Tue
Nov 07 23:09:24 2017 +0100
@@ -356,6 +356,8 @@
      * @param timeout the maximum time to wait. If less than
      * or equal to zero, do not wait at all.
      * @throws InterruptedException if interrupted while waiting
+     * @throws IllegalMonitorStateException if not executed inside a
+     *         synchronized block
      */
     public void timedWait(Object obj, long timeout)
             throws InterruptedException {