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 memory address 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 }