1 /*
2 * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 *
25 */
26
27 package jdk.incubator.foreign;
28
29 import jdk.internal.foreign.MemoryAddressImpl;
30
31 /**
32 * A memory address encodes an offset within a given {@link MemorySegment}. Memory addresses are typically obtained
33 * using the {@link MemorySegment#baseAddress()} method; such addresses can then be adjusted as required,
34 * using {@link MemoryAddress#offset(long)}.
35 * <p>
36 * A memory address is typically used as the first argument in a memory access var handle call, to perform some operation
37 * on the underlying memory backing a given memory segment. Since a memory address is always associated with a memory segment,
38 * such access operations are always subject to spatial and temporal checks as enforced by the address' owning memory region.
39 * <p>
40 * All implementations of this interface must be <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>;
41 * use of identity-sensitive operations (including reference equality ({@code ==}), identity hash code, or synchronization) on
42 * instances of {@code MemoryAddress} may have unpredictable results and should be avoided. The {@code equals} method should
43 * be used for comparisons.
44 * <p>
45 * Non-platform classes should not implement {@linkplain MemoryAddress} directly.
46 *
47 * @apiNote In the future, if the Java language permits, {@link MemoryAddress}
48 * may become a {@code sealed} interface, which would prohibit subclassing except by
49 * explicitly permitted types.
50 *
51 * @implSpec
52 * Implementations of this interface are immutable and thread-safe.
53 */
54 public interface MemoryAddress {
55 /**
56 * Creates a new memory address with given offset (in bytes) from current one.
57 * @param l specified offset (in bytes), relative to this address, which should be used to create the new address.
58 * @return a new memory address with given offset from current one.
59 */
60 MemoryAddress offset(long l);
61
62 /**
63 * The offset of this MemoryAddress into the underlying segment.
64 *
65 * @return the offset
66 */
67 long offset();
68
69 /**
70 * The memory segment this address belongs to.
71 * @return The memory segment this address belongs to.
72 */
73 MemorySegment segment();
74
75 /**
76 * Compares the specified object with this address for equality. Returns {@code true} if and only if the specified
77 * object is also a address, and it is equal to this address.
78 *
79 * @param that the object to be compared for equality with this address.
80 * @return {@code true} if the specified object is equal to this address.
81 */
82 @Override
83 boolean equals(Object that);
84
85 /**
86 * Returns the hash code value for this address.
87 * @return the hash code value for this address.
88 */
89 @Override
90 int hashCode();
91
92 /**
93 * Perform bulk copy from source address to target address. More specifically, the bytes at addresses {@code src}
94 * through {@code src.offset(bytes - 1)} are copied into addresses {@code dst} through {@code dst.offset(bytes - 1)}.
95 * @param src the source address.
96 * @param dst the target address.
97 * @param bytes the number of bytes to be copied.
98 * @throws IndexOutOfBoundsException if {@code bytes < 0}, or if it is greater than the size of the segments
99 * associated with either {@code src} or {@code dst}.
100 * @throws IllegalStateException if either the source address or the target address belong to memory segments
101 * which have been already closed, or if access occurs from a thread other than the thread owning either segment.
102 * @throws IllegalArgumentException if the range of source addresses overlaps with the range of destination addresses.
103 * @throws UnsupportedOperationException if {@code dst} is associated with a read-only segment (see {@link MemorySegment#isReadOnly()}).
104 */
105 static void copy(MemoryAddress src, MemoryAddress dst, long bytes) {
106 MemoryAddressImpl.copy((MemoryAddressImpl)src, (MemoryAddressImpl)dst, bytes);
107 }
108
109 }