stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8319607: FFM: Review the language in the FFM documentation

Browse Source 
Reviewed-by: mcimadamore
This commit is contained in:
Per Minborg 2023-11-07 14:34:33 +00:00
parent bf9a93de1f
commit ef8c8408a6
12 changed files with 128 additions and 128 deletions

4
src/java.base/share/classes/java/lang/foreign/AddressLayout.java

@ -100,7 +100,7 @@ public sealed interface AddressLayout extends ValueLayout permits ValueLayouts.O
*}
*
* @param layout the target layout.
* @return an address layout with same characteristics as this layout, but with the provided target layout.
* @return an address layout with the same characteristics as this layout, but with the provided target layout.
* @throws IllegalCallerException If the caller is in a module that does not have native access enabled
* @see #targetLayout()
*/
@ -114,7 +114,7 @@ public sealed interface AddressLayout extends ValueLayout permits ValueLayouts.O
*
* @apiNote This can be useful to compare two address layouts that have different target layouts, but are otherwise equal.
*
* @return an address layout with same characteristics as this layout, but with no target layout.
* @return an address layout with the same characteristics as this layout, but with no target layout.
* @see #targetLayout()
*/
AddressLayout withoutTargetLayout();

2
src/java.base/share/classes/java/lang/foreign/Arena.java

