Can we improve the charset parameter Javadoc in PrintStream?
Hi, When viewing the Javadoc of PrintStream, I noticed that the Javadocs of the constructors involving charsets seems to be a bit lacking. In most cases, these just mention something like "a charset" instead of saying what it's used for. While the class description specifies that, I think it could also be present in the parameter information of the constructors since PrintStream is a commonly used class. - The second parameter of PrintStream(File, String) is named "csn" and described as "The name of a supported charset". I suggest naming the parameter "encoding" and changing the description to "The name of a supported character encoding to be used for be used for converting characters to bytes" (with the appropriate link). This would be consistent with the PrintStream(OutputStream, boolean, String) constructor. - The second parameter of PrintStream(File, Charset) is described as "A charset". I think this could be changed to "The charset used for converting characters to bytes" or similar. - The third parameter of PrintStream(OutputStream, boolean, String) is named "encoding" and described as "The name of a supported character encoding". This could be changed to "The name of a supported character encoding to be used for be used for converting characters to bytes". - The third parameter of PrintStream(OutputStream, boolean, Charset) is described as "A charset". I suggest changing this to "The charset used for converting characters to bytes". Instead of using "encoding" for the String parameter names, "charsetName" would be another option. In this case, I would suggest something like "The name of a supported charset to be used for be used for converting characters to bytes". If wanted, I can write a pull request for this but as I don't have JBS access, I can't create the issue and CSR by myself. Yours, Daniel smime.p7s Description: S/MIME Cryptographic Signature
Re: yield return based on Continuations
Thank you for your interest,
I'll also include loom-dev with this mail.
Yours,
Daniel
Am 28.08.2023 um 11:12 schrieb Alan Bateman:
This looks fun! It's probably best to bring this to loom-dev. In its
archives you'll find several discussions about generators as several
people have been interested in that topic. Even when thread confined,
the main concern has been that exotic control flow yields leads to
surprising behavior with many of the existing constructs, e.g. in your
example think about behavior with finally blocks, try-with-resources,
locks, ... when the iterator is not fully consumed.
-Alan
On 28/08/2023 09:43, Daniel Schmid wrote:
Hi,
After seeing the JVM Language Summit talk on Continuations
(https://www.youtube.com/watch?v=6nRS6UiN7X0), I thought about it
being possible to implement something like "yield return" in
languages like C# (or "yield" in Python) based on Continuations.
Kotlin has implemented a similar feature as well:
https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.sequences/-sequence-scope/yield.html
Now that Continuations are in the JDK, I feel like it can be used as
a good primitive and now is a good time to start about thinking about
adding something like this as a Java feature or the libraries.
After my experiments and some discussion with another developer named
Peter Eastham (https://github.com/Crain-32), I was able to come up
with an implementation/proof-of-concept allowing something like the
following:
public static void main(String[] args) {
System.out.println("main thread: " + Thread.currentThread());
for (String s : Yielder.create(YieldReturnTest::someMethod)) {
System.out.println("Text: " + s);
}
}
private static void someMethod(Yielder y) {
y.yield("Hello - " + Thread.currentThread());
System.out.println("between yields");
y.yield("World - " + Thread.currentThread());
for (String s : Yielder.create(YieldReturnTest::otherMethod)) {
y.yield("nested: " + s);
}
y.yield("bye - " + Thread.currentThread());
}
private static void otherMethod(Yielder y) {
y.yield("it can");
y.yield("also be");
y.yield("nested");
}
output:
main thread: Thread[#1,main,5,main]
Text: Hello - Thread[#1,main,5,main]
between yields
Text: World - Thread[#1,main,5,main]
Text: nested: it can
Text: nested: also be
Text: nested: nested
Text: bye - Thread[#1,main,5,main]
In this example, the method reference passed to the Yielder.create
method would be run in a Continuation while y.yield would yield the
Continuation and make the value available to the iterator (next()
calls Continuation#run).
You can find a simple proof-of-concept of that here:
https://github.com/danthe1st/ContinuationYieldReturn
Would it be possible to add something like this to the JDK libraries?
I feel like it might be a useful addition to the JDK libraries as it
simplifies creating sequences a lot.
Originally, I thought about whether it might be a good idea to add
syntax for this but after building that proof-of-concept, it looks
like it would be sufficient to add this to the libraries and using
methods like this seems pretty natural.
One thing I am concerned with this approach (opposed to an approach
that involves changing syntax) is that it would be possible that the
method suddenly runs in a different thread if the
hasNext()/next()-calls of the Iterator chang the thread they are used
in at some point. While Continuations allow this behaviour, it might
seem a weird to developers who don't know how Continuations work.
But aside from that issue with iterations switching threads, this
approach seems pretty natural to me.
Yours,
Daniel
smime.p7s
Description: S/MIME Cryptographic Signature
yield return based on Coroutines
Hi,
After seeing the JVM Language Summit talk on Continuations
(https://www.youtube.com/watch?v=6nRS6UiN7X0), I thought about it being
possible to implement something like "yield return" in languages like C#
(or "yield" in Python) based on Continuations.
Kotlin has implemented a similar feature as well:
https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.sequences/-sequence-scope/yield.html
Now that Continuations are in the JDK, I feel like it can be used as a
good primitive and now is a good time to start about thinking about
adding something like this as a Java feature or the libraries.
After my experiments and some discussion with another developer named
Peter Eastham (https://github.com/Crain-32), I was able to come up with
an implementation/proof-of-concept allowing something like the following:
public static void main(String[] args) {
System.out.println("main thread: " + Thread.currentThread());
for (String s : Yielder.create(YieldReturnTest::someMethod)) {
System.out.println("Text: " + s);
}
}
private static void someMethod(Yielder y) {
y.yield("Hello - " + Thread.currentThread());
System.out.println("between yields");
y.yield("World - " + Thread.currentThread());
for (String s : Yielder.create(YieldReturnTest::otherMethod)) {
y.yield("nested: " + s);
}
y.yield("bye - " + Thread.currentThread());
}
private static void otherMethod(Yielder y) {
y.yield("it can");
y.yield("also be");
y.yield("nested");
}
output:
main thread: Thread[#1,main,5,main]
Text: Hello - Thread[#1,main,5,main]
between yields
Text: World - Thread[#1,main,5,main]
Text: nested: it can
Text: nested: also be
Text: nested: nested
Text: bye - Thread[#1,main,5,main]
In this example, the method reference passed to the Yielder.create
method would be run in a Continuation while y.yield would yield the
Continuation and make the value available to the iterator (next() calls
Continuation#run).
You can find a simple proof-of-concept of that here:
https://github.com/danthe1st/ContinuationYieldReturn
Would it be possible to add something like this to the JDK libraries?
I feel like it might be a useful addition to the JDK libraries as it
simplifies creating sequences a lot.
Originally, I thought about whether it might be a good idea to add
syntax for this but after building that proof-of-concept, it looks like
it would be sufficient to add this to the libraries and using methods
like this seems pretty natural.
One thing I am concerned with this approach (opposed to an approach that
involves changing syntax) is that it would be possible that the method
suddenly runs in a different thread if the hasNext()/next()-calls of the
Iterator chang the thread they are used in at some point. While
Continuations allow this behaviour, it might seem a weird to developers
who don't know how Continuations work.
But aside from that issue with iterations switching threads, this
approach seems pretty natural to me.
Yours,
Daniel
smime.p7s
Description: S/MIME Cryptographic Signature
Wrong exception in ComputedConstant#orElse Javadoc
When viewing the propsed Javadoc of ComputedConstant#orElse (https://cr.openjdk.org/~pminborg/computed-constant/api/java.base/java/lang/ComputedConstant.html#orElse(V)),it mentions throwing an NoSuchElementException in case the element cannot be bound. However, the Javadoc also mentions returning the passed value in that case. If we take a look at the code for that in the Leyden repository (https://github.com/openjdk/leyden/blob/b9219784cc277417dc112a7fbf652bdc021cf806/src/java.base/share/classes/jdk/internal/constant/AbstractComputedConstant.java#L127 and https://github.com/openjdk/leyden/blob/b9219784cc277417dc112a7fbf652bdc021cf806/src/java.base/share/classes/jdk/internal/constant/AbstractComputedConstant.java#L161C27-L161C27), we can see that "rethrow" is false and no NoSuchElementException is thrown (https://github.com/openjdk/leyden/blob/b9219784cc277417dc112a7fbf652bdc021cf806/src/java.base/share/classes/jdk/internal/constant/AbstractComputedConstant.java#L183-L186). I think the "@throws NoSuchElementException" should be removed from ComputedConstant#orElse (https://github.com/openjdk/leyden/blob/b9219784cc277417dc112a7fbf652bdc021cf806/src/java.base/share/classes/java/lang/ComputedConstant.java#L294C19-L294C19) Yours, Daniel smime.p7s Description: S/MIME Cryptographic Signature
Re: 8311517: Adapt ArrayList Javadoc for sequenced collections
I could create a PR for this if wanted. I would suggest changing > The size, isEmpty, get, set, iterator, and listIterator operations run in constant time. The add operation runs in amortized constant time, that is, adding n elements requires O(n) time. All of the other operations run in linear time (roughly speaking). The constant factor is low compared to that for the LinkedList implementation. to > The size, isEmpty, get, set, iterator, listIterator, and reversed operations run in constant time. The add, addLast, and removeLast operations runs in amortized constant time, that is, adding n elements requires O(n) time. All of the other operations run in linear time (roughly speaking). The constant factor is low compared to that for the LinkedList implementation. Is there any other part of the documentation that should be changed? Note that I do not have an OpenJDK account as I haven't contributed to OpenJDK projects before (Though I did sign the OCA). Yours, Daniel Am 20.07.2023 um 17:04 schrieb Daniel Schmid: I could create a PR for this if wanted. I would suggest changing > The size, isEmpty, get, set, iterator, and listIterator operations run in constant time. The add operation runs in amortized constant time, that is, adding n elements requires O(n) time. All of the other operations run in linear time (roughly speaking). The constant factor is low compared to that for the LinkedList implementation. to > The size, isEmpty, get, set, iterator, listIterator, and reversed operations run in constant time. The add, addLast, and removeLast operations runs in amortized constant time, that is, adding n elements requires O(n) time. All of the other operations run in linear time (roughly speaking). The constant factor is low compared to that for the LinkedList implementation. Is there any other --- Hi Daniel, Core-libs-dev is indeed the correct alias for this documentation issue. Create an issue to track: JDK-8311517 <https://bugs.openjdk.org/browse/JDK-8311517> Regards, Roger On 7/1/23 3:35 PM, Daniel Schmid wrote: The JEP for sequenced collection (https://openjdk.org/jeps/431) would add addFirst(), removeFirst() and reversed() methods to lists. However, the Javadoc of List mentions: > The size, isEmpty, get, set, iterator, and listIterator operations run in constant time. The add operation runs in amortized constant time, that is, adding n elements requires O(n) time. All of the other operations run in linear time (roughly speaking). The constant factor is low compared to that for the LinkedList implementation. This is (at the time of writing) still the case for the jdk21-fork (https://github.com/openjdk/jdk21/blob/430ffe7ae691d097de2818391531522f2538431d/src/java.base/share/classes/java/util/ArrayList.java#L42-L47). I think this should be updated to include that reversed() runs in constant time while addFirst() and removeFirst() run in linear time. I originally posted this in the core-libs-dev mailing list (https://mail.openjdk.org/pipermail/core-libs-dev/2023-June/107328.html) but it seems like that mail has been overlooked due to the amount of other content with PRs etc. there. Yours, Daniel smime.p7s Description: S/MIME Cryptographic Signature
Adapt ArrayList Javadoc for sequenced collections
Dear members of the core-libs-dev mailing list, The JEP for sequenced collection (https://openjdk.org/jeps/431) would add addFirst(), removeFirst() and reversed() methods to lists. However, the Javadoc of List mentions: > The size, isEmpty, get, set, iterator, and listIterator operations run in constant time. The add operation runs in amortized constant time, that is, adding n elements requires O(n) time. All of the other operations run in linear time (roughly speaking). The constant factor is low compared to that for the LinkedList implementation. This is (at the time of writing) still the case for the jdk21-fork (https://github.com/openjdk/jdk21/blob/430ffe7ae691d097de2818391531522f2538431d/src/java.base/share/classes/java/util/ArrayList.java#L42-L47). I think this should be updated to include that reversed() runs in constant time while addFirst() and removeFirst() run in linear time. Yours, Daniel smime.p7s Description: S/MIME Cryptographic Signature
