- * 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. *
* 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: *
- * 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). *
- * 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. *
- * 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}. *
* 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. *
* 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. *
- * 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): * *
@@ -246,7 +246,7 @@ import java.util.stream.Stream; * * Linker implementations may optionally support additional layouts, such as packed 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 try-with-resources block. * *
Variadic functions
* - * 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 variadic arguments. Variadic functions are, * essentially, templates that can be specialized into multiple non-variadic functions by replacing the @@ -435,7 +435,7 @@ import java.util.stream.Stream; *- {@code float} -> {@code double}
* * 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. *@@ -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. *
* 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. *
* 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 { *
* 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). *
- * 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. *
* 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; diff --git a/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java b/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java index 0f1a6efe826..40014e8c41f 100644 --- a/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java +++ b/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; *
- 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;
+ * has a size of 8 bytes on a 64-bit platform; *- The size of a padding layout is always provided explicitly, on {@linkplain MemoryLayout#paddingLayout(long) construction};
*- The size of a sequence layout whose element layout is E and element count is L, * is the size of E, multiplied by L;
@@ -155,7 +155,7 @@ import jdk.internal.foreign.layout.UnionLayoutImpl; * } * *- * 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. *
- * 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; *
Layout path well-formedness
* * A layout path is applied to a layout {@code C_0}, also called the initial layout. 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 selected layout. @@ -278,7 +278,7 @@ import jdk.internal.foreign.layout.UnionLayoutImpl; *- a toplevel variable-length array whose size depends on the value of some unrelated variable, or parameter;
*- an variable-length array nested in a struct, whose size depends on the value of some other field in the enclosing struct.
* - * 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. * *Toplevel variable-length arrays
@@ -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. ** 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 unspecified in the C declaration, using a Flexible Array Member * (a feature standardized in C99). @@ -558,7 +558,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin *
*
* 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. *- If the address layout has a target layout {@code T}, then the size of the returned segment * is {@code T.byteSize()};
- *- Otherwise, the address layout has no target layout, and the size of the returned segment + *
- Otherwise, the address layout has no target layout and the size of the returned segment * is zero.
** 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. - *
- The start offset of the slicing operation (computed as above) must fall fall inside the spatial bounds of the + *
- 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.
@@ -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 well-formed for this layout * @throws IllegalArgumentException if the layout path contains one or more dereference path elements */ @@ -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 open path element which selects the element + * Returns an open path element that selects the element * layout in a range 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}. *@@ -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 open path element which selects an unspecified + * Returns an open path element that selects an unspecified * element layout in a sequence layout. *
* 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 packed struct layout: * * {@snippet lang = java: diff --git a/src/java.base/share/classes/java/lang/foreign/MemorySegment.java b/src/java.base/share/classes/java/lang/foreign/MemorySegment.java index f145276e814..f01ad657313 100644 --- a/src/java.base/share/classes/java/lang/foreign/MemorySegment.java +++ b/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 zero, but never negative. *
* The address and size of a memory segment jointly ensure that access operations on the segment cannot fall - * outside the boundaries of the region of memory which backs the segment. + * outside the boundaries of the region of memory that backs the segment. * That is, a memory segment has spatial bounds. *
* 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 temporal bounds. *
@@ -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. *
* 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 alignment constraint 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 aligned according + * access only those offsets in the segment that denote addresses in physical memory that are aligned according * to the layout. An address in physical memory is aligned 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; *
* 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. *
* 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 always 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 any 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. *
- 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 *} *
- * 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 * restricted 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 unreachable. * 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 unreachable. * 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}. *
@@ -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. * *
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. * *
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.
* * @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. * *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.
* @@ -845,7 +845,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { * Unloads the contents of this mapped segment from physical memory. * *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).
* @@ -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 { ** 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. *
* 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. *
* 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 { *
* 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. *
* 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. *
* The lifetime of a memory segment can be either unbounded or bounded. An unbounded lifetime - * is modelled with the global scope. 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 global scope. 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: *
*
*- Segments obtained from the {@linkplain Arena#global() global arena};
@@ -2190,7 +2190,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl { *- Zero-length memory segments.
*- * 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 automatic scope. * An automatic scope is always {@link #isAlive() alive} as long as it is reachable. * 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. */ diff --git a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java index 0c73f9b904c..fa43a9252bc 100644 --- a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java +++ b/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.} *
* 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. *
@@ -601,7 +601,7 @@ public interface SegmentAllocator { * * @implNote A slicing allocator is not thread-safe. * - * @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 * prefix allocator. * 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); diff --git a/src/java.base/share/classes/java/lang/foreign/SequenceLayout.java b/src/java.base/share/classes/java/lang/foreign/SequenceLayout.java index 953d1cd0278..82a08938c4d 100644 --- a/src/java.base/share/classes/java/lang/foreign/SequenceLayout.java +++ b/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)); * } *
- * 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: diff --git a/src/java.base/share/classes/java/lang/foreign/SymbolLookup.java b/src/java.base/share/classes/java/lang/foreign/SymbolLookup.java index 4af2076fb5f..127a5f5d446 100644 --- a/src/java.base/share/classes/java/lang/foreign/SymbolLookup.java +++ b/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. *
- * 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: *
*
- 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.
*- It can be passed to an existing {@linkplain Linker#downcallHandle(FunctionDescriptor, Linker.Option...) downcall method handle}, as an argument to the underlying foreign function.
@@ -132,7 +132,7 @@ public interface SymbolLookup { Optionalfind(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. diff --git a/src/java.base/share/classes/java/lang/foreign/ValueLayout.java b/src/java.base/share/classes/java/lang/foreign/ValueLayout.java index 00f6541f133..ff2cd290388 100644 --- a/src/java.base/share/classes/java/lang/foreign/ValueLayout.java +++ b/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 * integral values (either signed or unsigned), floating-point values and * address values. * @@ -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 value-based. @@ -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 access mode diff --git a/src/java.base/share/classes/java/lang/foreign/package-info.java b/src/java.base/share/classes/java/lang/foreign/package-info.java index a427ccf371f..bf505284cef 100644 --- a/src/java.base/share/classes/java/lang/foreign/package-info.java +++ b/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 * access memory segments 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 The Java Language Specification. *
* 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 * outside the boundaries of the memory segment used by the access operation. We call this guarantee spatial safety; * 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 The Java Language Specification. @@ -121,14 +121,14 @@ *
* 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. *
* 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)}. *
* 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