Skip to content

8349653: Clarify the docs for MemorySegment::reinterpret #23688

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
minborg wants to merge 1 commit into from
Closed

8349653: Clarify the docs for MemorySegment::reinterpret #23688

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions src/java.base/share/classes/java/lang/foreign/MemorySegment.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -756,30 +756,30 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {

/**
* Returns a new memory segment with the same address and size as this segment, but
* with the provided scope. As such, the returned segment cannot be accessed after
* the provided arena has been closed. Moreover, the returned segment can be
* with the provided arena's scope. As such, the returned segment cannot be accessed
* after the provided arena has been closed. Moreover, the returned segment can be
* accessed compatibly with the confinement restrictions associated with the provided
* arena: that is, if the provided arena is a {@linkplain Arena#ofConfined() confined arena},
* the returned segment can only be accessed by the arena's owner thread, regardless
* of the confinement restrictions associated with this segment. In other words, this
* method returns a segment that can be used as any other segment allocated using the
* provided arena. However, The returned segment is backed by the same memory region
* provided arena. However, the returned segment is backed by the same memory region
* as that of the original segment. As such, the region of memory backing the
* returned segment is deallocated only when this segment's arena is closed.
* This might lead to <em>use-after-free</em> issues, as the returned segment can be
* accessed <em>after</em> its region of memory has been deallocated via this
* segment's arena.
* <p>
* Clients can specify an optional cleanup action that should be executed when the
* provided scope becomes invalid. This cleanup action receives a fresh memory
* provided arena's scope becomes invalid. This cleanup action receives a fresh memory
* segment that is obtained from this segment as follows:
* {@snippet lang=java :
* MemorySegment cleanupSegment = MemorySegment.ofAddress(this.address())
* .reinterpret(byteSize());
* }
* That is, the cleanup action receives a segment that is associated with the global
* scope, and is accessible from any thread. The size of the segment accepted by the
* cleanup action is {@link #byteSize()}.
* arena's scope, and is accessible from any thread. The size of the segment accepted
* by the cleanup action is {@link #byteSize()}.
* <p>
* If this segment is {@linkplain MemorySegment#isReadOnly() read-only},
* the returned segment is also {@linkplain MemorySegment#isReadOnly() read-only}.
Expand All @@ -790,8 +790,8 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* @apiNote The cleanup action (if present) should take care not to leak the received
* segment to external 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
* provided arena is an {@linkplain Arena#ofAuto() automatic arena},
* the cleanup action must not prevent the arena from becoming
* {@linkplain java.lang.ref##reachability unreachable}.
* A failure to do so will permanently prevent the regions of memory
* allocated by the automatic arena from being deallocated.
Expand All @@ -812,30 +812,30 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {

/**
* Returns a new segment with the same address as this segment, but with the provided
* size and scope. As such, the returned segment cannot be accessed after the
* provided arena has been closed. Moreover, if the returned segment can be accessed
* compatibly with the confinement restrictions associated with the provided arena:
* that is, if the provided arena is a {@linkplain Arena#ofConfined() confined arena},
* size and the provided arena's scope. As such, the returned segment cannot be
* accessed after the provided arena has been closed. Moreover, if the returned
* segment can be accessed compatibly with the confinement restrictions associated
* with the provided arena: that is, if the provided arena is a {@linkplain Arena#ofConfined() confined arena},
* the returned segment can only be accessed by the arena's owner thread, regardless
* of the confinement restrictions associated with this segment. In other words, this
* method returns a segment that can be used as any other segment allocated using the
* provided arena. However, The returned segment is backed by the same memory region
* provided arena. However, the returned segment is backed by the same memory region
* as that of the original segment. As such, the region of memory backing the
* returned segment is deallocated only when this segment's arena is closed.
* This might lead to <em>use-after-free</em> issues, as the returned segment can be
* accessed <em>after</em> its region of memory has been deallocated via this
* segment's arena.
* <p>
* Clients can specify an optional cleanup action that should be executed when the
* provided scope becomes invalid. This cleanup action receives a fresh memory
* provided arena's scope becomes invalid. This cleanup action receives a fresh memory
* segment that is obtained from this segment as follows:
* {@snippet lang=java :
* MemorySegment cleanupSegment = MemorySegment.ofAddress(this.address())
* .reinterpret(newSize);
* }
* That is, the cleanup action receives a segment that is associated with the global
* scope, and is accessible from any thread. The size of the segment accepted by the
* cleanup action is {@code newSize}.
* arena's scope, and is accessible from any thread. The size of the segment accepted
* by the cleanup action is {@code newSize}.
* <p>
* If this segment is {@linkplain MemorySegment#isReadOnly() read-only},
* the returned segment is also {@linkplain MemorySegment#isReadOnly() read-only}.
Expand All @@ -846,8 +846,8 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
* @apiNote The cleanup action (if present) should take care not to leak the received
* segment to external 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
* provided arena is an {@linkplain Arena#ofAuto() automatic arena},
* the cleanup action must not prevent the arena from becoming
* {@linkplain java.lang.ref##reachability unreachable}.
* A failure to do so will permanently prevent the regions of memory
* allocated by the automatic arena from being deallocated.
Expand Down