stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8236769: Clarify javadoc of memory access API

Browse Source 
Reviewed-by: chegar
This commit is contained in:
Paul Sandoz 2020-01-08 23:12:45 +00:00 committed by Maurizio Cimadamore
parent 0239771501
commit e5b0568e1c
3 changed files with 79 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java
View File

@ -74,7 +74,13 @@ public interface MemoryAddress {
/**
* Compares the specified object with this address for equality. Returns {@code true} if and only if the specified
* object is also a address, and it is equal to this address.
* object is also an address, and it refers to the same memory location as this address.
*
* @apiNote two addresses might be considered equal despite their associated segments differ. This
* can happen, for instance, if the segment associated with one address is a <em>slice</em>
* (see {@link MemorySegment#asSlice(long, long)}) of the segment associated with the other address. Moreover,
* two addresses might be considered equals despite differences in the temporal bounds associated with their
* corresponding segments (this is possible, for example, as a result of calls to {@link MemorySegment#acquire()}).
*
* @param that the object to be compared for equality with this address.
* @return {@code true} if the specified object is equal to this address.

21
src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java
View File

@ -55,14 +55,14 @@ import java.util.OptionalLong;
* <p>
* Non-platform classes should not implement {@linkplain MemoryLayout} directly.
*
* <h2>Size, alignment and byte order</h2>
* <h2><a id = "layout-align">Size, alignment and byte order</a></h2>
*
* All layouts have a size; layout size for value and padding layouts is always explicitly denoted; this means that a layout description
* always has the same size in bits, regardless of the platform in which it is used. For derived layouts, the size is computed
* as follows:
* <ul>
* <li>for a <em>finite</em> sequence layout <em>S</em> whose element layout is <em>E</em> and size is L,
* the size of <em>S</em> is that of <em>E, multiplied by L</em></li>
* the size of <em>S</em> is that of <em>E</em>, multiplied by <em>L</em></li>
* <li>the size of an <em>unbounded</em> sequence layout is <em>unknown</em></li>
* <li>for a group layout <em>G</em> with member layouts <em>M1</em>, <em>M2</em>, ... <em>Mn</em> whose sizes are
* <em>S1</em>, <em>S2</em>, ... <em>Sn</em>, respectively, the size of <em>G</em> is either <em>S1 + S2 + ... + Sn</em> or
@ -180,6 +180,9 @@ public interface MemoryLayout extends Constable {
* <li>{@code A=512} is the most strict alignment required by the x86/SV ABI (for AVX-512 data).</li>
* </ul>
*
* If no explicit alignment constraint was set on this layout (see {@link #withBitAlignment(long)}),
* then this method returns the <a href="#layout-align">natural alignment</a> constraint (in bits) associated with this layout.
*
* @return the layout alignment constraint, in bits.
*/
long bitAlignment();
@ -195,6 +198,9 @@ public interface MemoryLayout extends Constable {
* <li>{@code A=64} is the most strict alignment required by the x86/SV ABI (for AVX-512 data).</li>
* </ul>
*
* If no explicit alignment constraint was set on this layout (see {@link #withBitAlignment(long)}),
* then this method returns the <a href="#layout-align">natural alignment</a> constraint (in bytes) associated with this layout.
*
* @return the layout alignment constraint, in bytes.
* @throws UnsupportedOperationException if {@code bitAlignment()} is not a multiple of 8.
*/
@ -352,7 +358,16 @@ E * (S + I * F)
/**
* Compares the specified object with this layout for equality. Returns {@code true} if and only if the specified
* object is also a layout, and it is equal to this layout.
* object is also a layout, and it is equal to this layout. Two layouts are considered equal if they are of
* the same kind, have the same size, name and alignment constraints. Furthermore, depending on the layout kind, additional
* conditions must be satisfied:
* <ul>
* <li>two value layouts are considered equal if they have the same endianness (see {@link ValueLayout#order()})</li>
* <li>two sequence layouts are considered equal if they have the same element count (see {@link SequenceLayout#elementCount()}), and
* if their element layouts (see {@link SequenceLayout#elementLayout()}) are also equal</li>
* <li>two group layouts are considered equal if they are of the same kind (see {@link GroupLayout#isStruct()},
* {@link GroupLayout#isUnion()}) and if their member layouts (see {@link GroupLayout#memberLayouts()}) are also equal</li>
* </ul>
*
* @param that the object to be compared for equality with this layout.
* @return {@code true} if the specified object is equal to this layout.

54
test/jdk/java/foreign/TestTypeAccess.java Normal file
View File

@ -0,0 +1,54 @@
/*
* Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*
*/
/*
* @test
* @run testng TestTypeAccess
*/
import jdk.incubator.foreign.MemorySegment;
import jdk.incubator.foreign.MemoryLayouts;
import org.testng.annotations.*;
import java.lang.invoke.VarHandle;
import java.lang.invoke.WrongMethodTypeException;
public class TestTypeAccess {
static final VarHandle INT_HANDLE = MemoryLayouts.JAVA_INT.varHandle(int.class);
@Test(expectedExceptions=ClassCastException.class)
public void testMemoryAddressCoordinateAsString() {
try (MemorySegment s = MemorySegment.allocateNative(8)) {
int v = (int)INT_HANDLE.get("string");
}
}
@Test(expectedExceptions=WrongMethodTypeException.class)
public void testMemoryCoordinatePrimitive() {
try (MemorySegment s = MemorySegment.allocateNative(8)) {
int v = (int)INT_HANDLE.get(1);
}
}
}