@ -246,7 +246,7 @@ public interface Arena extends SegmentAllocator, AutoCloseable {
* The returned segment is associated with this {@linkplain #scope() arena scope}.
* The segment's {@link MemorySegment#address() address} is the starting address of the
* allocated off-heap region of memory backing the segment, and the address is
* aligned according the provided alignment constraint.
* aligned according to the provided alignment constraint.
*
* @implSpec
* Implementations of this method must return a native segment featuring the requested size,

6
src/java.base/share/classes/java/lang/foreign/FunctionDescriptor.java

@ -70,7 +70,7 @@ public sealed interface FunctionDescriptor permits FunctionDescriptorImpl {
* Returns a function descriptor with the given argument layouts inserted at the given index, into the argument
* layout array of this function descriptor.
* @param index the index at which to insert the arguments
* @param addedLayouts the argument layouts to insert at given index.
* @param addedLayouts the argument layouts to insert at the given index.
* @return a new function descriptor, with the provided additional argument layouts.
* @throws IllegalArgumentException if one of the layouts in {@code addedLayouts} is a padding layout
* @throws IllegalArgumentException if {@code index < 0 || index > argumentLayouts().size()}
@ -100,7 +100,7 @@ public sealed interface FunctionDescriptor permits FunctionDescriptorImpl {
* </ul>
*
* @apiNote A function descriptor cannot, by construction, contain any padding layouts. As such, it is not
* necessary to specify how padding layout should be mapped to carrier types.
* necessary to specify how padding layouts should be mapped to carrier types.
*
* @return the method type consisting of the carrier types of the layouts in this function descriptor.
*/
@ -121,7 +121,7 @@ public sealed interface FunctionDescriptor permits FunctionDescriptorImpl {
}
/**
* Creates a function descriptor with the given argument layouts and no return layout. This is useful to model functions
* Creates a function descriptor with the given argument layouts and no return layout. This is useful for modeling functions
* that return no values.
* @param argLayouts the argument layouts.
* @throws IllegalArgumentException if one of the layouts in {@code argLayouts} is a padding layout

2
src/java.base/share/classes/java/lang/foreign/GroupLayout.java

@ -44,7 +44,7 @@ public sealed interface GroupLayout extends MemoryLayout permits StructLayout, U
/**
* {@return the member layouts of this group layout}
*
* @apiNote the order in which member layouts are returned is the same order in which member layouts have
* @apiNote the order in which member layouts are returned in the same order in which member layouts have
* been passed to one of the group layout factory methods (see {@link MemoryLayout#structLayout(MemoryLayout...)},
* {@link MemoryLayout#unionLayout(MemoryLayout...)}).
*/

42
src/java.base/share/classes/java/lang/foreign/Linker.java

@ -43,13 +43,13 @@ import java.util.stream.Stream;
/**
* A linker provides access to foreign functions from Java code, and access to Java code from foreign functions.
* <p>
* Foreign functions typically reside in libraries that can be loaded on-demand. Each library conforms to
* Foreign functions typically reside in libraries that can be loaded on demand. Each library conforms to
* a specific ABI (Application Binary Interface). An ABI is a set of calling conventions and data types associated with
* the compiler, OS, and processor where the library was built. For example, a C compiler on Linux/x64 usually
* builds libraries that conform to the SystemV ABI.
* <p>
* A linker has detailed knowledge of the calling conventions and data types used by a specific ABI.
* For any library which conforms to that ABI, the linker can mediate between Java code running
* For any library that conforms to that ABI, the linker can mediate between Java code running
* in the JVM and foreign functions in the library. In particular:
* <ul>
* <li>A linker allows Java code to link against foreign functions, via
@ -106,21 +106,21 @@ import java.util.stream.Stream;
* of the C function they wish to link against. This description, a {@link FunctionDescriptor function descriptor},
* defines the layouts associated with the parameter types and return type (if any) of the C function.
* <p>
* Scalar C types such as {@code bool}, {@code int} are modelled as {@linkplain ValueLayout value layouts}
* Scalar C types such as {@code bool}, {@code int} are modeled as {@linkplain ValueLayout value layouts}
* of a suitable carrier. The {@linkplain #canonicalLayouts() mapping} between a scalar type and its corresponding
* canonical layout is dependent on the ABI implemented by the native linker (see below).
* <p>
* Composite types are modelled as {@linkplain GroupLayout group layouts}. More specifically, a C {@code struct} type
* Composite types are modeled as {@linkplain GroupLayout group layouts}. More specifically, a C {@code struct} type
* maps to a {@linkplain StructLayout struct layout}, whereas a C {@code union} type maps to a {@link UnionLayout union
* layout}. When defining a struct or union layout, clients must pay attention to the size and alignment constraint
* of the corresponding composite type definition in C. For instance, padding between two struct fields
* must be modelled explicitly, by adding an adequately sized {@linkplain PaddingLayout padding layout} member
* must be modeled explicitly, by adding an adequately sized {@linkplain PaddingLayout padding layout} member
* to the resulting struct layout.
* <p>
* Finally, pointer types such as {@code int**} and {@code int(*)(size_t*, size_t*)} are modelled as
* Finally, pointer types such as {@code int**} and {@code int(*)(size_t*, size_t*)} are modeled as
* {@linkplain AddressLayout address layouts}. When the spatial bounds of the pointer type are known statically,
* the address layout can be associated with a {@linkplain AddressLayout#targetLayout() target layout}. For instance,
* a pointer that is known to point to a C {@code int[2]} array can be modelled as an address layout whose
* a pointer that is known to point to a C {@code int[2]} array can be modeled as an address layout whose
* target layout is a sequence layout whose element count is 2, and whose element type is {@link ValueLayout#JAVA_INT}.
* <p>
* All native linker implementations are guaranteed to provide canonical layouts for the following set of types:
@ -144,11 +144,11 @@ import java.util.stream.Stream;
* constant {@link ValueLayout#JAVA_INT} on 32-bit platforms.
* <p>
* A native linker typically does not provide canonical layouts for C's unsigned integral types. Instead, they are
* modelled using the canonical layouts associated with their corresponding signed integral types. For instance,
* modeled using the canonical layouts associated with their corresponding signed integral types. For instance,
* the C type {@code unsigned long} maps to the layout constant {@link ValueLayout#JAVA_LONG} on Linux/x64, but maps to
* the layout constant {@link ValueLayout#JAVA_INT} on Windows/x64.
* <p>
* The following table shows some examples of how C types are modelled in Linux/x64 according to the
* The following table shows some examples of how C types are modeled in Linux/x64 according to the
* "System V Application Binary Interface" (all the examples provided here will assume these platform-dependent mappings):
*
* <blockquote><table class="plain">
@ -246,7 +246,7 @@ import java.util.stream.Stream;
*
* Linker implementations may optionally support additional layouts, such as <em>packed</em> struct layouts.
* A packed struct is a struct in which there is at least one member layout {@code L} that has an alignment
* constraint less strict than its natural alignment. This allows avoiding padding between member layouts,
* constraint less strict than its natural alignment. This allows to avoid padding between member layouts,
* as well as avoiding padding at the end of the struct layout. For example:
* {@snippet lang = java:
* // No padding between the 2 element layouts:
@ -317,7 +317,7 @@ import java.util.stream.Stream;
* as the target layout for the address layouts of both parameters. This will allow the comparator method to access
* the contents of the array elements to be compared. We then {@linkplain FunctionDescriptor#toMethodType() turn}
* that function descriptor into a suitable {@linkplain java.lang.invoke.MethodType method type} which we then use to look up
* the comparator method handle. We can now create an upcall stub which points to that method, and pass it, as a function
* the comparator method handle. We can now create an upcall stub that points to that method, and pass it, as a function
* pointer, to the {@code qsort} downcall handle, as follows:
*
* {@snippet lang = java:
@ -343,7 +343,7 @@ import java.util.stream.Stream;
* void *malloc(size_t size);
* }
*
* The {@code malloc} function allocates a region of memory of given size,
* The {@code malloc} function allocates a region of memory with the given size,
* and returns a pointer to that region of memory, which is later deallocated using another function from
* the C standard library:
*
@ -415,12 +415,12 @@ import java.util.stream.Stream;
* }
*
* Note how the segment obtained from {@code allocateMemory} acts as any other segment managed by the confined arena. More
* specifically, the obtained segment has the desired size, can only be accessed by a single thread (the thread which created
* specifically, the obtained segment has the desired size, can only be accessed by a single thread (the thread that created
* the confined arena), and its lifetime is tied to the surrounding <em>try-with-resources</em> block.
*
* <h3 id="variadic-funcs">Variadic functions</h3>
*
* Variadic functions are C functions which can accept a variable number and type of arguments. They are declared with a
* Variadic functions are C functions that can accept a variable number and type of arguments. They are declared with a
* trailing ellipsis ({@code ...}) at the end of the formal parameter list, such as: {@code void foo(int x, ...);}
* The arguments passed in place of the ellipsis are called <em>variadic arguments</em>. Variadic functions are,
* essentially, templates that can be <em>specialized</em> into multiple non-variadic functions by replacing the
@ -435,7 +435,7 @@ import java.util.stream.Stream;
* <li>{@code float} -> {@code double}</li>
* </ul>
* whereby the signed-ness of the source type corresponds to the signed-ness of the promoted type. The complete process
* of default argument promotion is described in the C specification. In effect these promotions place limits on the
* of default argument promotion is described in the C specification. In effect, these promotions place limits on the
* types that can be used to replace the {@code ...}, as the variadic parameters of the specialized form of a variadic
* function will always have a promoted type.
* <p>
@ -503,7 +503,7 @@ import java.util.stream.Stream;
* associated with the upcall stub to a type that is incompatible with the type of the upcall stub, and then attempts to
* invoke the function through the resulting function pointer. Moreover, if the method
* handle associated with an upcall stub returns a {@linkplain MemorySegment memory segment}, clients must ensure
* that this address cannot become invalid after the upcall completes. This can lead to unspecified behavior,
* that this address cannot become invalid after the upcall is completed. This can lead to unspecified behavior,
* and even JVM crashes, since an upcall is typically executed in the context of a downcall method handle invocation.
*
* @implSpec
@ -529,7 +529,7 @@ public sealed interface Linker permits AbstractLinker {
}
/**
* Creates a method handle which is used to call a foreign function with the given signature and address.
* Creates a method handle that is used to call a foreign function with the given signature and address.
* <p>
* Calling this method is equivalent to the following code:
* {@snippet lang=java :
@ -553,7 +553,7 @@ public sealed interface Linker permits AbstractLinker {
MethodHandle downcallHandle(MemorySegment address, FunctionDescriptor function, Option... options);
/**
* Creates a method handle which is used to call a foreign function with the given signature.
* Creates a method handle that is used to call a foreign function with the given signature.
* <p>
* The Java {@linkplain java.lang.invoke.MethodType method type} associated with the returned method handle is
* {@linkplain FunctionDescriptor#toMethodType() derived} from the argument and return layouts in the function descriptor,
@ -660,7 +660,7 @@ public sealed interface Linker permits AbstractLinker {
* <p>
* Each {@link Linker} is responsible for choosing the data types that are widely recognized as useful on the OS
* and processor combination supported by the {@link Linker}. Accordingly, the precise set of data type names
* and canonical layouts exposed by the linker is unspecified; it varies from one {@link Linker} to another.
* and canonical layouts exposed by the linker are unspecified; they vary from one {@link Linker} to another.
* @implNote It is strongly recommended that the result of {@link #canonicalLayouts()} exposes a set of symbols that is stable over time.
* Clients of {@link #canonicalLayouts()} are likely to fail if a data type that was previously exposed by the linker
* is no longer exposed, or if its canonical layout is updated.
@ -787,11 +787,11 @@ public sealed interface Linker permits AbstractLinker {
* A critical function is a function that has an extremely short running time in all cases
* (similar to calling an empty function), and does not call back into Java (e.g. using an upcall stub).
* <p>
* Using this linker option is a hint which some implementations may use to apply
* Using this linker option is a hint that some implementations may use to apply
* optimizations that are only valid for critical functions.
* <p>
* Using this linker option when linking non-critical functions is likely to have adverse effects,
* such as loss of performance, or JVM crashes.
* such as loss of performance or JVM crashes.
*/
static Option critical() {
return LinkerOptions.Critical.INSTANCE;

52
src/java.base/share/classes/java/lang/foreign/MemoryLayout.java

@ -68,7 +68,7 @@ import jdk.internal.foreign.layout.UnionLayoutImpl;
* } TaggedValues[5];
* }
*
* The above declaration can be modelled using a layout object, as follows:
* The above declaration can be modeled using a layout object, as follows:
*
* {@snippet lang=java :
* SequenceLayout TAGGED_VALUES = MemoryLayout.sequenceLayout(5,
@ -88,7 +88,7 @@ import jdk.internal.foreign.layout.UnionLayoutImpl;
* associated with the value layout. That is, the constant {@link ValueLayout#JAVA_INT} has carrier {@code int}, and
* size of 4 bytes;</li>
* <li>The size of an address layout is platform-dependent. That is, the constant {@link ValueLayout#ADDRESS}
* has size of 8 bytes on a 64-bit platform;</li>
* has a size of 8 bytes on a 64-bit platform;</li>
* <li>The size of a padding layout is always provided explicitly, on {@linkplain MemoryLayout#paddingLayout(long) construction};</li>
* <li>The size of a sequence layout whose element layout is <em>E</em> and element count is <em>L</em>,
* is the size of <em>E</em>, multiplied by <em>L</em>;</li>
@ -155,7 +155,7 @@ import jdk.internal.foreign.layout.UnionLayoutImpl;
* }
*
* <p>
* Open path elements also affects the creation of
* Open path elements also affect the creation of
* {@linkplain #byteOffsetHandle(PathElement...) offset-computing method handles}. Each open path element becomes
* an additional {@code long} parameter in the obtained method handle. This parameter can be used to specify the index
* of the sequence element whose offset is to be computed:
@ -185,12 +185,12 @@ import jdk.internal.foreign.layout.UnionLayoutImpl;
* );
* }
*
* This layout is a struct layout which describe a rectangle. It contains a single field, namely {@code points},
* This layout is a struct layout describing a rectangle. It contains a single field, namely {@code points},
* an address layout whose {@linkplain AddressLayout#targetLayout() target layout} is a sequence layout of four
* struct layouts. Each struct layout describes a two-dimensional point, and is defined as a pair or
* {@link ValueLayout#JAVA_INT} coordinates, with names {@code x} and {@code y}, respectively.
* <p>
* With dereference path elements, we can obtain a var handle which accesses the {@code y} coordinate of one of the
* With dereference path elements, we can obtain a var handle that accesses the {@code y} coordinate of one of the
* point in the rectangle, as follows:
*
* {@snippet lang=java :
@ -211,7 +211,7 @@ import jdk.internal.foreign.layout.UnionLayoutImpl;
* <h3 id="well-formedness">Layout path well-formedness</h3>
*
* A layout path is applied to a layout {@code C_0}, also called the <em>initial layout</em>. Each path element in a
* layout path can be thought of as a function which updates the current layout {@code C_i-1} to some other layout
* layout path can be thought of as a function that updates the current layout {@code C_i-1} to some other layout
* {@code C_i}. That is, for each path element {@code E1, E2, ... En}, in a layout path {@code P}, we compute
* {@code C_i = f_i(C_i-1)}, where {@code f_i} is the selection function associated with the path element under consideration,
* denoted as {@code E_i}. The final layout {@code C_i} is also called the <em>selected layout</em>.
@ -278,7 +278,7 @@ import jdk.internal.foreign.layout.UnionLayoutImpl;
* <li>a <em>toplevel</em> variable-length array whose size depends on the value of some unrelated variable, or parameter;</li>
* <li>an variable-length array <em>nested</em> in a struct, whose size depends on the value of some other field in the enclosing struct.</li>
* </ul>
* While variable-length arrays cannot be modelled directly using sequence layouts, clients can still enjoy structured
* While variable-length arrays cannot be modeled directly using sequence layouts, clients can still enjoy structured
* access to elements of variable-length arrays using var handles as demonstrated in the following sections.
*
* <h3 id="variable-length-toplevel">Toplevel variable-length arrays</h3>
@ -292,7 +292,7 @@ import jdk.internal.foreign.layout.UnionLayoutImpl;
* } Point;
* }
*
* In the above code, a point is modelled as two coordinates ({@code x} and {@code y} respectively). Now consider
* In the above code, a point is modeled as two coordinates ({@code x} and {@code y} respectively). Now consider
* the following snippet of C code:
*
* {@snippet lang=c :
@ -303,7 +303,7 @@ import jdk.internal.foreign.layout.UnionLayoutImpl;
* }
* }
*
* Here, we allocate an array of point ({@code points}). Crucially, the size of the array is dynamically bound to the value
* Here, we allocate an array of points ({@code points}). Crucially, the size of the array is dynamically bound to the value
* of the {@code size} variable. Inside the loop, the {@code x} coordinate of all the points in the array is accessed.
* <p>
* To model this code in Java, let's start by defining a layout for the {@code Point} struct, as follows:
@ -353,7 +353,7 @@ import jdk.internal.foreign.layout.UnionLayoutImpl;
* } Polygon;
* }
*
* In the above code, a polygon is modelled as a size (the number of edges in the polygon) and an array of points
* In the above code, a polygon is modeled as a size (the number of edges in the polygon) and an array of points
* (one for each vertex in the polygon). The number of vertices depends on the number of edges in the polygon. As such,
* the size of the {@code points} array is left <em>unspecified</em> in the C declaration, using a <em>Flexible Array Member</em>
* (a feature standardized in C99).
@ -558,7 +558,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
* <ul>
* <li>If the address layout has a target layout {@code T}, then the size of the returned segment
* is {@code T.byteSize()};</li>
* <li>Otherwise, the address layout has no target layout, and the size of the returned segment
* <li>Otherwise, the address layout has no target layout and the size of the returned segment
* is <a href="MemorySegment.html#wrapping-addresses">zero</a>.</li>
* </ul>
* Moreover, if the selected layout is an {@linkplain AddressLayout address layout}, calling {@link VarHandle#set(Object...)}
@ -648,7 +648,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
VarHandle arrayElementVarHandle(PathElement... elements);
/**
* Creates a method handle which, given a memory segment, returns a {@linkplain MemorySegment#asSlice(long,long) slice}
* Creates a method handle which, given a memory segment, returns a {@linkplain MemorySegment#asSlice(long, long) slice}
* corresponding to the layout selected by the given layout path, where the initial layout in the path is this layout.
* <p>
* The returned method handle has the following characteristics:
@ -670,7 +670,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
* according to the {@linkplain #byteAlignment() alignment constraint} of the root layout (this layout), or
* an {@link IllegalArgumentException} will be issued. Note that the alignment constraint of the root layout
* can be more strict (but not less) than the alignment constraint of the selected layout.</li>
* <li>The start offset of the slicing operation (computed as above) must fall fall inside the spatial bounds of the
* <li>The start offset of the slicing operation (computed as above) must fall inside the spatial bounds of the
* accessed memory segment, or an {@link IndexOutOfBoundsException} is thrown. This is the case when {@code O + A <= S},
* where {@code O} is the start offset of the slicing operation (computed as above), {@code A} is the size of the
* selected layout and {@code S} is the size of the accessed memory segment.</li>
@ -680,7 +680,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
* but more flexibly, as some indices can be specified when invoking the method handle.
*
* @param elements the layout path elements.
* @return a method handle which is used to slice a memory segment at the offset selected by the given layout path.
* @return a method handle that is used to slice a memory segment at the offset selected by the given layout path.
* @throws IllegalArgumentException if the layout path is not <a href="#well-formedness">well-formed</a> for this layout
* @throws IllegalArgumentException if the layout path contains one or more <a href=#deref-path-elements>dereference path elements</a>
*/
@ -718,14 +718,14 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
sealed interface PathElement permits LayoutPath.PathElementImpl {
/**
* Returns a path element which selects a member layout with the given name in a group layout.
* Returns a path element that selects a member layout with the given name in a group layout.
*
* @implSpec in case multiple group elements with a matching name exist, the path element returned by this
* method will select the first one; that is, the group element with the lowest offset from current path is selected.
* method will select the first one; that is, the group element with the lowest offset from the current path is selected.
* In such cases, using {@link #groupElement(long)} might be preferable.
*
* @param name the name of the member layout to be selected.
* @return a path element which selects the group member layout with the given name.
* @return a path element that selects the group member layout with the given name.
*/
static PathElement groupElement(String name) {
Objects.requireNonNull(name);
@ -734,7 +734,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
}
/**
* Returns a path element which selects a member layout with the given index in a group layout.
* Returns a path element that selects a member layout with the given index in a group layout.
*
* @param index the index of the member layout element to be selected.
* @return a path element which selects the group member layout with the given index.
@ -749,10 +749,10 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
}
/**
* Returns a path element which selects the element layout at the specified position in a sequence layout.
* Returns a path element that selects the element layout at the specified position in a sequence layout.
*
* @param index the index of the sequence element to be selected.
* @return a path element which selects the sequence element layout with the given index.
* @return a path element that selects the sequence element layout with the given index.
* @throws IllegalArgumentException if {@code index < 0}
*/
static PathElement sequenceElement(long index) {
@ -764,7 +764,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
}
/**
* Returns an <a href="MemoryLayout.html#open-path-elements">open path element</a> which selects the element
* Returns an <a href="MemoryLayout.html#open-path-elements">open path element</a> that selects the element
* layout in a <em>range</em> of positions in a sequence layout. The range is expressed as a pair of starting
* index (inclusive) {@code S} and step factor (which can also be negative) {@code F}.
* <p>
@ -777,7 +777,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
*
* @param start the index of the first sequence element to be selected.
* @param step the step factor at which subsequence sequence elements are to be selected.
* @return a path element which selects the sequence element layout with the given index.
* @return a path element that selects the sequence element layout with the given index.
* @throws IllegalArgumentException if {@code start < 0}, or {@code step == 0}
*/
static PathElement sequenceElement(long start, long step) {
@ -792,7 +792,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
}
/**
* Returns an <a href="MemoryLayout.html#open-path-elements">open path element</a> which selects an unspecified
* Returns an <a href="MemoryLayout.html#open-path-elements">open path element</a> that selects an unspecified
* element layout in a sequence layout.
* <p>
* The exact sequence element selected by this layout is expressed as an index {@code I}. If {@code C} is the
@ -806,10 +806,10 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
}
/**
* Returns a path element which dereferences an address layout as its
* Returns a path element that dereferences an address layout as its
* {@linkplain AddressLayout#targetLayout() target layout} (where set).
*
* @return a path element which dereferences an address layout.
* @return a path element that dereferences an address layout.
*/
static PathElement dereferenceElement() {
return new LayoutPath.PathElementImpl(PathKind.DEREF_ELEMENT,
@ -904,7 +904,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
* structLayout(JAVA_SHORT, MemoryLayout.paddingLayout(2), JAVA_INT);
* }
*
* Or, alternatively, they can use a member layout which features a smaller alignment constraint. This will result
* Or, alternatively, they can use a member layout that features a smaller alignment constraint. This will result
* in a <em>packed</em> struct layout:
*
* {@snippet lang = java:

98
src/java.base/share/classes/java/lang/foreign/MemorySegment.java

@ -92,11 +92,11 @@ import jdk.internal.vm.annotation.ForceInline;
* a positive number but may be <a href="#wrapping-addresses">zero</a>, but never negative.
* <p>
* The address and size of a memory segment jointly ensure that access operations on the segment cannot fall
* <em>outside</em> the boundaries of the region of memory which backs the segment.
* <em>outside</em> the boundaries of the region of memory that backs the segment.
* That is, a memory segment has <em>spatial bounds</em>.
* <p>
* Every memory segment is associated with a {@linkplain Scope scope}. This ensures that access operations
* on a memory segment cannot occur when the region of memory which backs the memory segment is no longer available
* on a memory segment cannot occur when the region of memory that backs the memory segment is no longer available
* (e.g., after the scope associated with the accessed memory segment is no longer {@linkplain Scope#isAlive() alive}).
* That is, a memory segment has <em>temporal bounds</em>.
* <p>
@ -172,7 +172,7 @@ import jdk.internal.vm.annotation.ForceInline;
* and its size is 10. As a result, attempting to read an int value at offset 20 of the
* {@code slice} segment will result in an exception. The {@linkplain Arena temporal bounds} of the original segment
* is inherited by its slices; that is, when the scope associated with {@code segment} is no longer {@linkplain Scope#isAlive() alive},
* {@code slice} will also be become inaccessible.
* {@code slice} will also become inaccessible.
* <p>
* A client might obtain a {@link Stream} from a segment, which can then be used to slice the segment (according to a given
* element layout) and even allow multiple threads to work in parallel on disjoint segment slices
@ -193,7 +193,7 @@ import jdk.internal.vm.annotation.ForceInline;
*
* Access operations on a memory segment are constrained not only by the spatial and temporal bounds of the segment,
* but also by the <em>alignment constraint</em> of the value layout specified to the operation. An access operation can
* access only those offsets in the segment that denote addresses in physical memory which are <em>aligned</em> according
* access only those offsets in the segment that denote addresses in physical memory that are <em>aligned</em> according
* to the layout. An address in physical memory is <em>aligned</em> according to a layout if the address is an integer
* multiple of the layout's alignment constraint. For example, the address 1000 is aligned according to an 8-byte alignment
* constraint (because 1000 is an integer multiple of 8), and to a 4-byte alignment constraint, and to a 2-byte alignment
@ -239,17 +239,17 @@ import jdk.internal.vm.annotation.ForceInline;
* <p>
* The alignment constraint used to access a segment is typically dictated by the shape of the data structure stored
* in the segment. For example, if the programmer wishes to store a sequence of 8-byte values in a native segment, then
* the segment should be allocated by specifying a 8-byte alignment constraint, either via {@link Arena#allocate(long, long)}
* the segment should be allocated by specifying an 8-byte alignment constraint, either via {@link Arena#allocate(long, long)}
* or {@link Arena#allocate(MemoryLayout)}. These factories ensure that the off-heap region of memory backing
* the returned segment has a starting address that is 8-byte aligned. Subsequently, the programmer can access the
* segment at the offsets of interest -- 0, 8, 16, 24, etc -- in the knowledge that every such access is aligned.
* <p>
* If the segment being accessed is a heap segment, then determining whether access is aligned is more complex.
* The address of the segment in physical memory is not known, and is not even fixed (it may change when the segment
* The address of the segment in physical memory is not known and is not even fixed (it may change when the segment
* is relocated during garbage collection). This means that the address cannot be combined with the specified offset to
* determine a target address in physical memory. Since the alignment constraint <em>always</em> refers to alignment of
* addresses in physical memory, it is not possible in principle to determine if any offset in a heap segment is aligned.
* For example, suppose the programmer chooses a 8-byte alignment constraint and tries
* For example, suppose the programmer chooses an 8-byte alignment constraint and tries
* to access offset 16 in a heap segment. If the heap segment's address 0 corresponds to physical address 1000,
* then the target address (1016) would be aligned, but if address 0 corresponds to physical address 1004,
* then the target address (1020) would not be aligned. It is undesirable to allow access to target addresses that are
@ -268,7 +268,7 @@ import jdk.internal.vm.annotation.ForceInline;
* be accessed at <em>any</em> offset under a 4-byte alignment constraint, because there is no guarantee that the target
* address would be 4-byte aligned, e.g., offset 0 would correspond to physical address 1006 while offset 1 would correspond
* to physical address 1007. Similarly, the segment cannot be accessed at any offset under an 8-byte alignment constraint,
* because because there is no guarantee that the target address would be 8-byte aligned, e.g., offset 2 would correspond
* because there is no guarantee that the target address would be 8-byte aligned, e.g., offset 2 would correspond
* to physical address 1008 but offset 4 would correspond to physical address 1010.</li>
* <li>The starting physical address of a {@code long[]} array will be 8-byte aligned (e.g. 1000) on 64-bit platforms,
* so that successive long elements occur at 8-byte aligned addresses (e.g., 1000, 1008, 1016, 1024, etc.) On 64-bit platforms,
@ -377,7 +377,7 @@ import jdk.internal.vm.annotation.ForceInline;
* to read a pointer from some memory segment. This can be done via the
* {@linkplain MemorySegment#get(AddressLayout, long)} access method. This method accepts an
* {@linkplain AddressLayout address layout} (e.g. {@link ValueLayout#ADDRESS}), the layout of the pointer
* to be read. For instance on a 64-bit platform, the size of an address layout is 8 bytes. The access operation
* to be read. For instance, on a 64-bit platform, the size of an address layout is 8 bytes. The access operation
* also accepts an offset, expressed in bytes, which indicates the position (relative to the start of the memory segment)
* at which the pointer is stored. The access operation returns a zero-length native memory segment, backed by a region
* of memory whose starting address is the 64-bit value read at the specified offset.
@ -421,7 +421,7 @@ import jdk.internal.vm.annotation.ForceInline;
* int x = ptr.getAtIndex(ValueLayout.JAVA_INT, 3); // ok
*}
* <p>
* All the methods which can be used to manipulate zero-length memory segments
* All the methods that can be used to manipulate zero-length memory segments
* ({@link #reinterpret(long)}, {@link #reinterpret(Arena, Consumer)}, {@link #reinterpret(long, Arena, Consumer)} and
* {@link AddressLayout#withTargetLayout(MemoryLayout)}) are
* <a href="package-summary.html#restricted"><em>restricted</em></a> methods, and should be used with caution:
@ -618,7 +618,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* and is accessible from any thread. The size of the segment accepted by the cleanup action is {@link #byteSize()}.
*
* @apiNote The cleanup action (if present) should take care not to leak the received segment to external
* clients which might access the segment after its backing region of memory is no longer available. Furthermore,
* clients that might access the segment after its backing region of memory is no longer available. Furthermore,
* if the provided scope is the scope of an {@linkplain Arena#ofAuto() automatic arena}, the cleanup action
* must not prevent the scope from becoming <a href="../../../java/lang/ref/package.html#reachability">unreachable</a>.
* A failure to do so will permanently prevent the regions of memory allocated by the automatic arena from being deallocated.
@ -653,7 +653,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* and is accessible from any thread. The size of the segment accepted by the cleanup action is {@code newSize}.
*
* @apiNote The cleanup action (if present) should take care not to leak the received segment to external
* clients which might access the segment after its backing region of memory is no longer available. Furthermore,
* clients that might access the segment after its backing region of memory is no longer available. Furthermore,
* if the provided scope is the scope of an {@linkplain Arena#ofAuto() automatic arena}, the cleanup action
* must not prevent the scope from becoming <a href="../../../java/lang/ref/package.html#reachability">unreachable</a>.
* A failure to do so will permanently prevent the regions of memory allocated by the automatic arena from being deallocated.
@ -661,7 +661,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* @param newSize the size of the returned segment.
* @param arena the arena to be associated with the returned segment.
* @param cleanup the cleanup action that should be executed when the provided arena is closed (can be {@code null}).
* @return a new segment that has the same address as this segment, but with new size and its scope set to
* @return a new segment that has the same address as this segment, but with the new size and its scope set to
* that of the provided arena.
* @throws UnsupportedOperationException if this segment is not a {@linkplain #isNative() native} segment
* @throws IllegalArgumentException if {@code newSize < 0}
@ -690,7 +690,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Returns {@code true} if this segment is a native segment. A native segment is
* created e.g. using the {@link Arena#allocate(long, long)} (and related) factory, or by
* {@linkplain #ofBuffer(Buffer) wrapping} a {@linkplain ByteBuffer#allocateDirect(int) direct buffer}.
* @return {@code true} if this segment is native segment.
* @return {@code true} if this segment is a native segment.
*/
boolean isNative();
@ -745,7 +745,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
MemorySegment fill(byte value);
/**
* Performs a bulk copy from given source segment to this segment. More specifically, the bytes at
* Performs a bulk copy from the given source segment to this segment. More specifically, the bytes at
* offset {@code 0} through {@code src.byteSize() - 1} in the source segment are copied into this segment
* at offset {@code 0} through {@code src.byteSize() - 1}.
* <p>
@ -798,14 +798,14 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
long mismatch(MemorySegment other);
/**
* Determines whether the contents of this mapped segment is resident in physical
* Determines whether all the contents of this mapped segment are resident in physical
* memory.
*
* <p> A return value of {@code true} implies that it is highly likely
* that all the data in this segment is resident in physical memory and
* may therefore be accessed without incurring any virtual-memory page
* faults or I/O operations. A return value of {@code false} does not
* necessarily imply that this segment's content is not resident in physical
* necessarily imply that this segment's contents are not resident in physical
* memory.
*
* <p> The returned value is a hint, rather than a guarantee, because the
@ -813,7 +813,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* by the time that an invocation of this method returns. </p>
*
* @return {@code true} if it is likely that the contents of this segment
* is resident in physical memory
* are resident in physical memory
*
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -828,7 +828,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Loads the contents of this mapped segment into physical memory.
*
* <p> This method makes a best effort to ensure that, when it returns,
* this contents of this segment is resident in physical memory. Invoking this
* the contents of this segment are resident in physical memory. Invoking this
* method may cause some number of page faults and I/O operations to
* occur. </p>
*
@ -845,7 +845,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Unloads the contents of this mapped segment from physical memory.
*
* <p> This method makes a best effort to ensure that the contents of this segment are
* are no longer resident in physical memory. Accessing this segment's contents
* no longer resident in physical memory. Accessing this segment's contents
* after invoking this method may cause some number of page faults and I/O operations to
* occur (as this segment's contents might need to be paged back in). </p>
*
@ -1029,7 +1029,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* getString(offset, StandardCharsets.UTF_8);
*}
*
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @return a Java string constructed from the bytes read from the given starting address up to (but not including)
* the first {@code '\0'} terminator character (assuming one is found).
* @throws IllegalArgumentException if the size of the string is greater than the largest string
@ -1082,7 +1082,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* {@snippet lang = java:
* setString(offset, str, StandardCharsets.UTF_8);
*}
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* the final address of this write operation can be expressed as {@code address() + offset}.
* @param str the Java string to be written into this segment.
* @throws IndexOutOfBoundsException if {@code offset < 0}
@ -1135,13 +1135,13 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* <p>
* If the buffer is {@linkplain Buffer#isReadOnly() read-only}, the resulting segment is also
* {@linkplain ByteBuffer#isReadOnly() read-only}. Moreover, if the buffer is a {@linkplain Buffer#isDirect() direct buffer},
* the returned segment is a native segment; otherwise the returned memory segment is a heap segment.
* the returned segment is a native segment; otherwise, the returned memory segment is a heap segment.
* <p>
* If the provided buffer has been obtained by calling {@link #asByteBuffer()} on a memory segment whose
* {@linkplain Scope scope} is {@code S}, the returned segment will be associated with the
* same scope {@code S}. Otherwise, the scope of the returned segment is an automatic scope that keeps the provided
* buffer reachable. As such, if the provided buffer is a direct buffer, its backing memory region will not be
* deallocated as long as the returned segment (or any of its slices) are kept reachable.
* deallocated as long as the returned segment, or any of its slices, are kept reachable.
*
* @param buffer the buffer instance to be turned into a new memory segment.
* @return a memory segment, derived from the given buffer instance.
@ -1244,7 +1244,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
/**
* Creates a zero-length native segment from the given {@linkplain #address() address value}.
* The returned segment is associated with the global scope, and is accessible from any thread.
* The returned segment is associated with the global scope and is accessible from any thread.
* <p>
* On 32-bit platforms, the given address value will be normalized such that the
* highest-order ("leftmost") 32 bits of the {@link MemorySegment#address() address}
@ -1309,8 +1309,8 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* <p>
* The copy occurs in an element-wise fashion: the bytes in the source segment are interpreted as a sequence of elements
* whose layout is {@code srcElementLayout}, whereas the bytes in the destination segment are interpreted as a sequence of
* elements whose layout is {@code dstElementLayout}. Both element layouts must have same size {@code S}.
* If the byte order of the two element layouts differ, the bytes corresponding to each element to be copied
* elements whose layout is {@code dstElementLayout}. Both element layouts must have the same size {@code S}.
* If the byte order of the two provided element layouts differs, the bytes corresponding to each element to be copied
* are swapped accordingly during the copy operation.
* <p>
* If the source segment overlaps with the destination segment, then the copying is performed as if the bytes at
@ -1365,7 +1365,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Reads a byte from this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be read.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @return a byte value read from this segment.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}.
@ -1381,7 +1381,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Writes a byte into this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be written.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @param value the byte value to be written.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1398,7 +1398,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Reads a boolean from this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be read.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @return a boolean value read from this segment.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1414,7 +1414,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Writes a boolean into this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be written.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @param value the boolean value to be written.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}.
@ -1431,7 +1431,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Reads a char from this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be read.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @return a char value read from this segment.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1447,7 +1447,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Writes a char into this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be written.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @param value the char value to be written.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1464,7 +1464,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Reads a short from this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be read.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @return a short value read from this segment.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1480,7 +1480,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Writes a short into this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be written.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @param value the short value to be written.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1497,7 +1497,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Reads an int from this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be read.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @return an int value read from this segment.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1513,7 +1513,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Writes an int into this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be written.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @param value the int value to be written.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1530,7 +1530,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Reads a float from this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be read.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @return a float value read from this segment.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1546,7 +1546,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Writes a float into this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be written.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @param value the float value to be written.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1563,7 +1563,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Reads a long from this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be read.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @return a long value read from this segment.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1579,7 +1579,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Writes a long into this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be written.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @param value the long value to be written.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1596,7 +1596,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Reads a double from this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be read.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @return a double value read from this segment.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1612,7 +1612,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Writes a double into this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be written.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @param value the double value to be written.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1632,7 +1632,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* {@linkplain AddressLayout#targetLayout() target layout} {@code T}, then the size of the returned segment
* is set to {@code T.byteSize()}.
* @param layout the layout of the region of memory to be read.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @return a native segment wrapping an address read from this segment.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -1651,7 +1651,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* Writes an address into this segment at the given offset, with the given layout.
*
* @param layout the layout of the region of memory to be written.
* @param offset offset in bytes (relative to this segment address) at which this access operation will occur.
* @param offset the offset in bytes (relative to this segment address) at which this access operation will occur.
* @param value the address value to be written.
* @throws IllegalStateException if the {@linkplain #scope() scope} associated with this segment is not
* {@linkplain Scope#isAlive() alive}
@ -2181,8 +2181,8 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* for equality. That is, two scopes are considered {@linkplain #equals(Object) equal} if they denote the same lifetime.
* <p>
* The lifetime of a memory segment can be either <em>unbounded</em> or <em>bounded</em>. An unbounded lifetime
* is modelled with the <em>global scope</em>. The global scope is always {@link #isAlive() alive}. As such, a segment
* associated with the global scope features trivial temporal bounds, and is always accessible.
* is modeled with the <em>global scope</em>. The global scope is always {@link #isAlive() alive}. As such, a segment
* associated with the global scope features trivial temporal bounds and is always accessible.
* Segments associated with the global scope are:
* <ul>
* <li>Segments obtained from the {@linkplain Arena#global() global arena};</li>
@ -2190,7 +2190,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* <li><a href="#wrapping-addresses">Zero-length memory segments.</a></li>
* </ul>
* <p>
* Conversely, a bounded lifetime is modelled with a segment scope that can be invalidated, either {@link Arena#close() explicitly},
* Conversely, a bounded lifetime is modeled with a segment scope that can be invalidated, either {@link Arena#close() explicitly},
* or automatically, by the garbage collector. A segment scope that is invalidated automatically is an <em>automatic scope</em>.
* An automatic scope is always {@link #isAlive() alive} as long as it is <a href="../../../java/lang/ref/package.html#reachability">reachable</a>.
* Segments associated with an automatic scope are:
@ -2219,7 +2219,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
/**
* {@return {@code true}, if the provided object is also a scope, which models the same lifetime as that
* modelled by this scope}. In that case, it is always the case that
* modeled by this scope}. In that case, it is always the case that
* {@code this.isAlive() == ((Scope)that).isAlive()}.
* @param that the object to be tested.
*/

26
src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java

@ -346,7 +346,7 @@ public interface SegmentAllocator {
* The contents of the source segment is copied into the result segment element by element, according to the byte
* order and alignment constraint of the given element layout.
*
* @implSpec the default implementation for this method is equivalent to the following code:
* @implSpec The default implementation for this method is equivalent to the following code:
* {@snippet lang = java:
* MemorySegment dest = this.allocate(elementLayout, elementCount);
* MemorySegment.copy(source, sourceElementLayout, sourceOffset, dest, elementLayout, 0, elementCount);
@ -389,7 +389,7 @@ public interface SegmentAllocator {
* The contents of the source array is copied into the result segment element by element, according to the byte
* order and alignment constraint of the given element layout.
*
* @implSpec the default implementation for this method is equivalent to the following code:
* @implSpec The default implementation for this method is equivalent to the following code:
* {@snippet lang = java:
* this.allocateFrom(layout, MemorySegment.ofArray(array),
* ValueLayout.JAVA_BYTE, 0, array.length)
@ -408,10 +408,10 @@ public interface SegmentAllocator {
* {@return a new memory segment initialized with the elements in the provided short array.}
* <p>
* The size of the allocated memory segment is {@code elementLayout.byteSize() * elements.length}.
* The contents of the source array is copied into the result segment element by element, according to the byte
* The contents of the source array are copied into the result segment element by element, according to the byte
* order and alignment constraint of the given element layout.
*
* @implSpec the default implementation for this method is equivalent to the following code:
* @implSpec The default implementation for this method is equivalent to the following code:
* {@snippet lang = java:
* this.allocateFrom(layout, MemorySegment.ofArray(array),
* ValueLayout.JAVA_SHORT, 0, array.length)
@ -433,7 +433,7 @@ public interface SegmentAllocator {
* The contents of the source array is copied into the result segment element by element, according to the byte
* order and alignment constraint of the given element layout.
*
* @implSpec the default implementation for this method is equivalent to the following code:
* @implSpec The default implementation for this method is equivalent to the following code:
* {@snippet lang = java:
* this.allocateFrom(layout, MemorySegment.ofArray(array),
* ValueLayout.JAVA_CHAR, 0, array.length)
@ -455,7 +455,7 @@ public interface SegmentAllocator {
* The contents of the source array is copied into the result segment element by element, according to the byte
* order and alignment constraint of the given element layout.
*
* @implSpec the default implementation for this method is equivalent to the following code:
* @implSpec The default implementation for this method is equivalent to the following code:
* {@snippet lang = java:
* this.allocateFrom(layout, MemorySegment.ofArray(array),
* ValueLayout.JAVA_INT, 0, array.length)
@ -477,7 +477,7 @@ public interface SegmentAllocator {
* The contents of the source array is copied into the result segment element by element, according to the byte
* order and alignment constraint of the given element layout.
*
* @implSpec the default implementation for this method is equivalent to the following code:
* @implSpec The default implementation for this method is equivalent to the following code:
* {@snippet lang = java:
* this.allocateFrom(layout, MemorySegment.ofArray(array),
* ValueLayout.JAVA_FLOAT, 0, array.length)
@ -499,7 +499,7 @@ public interface SegmentAllocator {
* The contents of the source array is copied into the result segment element by element, according to the byte
* order and alignment constraint of the given element layout.
*
* @implSpec the default implementation for this method is equivalent to the following code:
* @implSpec The default implementation for this method is equivalent to the following code:
* {@snippet lang = java:
* this.allocateFrom(layout, MemorySegment.ofArray(array),
* ValueLayout.JAVA_LONG, 0, array.length)
@ -521,7 +521,7 @@ public interface SegmentAllocator {
* The contents of the source array is copied into the result segment element by element, according to the byte
* order and alignment constraint of the given element layout.
*
* @implSpec the default implementation for this method is equivalent to the following code:
* @implSpec The default implementation for this method is equivalent to the following code:
* {@snippet lang = java:
* this.allocateFrom(layout, MemorySegment.ofArray(array),
* ValueLayout.JAVA_DOUBLE, 0, array.length)
@ -592,7 +592,7 @@ public interface SegmentAllocator {
MemorySegment allocate(long byteSize, long byteAlignment);
/**
* Returns a segment allocator which responds to allocation requests by returning consecutive slices
* Returns a segment allocator that responds to allocation requests by returning consecutive slices
* obtained from the provided segment. Each new allocation request will return a new slice starting at the
* current offset (modulo additional padding to satisfy alignment constraint), with given size.
* <p>
@ -601,7 +601,7 @@ public interface SegmentAllocator {
*
* @implNote A slicing allocator is not <em>thread-safe</em>.
*
* @param segment the segment which the returned allocator should slice from.
* @param segment the segment from which the returned allocator should slice from.
* @return a new slicing allocator
*/
static SegmentAllocator slicingAllocator(MemorySegment segment) {
@ -610,7 +610,7 @@ public interface SegmentAllocator {
}
/**
* Returns a segment allocator which responds to allocation requests by recycling a single segment. Each
* Returns a segment allocator that responds to allocation requests by recycling a single segment. Each
* new allocation request will return a new slice starting at the segment offset {@code 0}, hence the name
* <em>prefix allocator</em>.
* Equivalent to (but likely more efficient than) the following code:
@ -628,7 +628,7 @@ public interface SegmentAllocator {
* allocator might cause a thread to overwrite contents written to the underlying segment by a different thread.
*
* @param segment the memory segment to be recycled by the returned allocator.
* @return an allocator which recycles an existing segment upon each new allocation request.
* @return an allocator that recycles an existing segment upon each new allocation request.
*/
static SegmentAllocator prefixAllocator(MemorySegment segment) {
return (AbstractMemorySegmentImpl)Objects.requireNonNull(segment);

2
src/java.base/share/classes/java/lang/foreign/SequenceLayout.java

@ -89,7 +89,7 @@ public sealed interface SequenceLayout extends MemoryLayout permits SequenceLayo
* var reshapeSeq = MemoryLayout.sequenceLayout(2, MemoryLayout.sequenceLayout(6, ValueLayout.JAVA_INT));
* }
* <p>
* If one of the provided element count is the special value {@code -1}, then the element
* If one of the provided element counts is the special value {@code -1}, then the element
* count in that position will be inferred from the remaining element counts and the
* element count of the flattened projection of this layout. For instance, a layout equivalent to
* the above {@code reshapeSeq} can also be computed in the following ways:

6
src/java.base/share/classes/java/lang/foreign/SymbolLookup.java

@ -49,7 +49,7 @@ import java.util.function.BiFunction;
* A symbol lookup is created with respect to a particular library (or libraries). Subsequently, the {@link SymbolLookup#find(String)}
* method takes the name of a symbol and returns the address of the symbol in that library.
* <p>
* The address of a symbol is modelled as a zero-length {@linkplain MemorySegment memory segment}. The segment can be used in different ways:
* The address of a symbol is modeled as a zero-length {@linkplain MemorySegment memory segment}. The segment can be used in different ways:
* <ul>
* <li>It can be passed to a {@link Linker} to create a downcall method handle, which can then be used to call the foreign function at the segment's address.</li>
* <li>It can be passed to an existing {@linkplain Linker#downcallHandle(FunctionDescriptor, Linker.Option...) downcall method handle}, as an argument to the underlying foreign function.</li>
@ -132,7 +132,7 @@ public interface SymbolLookup {
Optional<MemorySegment> find(String name);
/**
* {@return a composed symbol lookup that returns result of finding the symbol with this lookup if found,
* {@return a composed symbol lookup that returns the result of finding the symbol with this lookup if found,
* otherwise returns the result of finding the symbol with the other lookup}
*
* @apiNote This method could be used to chain multiple symbol lookups together, e.g. so that symbols could
@ -143,7 +143,7 @@ public interface SymbolLookup {
* .or(SymbolLookup.loaderLookup());
*}
* The above code creates a symbol lookup that first searches for symbols in the "foo" library. If no symbol is found
* in "foo" then "bar" is searched. Finally, if a symbol is not found in neither "foo" nor "bar", the {@linkplain
* in "foo" then "bar" is searched. Finally, if a symbol is neither found in "foo" nor in "bar", the {@linkplain
* SymbolLookup#loaderLookup() loader lookup} is used.
*
* @param other the symbol lookup that should be used to look for symbols not found in this lookup.

6
src/java.base/share/classes/java/lang/foreign/ValueLayout.java

@ -30,7 +30,7 @@ import java.nio.ByteOrder;
import jdk.internal.foreign.layout.ValueLayouts;
/**
* A layout that models values of basic data types. Examples of values modelled by a value layout are
* A layout that models values of basic data types. Examples of values modeled by a value layout are
* <em>integral</em> values (either signed or unsigned), <em>floating-point</em> values and
* <em>address</em> values.
* <p>
@ -42,7 +42,7 @@ import jdk.internal.foreign.layout.ValueLayouts;
* @apiNote Some characteristics of the Java layout constants are platform-dependent. For instance, the byte order of
* these constants is set to the {@linkplain ByteOrder#nativeOrder() native byte order}, thus making it easy to work
* with other APIs, such as arrays and {@link java.nio.ByteBuffer}. Moreover, the alignment constraint of
* {@link ValueLayout#JAVA_LONG} and {@link ValueLayout#JAVA_DOUBLE} is set to 8 bytes on 64-bit platforms, but only to
* {@link ValueLayout#JAVA_LONG} and {@link ValueLayout#JAVA_DOUBLE} are set to 8 bytes on 64-bit platforms, but only to
* 4 bytes on 32-bit platforms.
*
* @implSpec implementing classes and subclasses are immutable, thread-safe and <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.
@ -102,7 +102,7 @@ public sealed interface ValueLayout extends MemoryLayout permits
* The returned var handle checks that accesses are aligned according to this value layout's
* {@linkplain MemoryLayout#byteAlignment() alignment constraint}.
*
* @apiNote This method is similar, but more efficient, than calling {@code MemoryLayout#varHandle(PathElement...)}
* @apiNote This method is similar, but more efficient than calling {@code MemoryLayout#varHandle(PathElement...)}
* with an empty path element array, as it avoids the creation of the var args array.
*
* @apiNote The returned var handle features certain <a href="MemoryLayout.html#access-mode-restrictions">access mode

10
src/java.base/share/classes/java/lang/foreign/package-info.java

@ -33,7 +33,7 @@
* models a contiguous region of memory, residing either inside or outside the Java heap. Memory segments are
* typically allocated using an {@link java.lang.foreign.Arena}, which controls the lifetime of the regions of memory
* backing the segments it allocates. The contents of a memory segment can be described using a
* {@link java.lang.foreign.MemoryLayout memory layout}, which provides basic operations to query sizes, offsets and
* {@link java.lang.foreign.MemoryLayout memory layout}, which provides basic operations to query sizes, offsets, and
* alignment constraints. Memory layouts also provide an alternate, more abstract way, to
* <a href=MemorySegment.html#segment-deref>access memory segments</a> using
* {@linkplain java.lang.foreign.MemoryLayout#varHandle(java.lang.foreign.MemoryLayout.PathElement...) var handles},
@ -61,7 +61,7 @@
* in Section {@jls 14.20.3} of <cite>The Java Language Specification</cite>.
* <p>
* Memory segments provide strong safety guarantees when it comes to memory access. First, when accessing a memory segment,
* the access coordinates are validated (upon access), to make sure that access does not occur at any address which resides
* the access coordinates are validated (upon access), to make sure that access does not occur at any address that resides
* <em>outside</em> the boundaries of the memory segment used by the access operation. We call this guarantee <em>spatial safety</em>;
* in other words, access to memory segments is bounds-checked, in the same way as array access is, as described in
* Section {@jls 15.10.4} of <cite>The Java Language Specification</cite>.
@ -121,14 +121,14 @@
* <p>
* Binding foreign data and/or functions is generally unsafe and, if done incorrectly, can result in VM crashes,
* or memory corruption when the bound Java API element is accessed. For instance, incorrectly resizing a native
* memory sgement using {@link java.lang.foreign.MemorySegment#reinterpret(long)} can lead to a JVM crash, or, worse,
* memory segment using {@link java.lang.foreign.MemorySegment#reinterpret(long)} can lead to a JVM crash, or, worse,
* lead to silent memory corruption when attempting to access the resized segment. For these reasons, it is crucial for
* code that calls a restricted method to never pass arguments that might cause incorrect binding of foreign data and/or
* functions to a Java API.
* <p>
* Given the potential danger of restricted methods, the Java runtime issues a warning on the standard error stream
* every time a restricted method is invoked. Such warnings can be disabled by granting access to restricted methods
* to selected modules. This can be done either via implementation-specific command line options, or programmatically, e.g. by calling
* to selected modules. This can be done either via implementation-specific command line options or programmatically, e.g. by calling
* {@link java.lang.ModuleLayer.Controller#enableNativeAccess(java.lang.Module)}.
* <p>
* For every class in this package, unless specified otherwise, any method arguments of reference
@ -142,7 +142,7 @@
* In the reference implementation, access to restricted methods can be granted to specific modules using the command line option
* {@code --enable-native-access=M1,M2, ... Mn}, where {@code M1}, {@code M2}, {@code ... Mn} are module names
* (for the unnamed module, the special value {@code ALL-UNNAMED} can be used). If this option is specified, access to
* restricted methods is only granted to the modules listed by that option. If this option is not specified,
* restricted methods are only granted to the modules listed by that option. If this option is not specified,
* access to restricted methods is enabled for all modules, but access to restricted methods will result in runtime warnings.
*
* @spec jni/index.html Java Native Interface Specification