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 package java.foreign.memory;
  27 
  28 import jdk.internal.foreign.MemoryAddressImpl;
  29 import jdk.internal.foreign.MemoryBoundInfo;
  30 import jdk.internal.foreign.MemoryScopeImpl;
  31 
  32 import java.nio.ByteBuffer;
  33 
  34 /**
  35  * This interface encapsulate a memory address with certain spatial and temporal bounds.
  36  */
  37 public interface MemoryAddress {
  38     /**
  39      * Creates a new memory address with given offset from current one.
  40      * @param l specified offset at which new address should be created.
  41      * @return a new memory address with given offset from current one.
  42      */
  43     MemoryAddress offset(long l);
  44 
  45     /**
  46      * Creates a new memory address whose base address is the same as this address
  47      * and whose new limit is at the offset specified by the given argument.
  48      * @param newSize The new address limit.
  49      * @return a new address with updated base/limit addresses.
  50      */
  51     MemoryAddress narrow(long newSize);
  52 
  53     /**
  54      * The scope associated with this address.
  55      * @return The scope associated with this address.
  56      */
  57     MemoryScope scope();
  58 
  59     /**
  60      * Wraps the this address in a direct {@link ByteBuffer}
  61      *
  62      * @param bytes the size of the buffer in bytes
  63      * @return the created {@link ByteBuffer}
  64      * @throws IllegalAccessException if bytes is larger than the region covered by this address
  65      */
  66     ByteBuffer asDirectByteBuffer(int bytes) throws IllegalAccessException;
  67 
  68     @Override
  69     boolean equals(Object that);
  70 
  71     @Override
  72     int hashCode();
  73 
  74     @Override
  75     String toString();
  76 
  77     /**
  78      * Perform bulk copy from source address to target address.
  79      * @param src the source address.
  80      * @param dst the target address.
  81      * @param bytes the number of bytes to be copied.
  82      */
  83     static void copy(MemoryAddress src, MemoryAddress dst, long bytes) {
  84         MemoryAddressImpl.copy((MemoryAddressImpl)src, (MemoryAddressImpl)dst, bytes);
  85     }
  86 
  87     /**
  88      * Returns a memory address that models the memory region associated with the given byte
  89      * buffer. The region starts relative to the buffer's position (inclusive)
  90      * and ends relative to the buffer's limit (exclusive).
  91      * <p>
  92      * The address keeps a reference to the buffer to ensure the buffer is kept
  93      * live for the life-time of the address.
  94      * <p>
  95      *
  96      * @param bb the byte buffer
  97      * @return the created address
  98      */
  99     static MemoryAddress ofByteBuffer(ByteBuffer bb) {
 100         SecurityManager security = System.getSecurityManager();
 101         if (security != null) {
 102             security.checkPermission(new RuntimePermission("java.foreign.Pointer.fromByteBuffer"));
 103         }
 104         return new MemoryAddressImpl(MemoryScopeImpl.UNCHECKED,
 105                 MemoryBoundInfo.ofByteBuffer(bb));
 106     }
 107 
 108     /**
 109      * Return the null address.
 110      * @return the null address.
 111      */
 112     static MemoryAddress ofNull() {
 113         return MemoryAddressImpl.NULL_ADDR;
 114     }
 115 }