From pavel.rappo at gmail.com Fri Oct 3 20:54:40 2025 From: pavel.rappo at gmail.com (Pavel Rappo) Date: Fri, 3 Oct 2025 21:54:40 +0100 Subject: Clarification to TimeUnit.convert(Duration) Message-ID: TimeUnit.covert(Duration)'s receiver is an enum constant. Different constants result in different converstions. So, it's a bit vague to contrast "this method" to a specific conversion (in this case, nanoseconds). Would this small clarification benefit the reader? If so, I could create a PR. diff --git a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java index d116fb9b22b..6135461cf48 100644 --- a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java +++ b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java @@ -203,8 +203,11 @@ public long convert(long sourceDuration, TimeUnit sourceUnit) { * is equivalent to {@code n} (in the absence of overflow). * * @apiNote - * This method differs from {@link Duration#toNanos()} in that it - * does not throw {@link ArithmeticException} on numeric overflow. + * {@link #NANOSECONDS}{@code .convert(Duration)} and + * {@link #MILLISECONDS}{@code .convert(Duration)} differ from + * {@link Duration#toNanos()} and {@link Duration#toMillis()} respectively + * in that they do not throw {@link ArithmeticException} on numeric + * overflow. * * @param duration the time duration * @return the converted duration in this unit, From pavel.rappo at gmail.com Mon Oct 13 17:11:25 2025 From: pavel.rappo at gmail.com (Pavel Rappo) Date: Mon, 13 Oct 2025 18:11:25 +0100 Subject: Clarification to TimeUnit.convert(Duration) In-Reply-To: References: Message-ID: ping On Fri, Oct 3, 2025 at 9:54?PM Pavel Rappo wrote: > > TimeUnit.covert(Duration)'s receiver is an enum constant. Different > constants result in different converstions. So, it's a bit vague to > contrast "this method" to a specific conversion (in this case, > nanoseconds). Would this small clarification benefit the reader? If > so, I could create a PR. > > diff --git a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > index d116fb9b22b..6135461cf48 100644 > --- a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > +++ b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > @@ -203,8 +203,11 @@ public long convert(long sourceDuration, TimeUnit > sourceUnit) { > * is equivalent to {@code n} (in the absence of overflow). > * > * @apiNote > - * This method differs from {@link Duration#toNanos()} in that it > - * does not throw {@link ArithmeticException} on numeric overflow. > + * {@link #NANOSECONDS}{@code .convert(Duration)} and > + * {@link #MILLISECONDS}{@code .convert(Duration)} differ from > + * {@link Duration#toNanos()} and {@link Duration#toMillis()} respectively > + * in that they do not throw {@link ArithmeticException} on numeric > + * overflow. > * > * @param duration the time duration > * @return the converted duration in this unit, From chen.l.liang at oracle.com Tue Oct 14 21:44:30 2025 From: chen.l.liang at oracle.com (Chen Liang) Date: Tue, 14 Oct 2025 21:44:30 +0000 Subject: Clarification to TimeUnit.convert(Duration) In-Reply-To: References: Message-ID: Hi Pavel, I don't think specifying the enum constants is particularly meaningful - maybe future constants also have overflowing operations. Wording like "conversion methods on Duration" instead of just toNanos/toMillis would be more helpful though. Chen ________________________________ From: concurrency-discuss on behalf of Pavel Rappo Sent: Monday, October 13, 2025 10:11 AM To: concurrency-discuss at openjdk.org Subject: Re: Clarification to TimeUnit.convert(Duration) ping On Fri, Oct 3, 2025 at 9:54?PM Pavel Rappo wrote: > > TimeUnit.covert(Duration)'s receiver is an enum constant. Different > constants result in different converstions. So, it's a bit vague to > contrast "this method" to a specific conversion (in this case, > nanoseconds). Would this small clarification benefit the reader? If > so, I could create a PR. > > diff --git a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > index d116fb9b22b..6135461cf48 100644 > --- a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > +++ b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > @@ -203,8 +203,11 @@ public long convert(long sourceDuration, TimeUnit > sourceUnit) { > * is equivalent to {@code n} (in the absence of overflow). > * > * @apiNote > - * This method differs from {@link Duration#toNanos()} in that it > - * does not throw {@link ArithmeticException} on numeric overflow. > + * {@link #NANOSECONDS}{@code .convert(Duration)} and > + * {@link #MILLISECONDS}{@code .convert(Duration)} differ from > + * {@link Duration#toNanos()} and {@link Duration#toMillis()} respectively > + * in that they do not throw {@link ArithmeticException} on numeric > + * overflow. > * > * @param duration the time duration > * @return the converted duration in this unit, -------------- next part -------------- An HTML attachment was scrubbed... URL: From pavel.rappo at gmail.com Tue Oct 14 22:00:06 2025 From: pavel.rappo at gmail.com (Pavel Rappo) Date: Tue, 14 Oct 2025 23:00:06 +0100 Subject: Clarification to TimeUnit.convert(Duration) In-Reply-To: References: Message-ID: It's not really a specification, as it's @apiNote. IMO, referring to specific methods is good, it aids quick grasping of the idea. No matter what method Duration might have later, e.g. toMicros(), any sub-second conversion method can overflow. Maybe we can say that and add a few examples of the conversion methods that do? On Tue, Oct 14, 2025 at 10:44?PM Chen Liang wrote: > > Hi Pavel, > > I don't think specifying the enum constants is particularly meaningful - maybe future constants also have overflowing operations. Wording like "conversion methods on Duration" instead of just toNanos/toMillis would be more helpful though. > > Chen > ________________________________ > From: concurrency-discuss on behalf of Pavel Rappo > Sent: Monday, October 13, 2025 10:11 AM > To: concurrency-discuss at openjdk.org > Subject: Re: Clarification to TimeUnit.convert(Duration) > > ping > > On Fri, Oct 3, 2025 at 9:54?PM Pavel Rappo wrote: > > > > TimeUnit.covert(Duration)'s receiver is an enum constant. Different > > constants result in different converstions. So, it's a bit vague to > > contrast "this method" to a specific conversion (in this case, > > nanoseconds). Would this small clarification benefit the reader? If > > so, I could create a PR. > > > > diff --git a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > > b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > > index d116fb9b22b..6135461cf48 100644 > > --- a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > > +++ b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > > @@ -203,8 +203,11 @@ public long convert(long sourceDuration, TimeUnit > > sourceUnit) { > > * is equivalent to {@code n} (in the absence of overflow). > > * > > * @apiNote > > - * This method differs from {@link Duration#toNanos()} in that it > > - * does not throw {@link ArithmeticException} on numeric overflow. > > + * {@link #NANOSECONDS}{@code .convert(Duration)} and > > + * {@link #MILLISECONDS}{@code .convert(Duration)} differ from > > + * {@link Duration#toNanos()} and {@link Duration#toMillis()} respectively > > + * in that they do not throw {@link ArithmeticException} on numeric > > + * overflow. > > * > > * @param duration the time duration > > * @return the converted duration in this unit, From chen.l.liang at oracle.com Tue Oct 14 22:50:26 2025 From: chen.l.liang at oracle.com (Chen Liang) Date: Tue, 14 Oct 2025 22:50:26 +0000 Subject: [External] : Re: Clarification to TimeUnit.convert(Duration) In-Reply-To: References: Message-ID: I think that would be a great way to go ahead, providing generality while also showing applicable examples. Confidential ? Oracle Internal ________________________________ From: Pavel Rappo Sent: Tuesday, October 14, 2025 3:00 PM To: Chen Liang Cc: concurrency-discuss at openjdk.org Subject: [External] : Re: Clarification to TimeUnit.convert(Duration) It's not really a specification, as it's @apiNote. IMO, referring to specific methods is good, it aids quick grasping of the idea. No matter what method Duration might have later, e.g. toMicros(), any sub-second conversion method can overflow. Maybe we can say that and add a few examples of the conversion methods that do? On Tue, Oct 14, 2025 at 10:44?PM Chen Liang wrote: > > Hi Pavel, > > I don't think specifying the enum constants is particularly meaningful - maybe future constants also have overflowing operations. Wording like "conversion methods on Duration" instead of just toNanos/toMillis would be more helpful though. > > Chen > ________________________________ > From: concurrency-discuss on behalf of Pavel Rappo > Sent: Monday, October 13, 2025 10:11 AM > To: concurrency-discuss at openjdk.org > Subject: Re: Clarification to TimeUnit.convert(Duration) > > ping > > On Fri, Oct 3, 2025 at 9:54?PM Pavel Rappo wrote: > > > > TimeUnit.covert(Duration)'s receiver is an enum constant. Different > > constants result in different converstions. So, it's a bit vague to > > contrast "this method" to a specific conversion (in this case, > > nanoseconds). Would this small clarification benefit the reader? If > > so, I could create a PR. > > > > diff --git a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > > b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > > index d116fb9b22b..6135461cf48 100644 > > --- a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > > +++ b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java > > @@ -203,8 +203,11 @@ public long convert(long sourceDuration, TimeUnit > > sourceUnit) { > > * is equivalent to {@code n} (in the absence of overflow). > > * > > * @apiNote > > - * This method differs from {@link Duration#toNanos()} in that it > > - * does not throw {@link ArithmeticException} on numeric overflow. > > + * {@link #NANOSECONDS}{@code .convert(Duration)} and > > + * {@link #MILLISECONDS}{@code .convert(Duration)} differ from > > + * {@link Duration#toNanos()} and {@link Duration#toMillis()} respectively > > + * in that they do not throw {@link ArithmeticException} on numeric > > + * overflow. > > * > > * @param duration the time duration > > * @return the converted duration in this unit, -------------- next part -------------- An HTML attachment was scrubbed... URL: