New candidate JEP: 419: Foreign Function & Memory API (Second Incubator)

[Sebastian Stenzel]

I looked at these two lines from the example on the JEP page:

    MemorySegment cString = MemorySegment.allocateNative(javaStrings[i].length + 1, ...);
    cString.setUtf8String(0, javaStrings[i]);

Just looking at the code, I have to guess, where exactly null-termination happens. There are two options:

* Either `allocateNative` fills the allocated memory with zeros - while inefficient, this might be a legitimate assumption for people only knowing Java
* Or `setUtf8String` adds a null byte - which should then be documented somewhere

So I looked at the JavaDoc and I believe the documentation can be improved for both methods:

First of all, regarding `allocateNative`, I think it should be explicitly stated that allocation does not mean initialization. While this might be obvious for most people here, we should keep in mind that by making the non-Java world more accessible for Java developers, we should do our best to warn those people about the different laws of nature they need to obey when entering this world.


Furthermore, here are my two cents about the `setUtf8String` JavaDoc. Currently it says:

> Writes a UTF-8 encoded, null-terminated string into this segment at given offset.

... which, being nit-picky, I read as "please pass a UTF-8 encoded, null terminated string to this method". Instead, I'd suggest:

> Writes the given string into this segment at given offset, converting it to a null-terminated byte sequence using UTF-8 encoding.


Last but not least, I'd like to note that the size of the allocated segment in the aforementioned example depends on the string length (should be `length()`), which is inaccurate when using multi-byte unicode code points. Just thought, I'd mention it, as people may copy this code.


> On 12. Oct 2021, at 00:41, mark.reinhold at oracle.com wrote:
> 
> https://openjdk.java.net/jeps/419
> 
>  Summary: Introduce an API by which Java programs can interoperate with
>  code and data outside of the Java runtime. By efficiently invoking
>  foreign functions (i.e., code outside the JVM), and by safely accessing
>  foreign memory (i.e., memory not managed by the JVM), the API enables
>  Java programs to call native libraries and process native data without
>  the brittleness and danger of JNI.
> 
> - Mark