Skip to content
Permalink
Browse files

8236769: Clarify javadoc of memory access API

Reviewed-by: chegar
  • Loading branch information
PaulSandoz authored and mcimadamore committed Jan 8, 2020
1 parent 0239771 commit e5b0568e1c7b56a5ba7f3edecf826a463a70144a
@@ -74,7 +74,13 @@

/**
* 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.
@@ -55,14 +55,14 @@
* <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 @@ default long byteSize() {
* <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 @@ default long byteSize() {
* <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 @@ static PathElement sequenceElement() {

/**
* 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.
@@ -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);
}
}
}

0 comments on commit e5b0568

Please sign in to comment.