Skip to content

Commit

Permalink
8319324: FFM: Reformat javadocs
Browse files Browse the repository at this point in the history
Reviewed-by: mcimadamore
  • Loading branch information
minborg committed Nov 9, 2023
1 parent a3f1b33 commit f939542
Show file tree
Hide file tree
Showing 16 changed files with 3,008 additions and 2,173 deletions.
62 changes: 36 additions & 26 deletions src/java.base/share/classes/java/lang/foreign/AddressLayout.java
Original file line number Diff line number Diff line change
Expand Up @@ -35,23 +35,27 @@
import java.util.Optional;

/**
* A value layout used to model the address of some region of memory. The carrier associated with an address layout is
* {@code MemorySegment.class}. The size and alignment of an address layout are platform-dependent
* (e.g. on a 64-bit platform, the size and alignment of an address layout are set to 8 bytes).
* A value layout used to model the address of some region of memory. The carrier
* associated with an address layout is {@code MemorySegment.class}. The size and
* alignment of an address layout are platform-dependent (e.g. on a 64-bit platform,
* the size and alignment of an address layout are set to 8 bytes).
* <p>
* An address layout may optionally feature a {@linkplain #targetLayout() target layout}. An address layout with
* target layout {@code T} can be used to model the address of a region of memory whose layout is {@code T}.
* For instance, an address layout with target layout {@link ValueLayout#JAVA_INT} can be used to model the address
* of a region of memory that is 4 bytes long. Specifying a target layout can be useful in the following situations:
* An address layout may optionally feature a {@linkplain #targetLayout() target layout}.
* An address layout with target layout {@code T} can be used to model the address of a
* region of memory whose layout is {@code T}. For instance, an address layout with
* target layout {@link ValueLayout#JAVA_INT} can be used to model the address of a
* region of memory that is 4 bytes long. Specifying a target layout can be useful in
* the following situations:
* <ul>
* <li>When accessing a memory segment that has been obtained by reading an address from another
* memory segment, e.g. using {@link MemorySegment#getAtIndex(AddressLayout, long)};</li>
* <li>When accessing a memory segment that has been obtained by reading an address from
* another memory segment, e.g. using {@link MemorySegment#getAtIndex(AddressLayout, long)};</li>
* <li>When creating a downcall method handle, using {@link Linker#downcallHandle(FunctionDescriptor, Option...)};
* <li>When creating an upcall stub, using {@link Linker#upcallStub(MethodHandle, FunctionDescriptor, Arena, Option...)}.
* </ul>
*
* @implSpec
* Implementations of this interface are immutable, thread-safe and <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.
* Implementations of this interface are immutable, thread-safe and
* <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.
*
* @see #ADDRESS
* @see #ADDRESS_UNALIGNED
Expand Down Expand Up @@ -84,43 +88,49 @@ public sealed interface AddressLayout extends ValueLayout permits ValueLayouts.O
AddressLayout withOrder(ByteOrder order);

/**
* Returns an address layout with the same carrier, alignment constraint, name and order as this address layout,
* but associated with the specified target layout. The returned address layout allows raw addresses to be accessed
* as {@linkplain MemorySegment memory segments} whose size is set to the size of the specified layout. Moreover,
* if the accessed raw address is not compatible with the alignment constraint in the provided layout,
* {@linkplain IllegalArgumentException} will be thrown.
* Returns an address layout with the same carrier, alignment constraint, name and
* order as this address layout, but associated with the specified target layout.
* The returned address layout allows raw addresses to be accessed as
* {@linkplain MemorySegment memory segments} whose size is set to the size of the
* specified layout. Moreover, if the accessed raw address is not compatible with
* the alignment constraint in the provided layout, {@linkplain IllegalArgumentException}
* will be thrown.
* @apiNote
* This method can also be used to create an address layout which, when used, creates native memory
* segments with maximal size (e.g. {@linkplain Long#MAX_VALUE}). This can be done by using a target sequence
* layout with unspecified size, as follows:
* This method can also be used to create an address layout which, when used, creates
* native memory segments with maximal size (e.g. {@linkplain Long#MAX_VALUE}). This
* can be done by using a target sequence layout with unspecified size, as follows:
* {@snippet lang = java:
* AddressLayout addressLayout = ...
* AddressLayout unboundedLayout = addressLayout.withTargetLayout(
* MemoryLayout.sequenceLayout(Long.MAX_VALUE, ValueLayout.JAVA_BYTE));
*}
*
* @param layout the 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
* @param layout the target layout
* @return an address layout with 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()
*/
@CallerSensitive
@Restricted
AddressLayout withTargetLayout(MemoryLayout layout);

/**
* Returns an address layout with the same carrier, alignment constraint, name and order as this address layout,
* but with no target layout.
* Returns an address layout with the same carrier, alignment constraint, name and
* order as this address layout, but with no target layout.
*
* @apiNote This can be useful to compare two address layouts that have different target layouts, but are otherwise equal.
* @apiNote This can be useful to compare two address layouts that have different
* target layouts, but are otherwise equal.
*
* @return an address layout with the same characteristics as this layout, but with no target layout.
* @return an address layout with same characteristics as this layout, but with no
* target layout
* @see #targetLayout()
*/
AddressLayout withoutTargetLayout();

/**
* {@return the target layout associated with this address layout (if any)}.
* {@return the target layout associated with this address layout (if any)}
*/
Optional<MemoryLayout> targetLayout();

Expand Down

1 comment on commit f939542

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.