1 /*
  2  * Copyright (c) 2023, 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.lang.foreign;
 27 
 28 import jdk.internal.foreign.layout.ValueLayouts;
 29 import jdk.internal.javac.PreviewFeature;
 30 import jdk.internal.reflect.CallerSensitive;
 31 
 32 import java.lang.foreign.Linker.Option;
 33 import java.lang.invoke.MethodHandle;
 34 import java.nio.ByteOrder;
 35 import java.util.Optional;
 36 
 37 /**
 38  * A value layout used to model the address of some region of memory. The carrier associated with an address layout is
 39  * {@code MemorySegment.class}. The size and alignment of an address layout are platform-dependent
 40  * (e.g. on a 64-bit platform, the size and alignment of an address layout are set to 8 bytes).
 41  * <p>
 42  * An address layout may optionally feature a {@linkplain #targetLayout() target layout}. An address layout with
 43  * target layout {@code T} can be used to model the address of a region of memory whose layout is {@code T}.
 44  * For instance, an address layout with target layout {@link ValueLayout#JAVA_INT} can be used to model the address
 45  * of a region of memory that is 4 bytes long. Specifying a target layout can be useful in the following situations:
 46  * <ul>
 47  *     <li>When accessing a memory segment that has been obtained by reading an address from another
 48  *     memory segment, e.g. using {@link MemorySegment#getAtIndex(AddressLayout, long)};</li>
 49  *     <li>When creating a downcall method handle, using {@link Linker#downcallHandle(FunctionDescriptor, Option...)};
 50  *     <li>When creating an upcall stub, using {@link Linker#upcallStub(MethodHandle, FunctionDescriptor, Arena, Option...)}.
 51  * </ul>
 52  *
 53  * @see #ADDRESS
 54  * @see #ADDRESS_UNALIGNED
 55  * @since 19
 56  */
 57 @PreviewFeature(feature = PreviewFeature.Feature.FOREIGN)
 58 public sealed interface AddressLayout extends ValueLayout permits ValueLayouts.OfAddressImpl {
 59 
 60     /**
 61      * {@inheritDoc}
 62      */
 63     @Override
 64     AddressLayout withName(String name);
 65 
 66     /**
 67      * {@inheritDoc}
 68      */
 69     @Override
 70     AddressLayout withoutName();
 71 
 72     /**
 73      * {@inheritDoc}
 74      */
 75     @Override
 76     AddressLayout withByteAlignment(long byteAlignment);
 77 
 78     /**
 79      * {@inheritDoc}
 80      */
 81     @Override
 82     AddressLayout withOrder(ByteOrder order);
 83 
 84     /**
 85      * Returns an address layout with the same carrier, alignment constraint, name and order as this address layout,
 86      * but associated with the specified target layout. The returned address layout allows raw addresses to be accessed
 87      * as {@linkplain MemorySegment memory segments} whose size is set to the size of the specified layout. Moreover,
 88      * if the accessed raw address is not compatible with the alignment constraint in the provided layout,
 89      * {@linkplain IllegalArgumentException} will be thrown.
 90      * @apiNote
 91      * This method can also be used to create an address layout which, when used, creates native memory
 92      * segments with maximal size (e.g. {@linkplain Long#MAX_VALUE}). This can be done by using a target sequence
 93      * layout with unspecified size, as follows:
 94      * {@snippet lang = java:
 95      * AddressLayout addressLayout   = ...
 96      * AddressLayout unboundedLayout = addressLayout.withTargetLayout(
 97      *         MemoryLayout.sequenceLayout(ValueLayout.JAVA_BYTE));
 98      *}
 99      * <p>
100      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
101      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
102      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
103      * restricted methods, and use safe and supported functionalities, where possible.
104      *
105      * @param layout the target layout.
106      * @return an address layout with same characteristics as this layout, but with the provided target layout.
107      * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
108      * @see #targetLayout()
109      */
110     @CallerSensitive
111     AddressLayout withTargetLayout(MemoryLayout layout);
112 
113     /**
114      * Returns an address layout with the same carrier, alignment constraint, name and order as this address layout,
115      * but with no target layout.
116      *
117      * @apiNote This can be useful to compare two address layouts that have different target layouts, but are otherwise equal.
118      *
119      * @return an address layout with same characteristics as this layout, but with no target layout.
120      * @see #targetLayout()
121      */
122     AddressLayout withoutTargetLayout();
123 
124     /**
125      * {@return the target layout associated with this address layout (if any)}.
126      */
127     Optional<MemoryLayout> targetLayout();
128 
129 }