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 import jdk.internal.reflect.CallerSensitive;
 31 
 32 import java.nio.ByteOrder;
 33 
 34 /**
 35  * A memory address models a reference into a memory location. Memory addresses are typically obtained in three ways:
 36  * <ul>
 37  *     <li>By calling {@link Addressable#address()} on an instance of type {@link Addressable} (e.g. a memory segment);</li>
 38  *     <li>By invoking a {@linkplain CLinker#downcallHandle(FunctionDescriptor) downcall method handle} which returns a pointer;</li>
 39  *     <li>By reading an address from memory, e.g. via {@link MemorySegment#get(ValueLayout.OfAddress, long)}.</li>
 40  * </ul>
 41  * A memory address is backed by a raw machine pointer, expressed as a {@linkplain #toRawLongValue() long value}.
 42  *
 43  * <h2>Dereference</h2>
 44  *
 45  * A memory address can be read or written using various methods provided in this class (e.g. {@link #get(ValueLayout.OfInt, long)}).
 46  * Each dereference method takes a {@linkplain jdk.incubator.foreign.ValueLayout value layout}, which specifies the size,
 47  * alignment constraints, byte order as well as the Java type associated with the dereference operation, and an offset.
 48  * For instance, to read an int from a segment, using {@link ByteOrder#nativeOrder() default endianness}, the following code can be used:
 49  * <blockquote><pre>{@code
 50 MemoryAddress address = ...
 51 int value = address.get(ValueLayout.JAVA_INT, 0);
 52  * }</pre></blockquote>
 53  *
 54  * If the value to be read is stored in memory using {@link ByteOrder#BIG_ENDIAN big-endian} encoding, the dereference operation
 55  * can be expressed as follows:
 56  * <blockquote><pre>{@code
 57 MemoryAddress address = ...
 58 int value = address.get(ValueLayout.JAVA_INT.withOrder(BIG_ENDIAN), 0);
 59  * }</pre></blockquote>
 60  *
 61  * All the dereference methods in this class are <a href="package-summary.html#restricted"><em>restricted</em></a>: since
 62  * a memory address does not feature temporal nor spatial bounds, the runtime has no way to check the correctness
 63  * of the memory dereference operation.
 64  * <p>
 65  * All implementations of this interface must be <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>;
 66  * programmers should treat instances that are {@linkplain #equals(Object) equal} as interchangeable and should not
 67  * use instances for synchronization, or unpredictable behavior may occur. For example, in a future release,
 68  * synchronization may fail. The {@code equals} method should be used for comparisons.
 69  * <p>
 70  * Non-platform classes should not implement {@linkplain MemoryAddress} directly.
 71  *
 72  * <p> Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null}
 73  * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown. </p>
 74  *
 75  * @implSpec
 76  * Implementations of this interface are immutable, thread-safe and <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.
 77  */
 78 public sealed interface MemoryAddress extends Addressable permits MemoryAddressImpl {
 79 
 80     /**
 81      * Returns the raw long value associated with this memory address.
 82      * @return The raw long value associated with this memory address.
 83      */
 84     long toRawLongValue();
 85 
 86     /**
 87      * Creates a new memory address with given offset (in bytes), which might be negative, from current one.
 88      * @param offset specified offset (in bytes), relative to this address, which should be used to create the new address.
 89      * @return a new memory address with given offset from current one.
 90      */
 91     MemoryAddress addOffset(long offset);
 92 
 93     /**
 94      * Reads a UTF-8 encoded, null-terminated string from this address and offset.
 95      * <p>
 96      * This method always replaces malformed-input and unmappable-character
 97      * sequences with this charset's default replacement string.  The {@link
 98      * java.nio.charset.CharsetDecoder} class should be used when more control
 99      * over the decoding process is required.
100      * <p>
101      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
102      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
103      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
104      * restricted methods, and use safe and supported functionalities, where possible.
105      *
106      * @param offset offset in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + offset}.
107      * @return a Java UTF-8 string containing all the bytes read from the given starting address ({@code toRowLongValue() + offset})
108      * up to (but not including) the first {@code '\0'} terminator character (assuming one is found).
109      * @throws IllegalArgumentException if the size of the native string is greater than the largest string supported by the platform.
110      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
111      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
112      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
113      */
114     @CallerSensitive
115     String getUtf8String(long offset);
116 
117     /**
118      * Writes a UTF-8 encoded, null-terminated string to this address at given offset.
119      * <p>
120      * This method always replaces malformed-input and unmappable-character
121      * sequences with this charset's default replacement string.  The {@link
122      * java.nio.charset.CharsetDecoder} class should be used when more control
123      * over the decoding process is required.
124      * @param offset offset in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + offset}.
125      * @param str the Java string to be written at this address.
126      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
127      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
128      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
129      */
130     @CallerSensitive
131     void setUtf8String(long offset, String str);
132 
133     /**
134      * Compares the specified object with this address for equality. Returns {@code true} if and only if the specified
135      * object is also an address, and it refers to the same memory location as this address.
136      *
137      * @param that the object to be compared for equality with this address.
138      * @return {@code true} if the specified object is equal to this address.
139      */
140     @Override
141     boolean equals(Object that);
142 
143     /**
144      * Returns the hash code value for this address.
145      * @return the hash code value for this address.
146      */
147     @Override
148     int hashCode();
149 
150     /**
151      * The native memory address instance modelling the {@code NULL} address.
152      */
153     MemoryAddress NULL = new MemoryAddressImpl(0L);
154 
155     /**
156      * Obtain a native memory address instance from given long address.
157      * @param value the long address.
158      * @return the new memory address instance.
159      */
160     static MemoryAddress ofLong(long value) {
161         return value == 0 ?
162                 NULL :
163                 new MemoryAddressImpl(value);
164     }
165 
166     /**
167      * Reads a byte from this address and offset with given layout.
168      * <p>
169      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
170      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
171      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
172      * restricted methods, and use safe and supported functionalities, where possible.
173      *
174      * @param layout the layout of the memory region to be read.
175      * @param offset offset in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + offset}.
176      * @return a byte value read from this address.
177      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
178      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
179      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
180      */
181     @CallerSensitive
182     byte get(ValueLayout.OfByte layout, long offset);
183 
184     /**
185      * Writes a byte to this address instance and offset with given layout.
186      * <p>
187      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
188      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
189      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
190      * restricted methods, and use safe and supported functionalities, where possible.
191      *
192      * @param layout the layout of the memory region to be written.
193      * @param offset offset in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + offset}.
194      * @param value the byte value to be written.
195      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
196      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
197      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
198      */
199     @CallerSensitive
200     void set(ValueLayout.OfByte layout, long offset, byte value);
201 
202     /**
203      * Reads a boolean from this address and offset with given layout.
204      * <p>
205      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
206      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
207      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
208      * restricted methods, and use safe and supported functionalities, where possible.
209      *
210      * @param layout the layout of the memory region to be read.
211      * @param offset offset in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + offset}.
212      * @return a boolean value read from this address.
213      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
214      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
215      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
216      */
217     @CallerSensitive
218     boolean get(ValueLayout.OfBoolean layout, long offset);
219 
220     /**
221      * Writes a boolean to this address instance and offset with given layout.
222      * <p>
223      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
224      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
225      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
226      * restricted methods, and use safe and supported functionalities, where possible.
227      *
228      * @param layout the layout of the memory region to be written.
229      * @param offset offset in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + offset}.
230      * @param value the boolean value to be written.
231      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
232      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
233      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
234      */
235     @CallerSensitive
236     void set(ValueLayout.OfBoolean layout, long offset, boolean value);
237 
238     /**
239      * Reads a char from this address and offset with given layout.
240      * <p>
241      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
242      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
243      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
244      * restricted methods, and use safe and supported functionalities, where possible.
245      *
246      * @param layout the layout of the memory region to be read.
247      * @param offset offset in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + offset}.
248      * @return a char value read from this address.
249      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
250      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
251      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
252      */
253     @CallerSensitive
254     char get(ValueLayout.OfChar layout, long offset);
255 
256     /**
257      * Writes a char to this address instance and offset with given layout.
258      * <p>
259      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
260      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
261      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
262      * restricted methods, and use safe and supported functionalities, where possible.
263      *
264      * @param layout the layout of the memory region to be written.
265      * @param offset offset in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + offset}.
266      * @param value the char value to be written.
267      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
268      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
269      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
270      */
271     @CallerSensitive
272     void set(ValueLayout.OfChar layout, long offset, char value);
273 
274     /**
275      * Reads a short from this address and offset with given layout.
276      * <p>
277      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
278      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
279      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
280      * restricted methods, and use safe and supported functionalities, where possible.
281      *
282      * @param layout the layout of the memory region to be read.
283      * @param offset offset in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + offset}.
284      * @return a short value read from this address.
285      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
286      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
287      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
288      */
289     @CallerSensitive
290     short get(ValueLayout.OfShort layout, long offset);
291 
292     /**
293      * Writes a short to this address instance and offset with given layout.
294      * <p>
295      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
296      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
297      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
298      * restricted methods, and use safe and supported functionalities, where possible.
299      *
300      * @param layout the layout of the memory region to be written.
301      * @param offset offset in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + offset}.
302      * @param value the short value to be written.
303      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
304      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
305      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
306      */
307     @CallerSensitive
308     void set(ValueLayout.OfShort layout, long offset, short value);
309 
310     /**
311      * Reads an int from this address and offset with given layout.
312      * <p>
313      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
314      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
315      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
316      * restricted methods, and use safe and supported functionalities, where possible.
317      *
318      * @param layout the layout of the memory region to be read.
319      * @param offset offset in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + offset}.
320      * @return an int value read from this address.
321      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
322      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
323      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
324      */
325     @CallerSensitive
326     int get(ValueLayout.OfInt layout, long offset);
327 
328     /**
329      * Writes an int to this address instance and offset with given layout.
330      * <p>
331      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
332      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
333      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
334      * restricted methods, and use safe and supported functionalities, where possible.
335      *
336      * @param layout the layout of the memory region to be written.
337      * @param offset offset in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + offset}.
338      * @param value the int value to be written.
339      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
340      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
341      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
342      */
343     @CallerSensitive
344     void set(ValueLayout.OfInt layout, long offset, int value);
345 
346     /**
347      * Reads a float from this address and offset with given layout.
348      * <p>
349      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
350      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
351      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
352      * restricted methods, and use safe and supported functionalities, where possible.
353      *
354      * @param layout the layout of the memory region to be read.
355      * @param offset offset in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + offset}.
356      * @return a float value read from this address.
357      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
358      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
359      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
360      */
361     @CallerSensitive
362     float get(ValueLayout.OfFloat layout, long offset);
363 
364     /**
365      * Writes a float to this address instance and offset with given layout.
366      * <p>
367      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
368      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
369      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
370      * restricted methods, and use safe and supported functionalities, where possible.
371      *
372      * @param layout the layout of the memory region to be written.
373      * @param offset offset in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + offset}.
374      * @param value the float value to be written.
375      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
376      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
377      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
378      */
379     @CallerSensitive
380     void set(ValueLayout.OfFloat layout, long offset, float value);
381 
382     /**
383      * Reads a long from this address and offset with given layout.
384      * <p>
385      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
386      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
387      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
388      * restricted methods, and use safe and supported functionalities, where possible.
389      *
390      * @param layout the layout of the memory region to be read.
391      * @param offset offset in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + offset}.
392      * @return a long value read from this address.
393      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
394      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
395      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
396      */
397     @CallerSensitive
398     long get(ValueLayout.OfLong layout, long offset);
399 
400     /**
401      * Writes a long to this address instance and offset with given layout.
402      * <p>
403      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
404      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
405      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
406      * restricted methods, and use safe and supported functionalities, where possible.
407      *
408      * @param layout the layout of the memory region to be written.
409      * @param offset offset in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + offset}.
410      * @param value the long value to be written.
411      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
412      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
413      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
414      */
415     @CallerSensitive
416     void set(ValueLayout.OfLong layout, long offset, long value);
417 
418     /**
419      * Reads a double from this address and offset with given layout.
420      * <p>
421      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
422      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
423      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
424      * restricted methods, and use safe and supported functionalities, where possible.
425      *
426      * @param layout the layout of the memory region to be read.
427      * @param offset offset in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + offset}.
428      * @return a double value read from this address.
429      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
430      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
431      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
432      */
433     @CallerSensitive
434     double get(ValueLayout.OfDouble layout, long offset);
435 
436     /**
437      * Writes a double to this address instance and offset with given layout.
438      * <p>
439      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
440      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
441      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
442      * restricted methods, and use safe and supported functionalities, where possible.
443      *
444      * @param layout the layout of the memory region to be written.
445      * @param offset offset in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + offset}.
446      * @param value the double value to be written.
447      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
448      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
449      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
450      */
451     @CallerSensitive
452     void set(ValueLayout.OfDouble layout, long offset, double value);
453 
454     /**
455      * Reads an address from this address and offset with given layout.
456      * <p>
457      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
458      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
459      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
460      * restricted methods, and use safe and supported functionalities, where possible.
461      *
462      * @param layout the layout of the memory region to be read.
463      * @param offset offset in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + offset}.
464      * @return an address value read from this address.
465      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
466      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
467      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
468      */
469     @CallerSensitive
470     MemoryAddress get(ValueLayout.OfAddress layout, long offset);
471 
472     /**
473      * Writes an address to this address instance and offset with given layout.
474      * <p>
475      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
476      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
477      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
478      * restricted methods, and use safe and supported functionalities, where possible.
479      *
480      * @param layout the layout of the memory region to be written.
481      * @param offset offset in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + offset}.
482      * @param value the address value to be written.
483      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
484      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
485      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
486      */
487     @CallerSensitive
488     void set(ValueLayout.OfAddress layout, long offset, Addressable value);
489 
490     /**
491      * Reads a char from this address and index, scaled by given layout size.
492      * <p>
493      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
494      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
495      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
496      * restricted methods, and use safe and supported functionalities, where possible.
497      *
498      * @param layout the layout of the memory region to be read.
499      * @param index index in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
500      * @return a char value read from this address.
501      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
502      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
503      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
504      */
505     @CallerSensitive
506     char getAtIndex(ValueLayout.OfChar layout, long index);
507 
508     /**
509      * Writes a char to this address instance and index, scaled by given layout size.
510      * <p>
511      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
512      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
513      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
514      * restricted methods, and use safe and supported functionalities, where possible.
515      *
516      * @param layout the layout of the memory region to be written.
517      * @param index index in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
518      * @param value the char value to be written.
519      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
520      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
521      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
522      */
523     @CallerSensitive
524     void setAtIndex(ValueLayout.OfChar layout, long index, char value);
525 
526     /**
527      * Reads a short from this address and index, scaled by given layout size.
528      * <p>
529      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
530      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
531      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
532      * restricted methods, and use safe and supported functionalities, where possible.
533      *
534      * @param layout the layout of the memory region to be read.
535      * @param index index in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
536      * @return a short value read from this address.
537      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
538      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
539      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
540      */
541     @CallerSensitive
542     short getAtIndex(ValueLayout.OfShort layout, long index);
543 
544     /**
545      * Writes a short to this address instance and index, scaled by given layout size.
546      * <p>
547      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
548      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
549      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
550      * restricted methods, and use safe and supported functionalities, where possible.
551      *
552      * @param layout the layout of the memory region to be written.
553      * @param index index in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
554      * @param value the short value to be written.
555      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
556      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
557      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
558      */
559     @CallerSensitive
560     void setAtIndex(ValueLayout.OfShort layout, long index, short value);
561 
562     /**
563      * Reads an int from this address and index, scaled by given layout size.
564      * <p>
565      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
566      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
567      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
568      * restricted methods, and use safe and supported functionalities, where possible.
569      *
570      * @param layout the layout of the memory region to be read.
571      * @param index index in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
572      * @return an int value read from this address.
573      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
574      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
575      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
576      */
577     @CallerSensitive
578     int getAtIndex(ValueLayout.OfInt layout, long index);
579 
580     /**
581      * Writes an int to this address instance and index, scaled by given layout size.
582      * <p>
583      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
584      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
585      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
586      * restricted methods, and use safe and supported functionalities, where possible.
587      *
588      * @param layout the layout of the memory region to be written.
589      * @param index index in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
590      * @param value the int value to be written.
591      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
592      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
593      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
594      */
595     @CallerSensitive
596     void setAtIndex(ValueLayout.OfInt layout, long index, int value);
597 
598     /**
599      * Reads a float from this address and index, scaled by given layout size.
600      * <p>
601      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
602      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
603      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
604      * restricted methods, and use safe and supported functionalities, where possible.
605      *
606      * @param layout the layout of the memory region to be read.
607      * @param index index in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
608      * @return a float value read from this address.
609      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
610      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
611      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
612      */
613     @CallerSensitive
614     float getAtIndex(ValueLayout.OfFloat layout, long index);
615 
616     /**
617      * Writes a float to this address instance and index, scaled by given layout size.
618      * <p>
619      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
620      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
621      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
622      * restricted methods, and use safe and supported functionalities, where possible.
623      *
624      * @param layout the layout of the memory region to be written.
625      * @param index index in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
626      * @param value the float value to be written.
627      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
628      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
629      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
630      */
631     @CallerSensitive
632     void setAtIndex(ValueLayout.OfFloat layout, long index, float value);
633 
634     /**
635      * Reads a long from this address and index, scaled by given layout size.
636      * <p>
637      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
638      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
639      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
640      * restricted methods, and use safe and supported functionalities, where possible.
641      *
642      * @param layout the layout of the memory region to be read.
643      * @param index index in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
644      * @return a long value read from this address.
645      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
646      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
647      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
648      */
649     @CallerSensitive
650     long getAtIndex(ValueLayout.OfLong layout, long index);
651 
652     /**
653      * Writes a long to this address instance and index, scaled by given layout size.
654      * <p>
655      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
656      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
657      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
658      * restricted methods, and use safe and supported functionalities, where possible.
659      *
660      * @param layout the layout of the memory region to be written.
661      * @param index index in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
662      * @param value the long value to be written.
663      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
664      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
665      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
666      */
667     @CallerSensitive
668     void setAtIndex(ValueLayout.OfLong layout, long index, long value);
669 
670     /**
671      * Reads a double from this address and index, scaled by given layout size.
672      * <p>
673      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
674      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
675      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
676      * restricted methods, and use safe and supported functionalities, where possible.
677      *
678      * @param layout the layout of the memory region to be read.
679      * @param index index in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
680      * @return a double value read from this address.
681      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
682      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
683      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
684      */
685     @CallerSensitive
686     double getAtIndex(ValueLayout.OfDouble layout, long index);
687 
688     /**
689      * Writes a double to this address instance and index, scaled by given layout size.
690      * <p>
691      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
692      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
693      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
694      * restricted methods, and use safe and supported functionalities, where possible.
695      *
696      * @param layout the layout of the memory region to be written.
697      * @param index index in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
698      * @param value the double value to be written.
699      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
700      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
701      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
702      */
703     @CallerSensitive
704     void setAtIndex(ValueLayout.OfDouble layout, long index, double value);
705 
706     /**
707      * Reads an address from this address and index, scaled by given layout size.
708      * <p>
709      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
710      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
711      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
712      * restricted methods, and use safe and supported functionalities, where possible.
713      *
714      * @param layout the layout of the memory region to be read.
715      * @param index index in bytes (relative to this address). The final address of this read operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
716      * @return an address value read from this address.
717      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
718      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
719      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
720      */
721     @CallerSensitive
722     MemoryAddress getAtIndex(ValueLayout.OfAddress layout, long index);
723 
724     /**
725      * Writes an address to this address instance and index, scaled by given layout size.
726      * <p>
727      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
728      * Restricted methods are unsafe, and, if used incorrectly, their use might crash
729      * the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
730      * restricted methods, and use safe and supported functionalities, where possible.
731      *
732      * @param layout the layout of the memory region to be written.
733      * @param index index in bytes (relative to this address). The final address of this write operation can be expressed as {@code toRowLongValue() + (index * layout.byteSize())}.
734      * @param value the address value to be written.
735      * @throws IllegalCallerException if access to this method occurs from a module {@code M} and the command line option
736      * {@code --enable-native-access} is either absent, or does not mention the module name {@code M}, or
737      * {@code ALL-UNNAMED} in case {@code M} is an unnamed module.
738      */
739     @CallerSensitive
740     void setAtIndex(ValueLayout.OfAddress layout, long index, Addressable value);
741 }