Test Plan for Foreign-Memory Access API (Third Incubator)

Test Methodology

The JEP in question adds several new APIs, as well as inter-operating with some existing APIs. Both should be tested.

New APIs

• MemorySegment and MemoryAddress; These are classes with several thread-safety concerns. Data races should not be able to crash the VM. This can be verified using stress testing. More general API testing can be used to verify that unsafe operations are caught, and exceptions are thrown.
• MemoryAccessHandles provides methods for creating var handles that can be used to do foreign memory access, in tandem with MemorySegment. This uses among other things template files and runtime bytecode generation. Care should be taken when testing that the bytecode verifier is run on the generated classes when running test (since this is not always the case by default).
• The MemorLayout API; a hierarchy of classes that can be used to describe memory layouts. These should be tested through standard API testing based on the specification.

Interop with existing APIs

• ByteBuffer; it is possible to convert between a MemorySegment and a ByteBuffer. Testing should verify that existing ByteBuffer functionality continues to work, including JNI APIs such as GetDirectBufferAddress. Testing should also verify that converting between one type and the other (repeatedly) is a loss-less operation, in particularly: when converting from a MemorySegment to a ByteBuffer, all safety guarantees the MemorySegment implementation makes should continue to hold.
• The MemoryAccessHandles API also adds a set of var handle combinators. This required adding a new IndirectVarHandle subclass of VarHandle. Testing should verify that these new combinators, when used together with the plethora of existing var handle types, work as expected.

Benchmarking

• Since this is a performance sensitive API, benchmarks should be added that compare the performance of memory accesses to that of existing APIs such as Unsafe and ByteBuffer.

Test Inventory

Existing Tests

• Parts of the implementation of ByteBuffer had to be changed to work with MemorySegments. Existing tests for ByteBuffer can be used to verify that they keep functioning as expected.
• The test test/jdk/java/util/stream/test/org/openjdk/tests/java/util/stream/SpliteratorTest.java has been updated to test the spliterator functionality of MemorySegment
• Existing var handle tests in test/jdk/java/lang/invoke/VarHandles were adapted to run in several new configurations that apply trivial/identity adaptation, to test the added var handle combinators and IndirectVarHandle together with all the existing var handle kinds.

New Tests

• New tests have been added in test/jdk/java/foreign to test the new APIs.
• Benchmarks have been added to test/micro/org/openjdk/bench/jdk/incubator/foreign to test the performance of memory accesses, with and without loops.

Test Success Criteria

• At least 80% cyclomatic complexity test coverage
• 100% coverage of the public API
• Memory access performance using the new API should be in the same ball park as that of Unsafe and ByteBuffer