[foreign-jextract] RFR: Update memory access and linker documents

[Jorn Vernee]

On Wed, 24 Mar 2021 19:17:58 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This patch updates the two documents describing usage of the foreign memory access and foreign linker API.

doc/panama_ffi.md line 66:

> 64: MemorySegment size = MemorySegment.allocateNative(C_INT);
> 65: MemoryAccess.setInt(size, 5);
> 66: foo.invokeExact(42, size);

I think this should call `size.address()` to be equivalent with the C code. Also, reachability of the segment is problematic in that case, so maybe this should switch to using an explicit resource scope.

doc/panama_ffi.md line 78:

> 76: 
> 77: ```java
> 78: MemorySegment size = SegmentAllocator.ofDefault().allocate(C_INT, 5);

Same here

doc/panama_ffi.md line 135:

> 133:     MemorySegment upcallStub(MethodHandle target, FunctionDescriptor function, ResourceScope scope);
> 134:     MemorySegment upcallStub(MethodHandle target, FunctionDescriptor function);
> 135:     ...

We also now have the downcallHandle overload that takes a SegmentAllocator

doc/panama_ffi.md line 198:

> 196: 
> 197: ```java
> 198: long len = strlen.invokeExact(CLinker.toCString("Hello").address()); // 5

Segment reachability here is problematic as well.

doc/panama_ffi.md line 213:

> 211: long len = strlen_virtual.invokeExact(
> 212: 	LibraryLookup.ofDefault().lookup("strlen").get()
> 213: 	CLinker.toCString("Hello").address()

Here as well

doc/panama_ffi.md line 279:

> 277: 
> 278: ```java
> 279: MemorySegment array = SegmentAllocator.ofDefault().allocateArray(new int[] { 0, 9, 3, 4, 6, 5, 1, 8, 2, 7 }));

Same here

doc/panama_memaccess.md line 41:

> 39: for (int i = 0 ; i < values.length ; i++) {
> 40:     int x = MemoryAccess.getIntAtIndex(segment, i);
> 41:     int y = MemoryAccess.getIntAtIndex(segment, (i * 2) + 1);

You forgot to construct the `Point` here.

Also, I don't think the index computaions are correct in this? Would have expected `i += 2` in the loop header, and then an access at `i` for x and `i+1` for y.

doc/panama_memaccess.md line 55:

> 53:     int x = intBuffer.get(i);
> 54:     int y = intBuffer.get((i * 2) + 1);
> 55: }

Same here

doc/panama_memaccess.md line 99:

> 97: 2. a *logical* index, which is used to select the element of the sequence we want to access (as the layout path used to construct these var handles contains one free dimension)
> 98: 
> 99: Note that memory access var handles (as any other var handle) are *strongly* typed; and to get maximum efficiency, it is generally necessary to introduce casts to make sure that the access coordinates match the expected types — in this case we have to cast `i` into a `long`; similarly, since the signature polymorphic method `VarHandle::get` notionally returns `Object` a cast is necessary to force the right return type the var handle operation.

Maybe it's good to mention `VarHandle::withInvokeExactBehavior` at this point as well, to help enforce the type.

doc/panama_memaccess.md line 117:

> 115: Here, we create a new *confined* resource scope, which is then used when creating a mapped segment; this means that the lifecycle of the `mapped` segment will be tied to that of the resource scope, and that accessing the segment (e.g. dereference) *after* `scope` has been closed will not be possible.
> 116: 
> 117: As this example alludes to, resource scopes can come in many flavors: they can be *confined* (where access is restricted to the thread which created the segment), *shared* <a href="#2"><sup>2</sup></a> (where access can occur in any thread) and can be optionally associated with a `Cleaner` object, which would take care of performing implicit deallocation, in case the resource scope becomes *unreachable* and the `close` method has not been called by the user. In fact, all the memory segments we have seen previously were associated with the so called *default* scope: a shared scope which does not support deterministic deallocation (e.g. calling `close` will fail), and whose resources are managed by a `Cleaner`.

s/segment/scope
Suggestion:

As this example alludes to, resource scopes can come in many flavors: they can be *confined* (where access is restricted to the thread which created the scope), *shared* <a href="#2"><sup>2</sup></a> (where access can occur in any thread) and can be optionally associated with a `Cleaner` object, which would take care of performing implicit deallocation, in case the resource scope becomes *unreachable* and the `close` method has not been called by the user. In fact, all the memory segments we have seen previously were associated with the so called *default* scope: a shared scope which does not support deterministic deallocation (e.g. calling `close` will fail), and whose resources are managed by a `Cleaner`.

doc/panama_memaccess.md line 168:

> 166: 
> 167: int sum = StreamSupport.stream(MemorySegment.spliterator(segment, seq_bulk), true)
> 168:                 .mapToInt(slice -> {

The indentation seems off in this snippet

-------------

PR: https://git.openjdk.java.net/panama-foreign/pull/475