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

[Martin Buchholz]

Thanks - you're right - I filed
https://bugs.openjdk.java.net/browse/JDK-8190889


On Tue, Nov 7, 2017 at 2:25 PM, Christoph Dreis <christoph.dreis at freenet.de>
wrote:

> 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 {
>
>