SegmentScope is a preview API of the Java platform.
A memory segment can only be accessed while its scope is alive. Moreover, depending on how the segment scope has been obtained, access might additionally be restricted to specific threads.
The simplest segment scope is the global scope. The global scope is always alive. As a result, segments associated with the global scope are always accessible and their backing regions of memory are never deallocated. Moreover, memory segments associated with the global scope can be accessed from any thread.
MemorySegment segment = MemorySegment.allocateNative(100, SegmentScope.global());
...
// segment is never deallocated!
Alternatively, clients can obtain an automatic scope, that is a segment scope that is managed, automatically, by the garbage collector. The regions of memory backing memory segments associated with an automatic scope are deallocated at some unspecified time after they become unreachable, as shown below:
MemorySegment segment = MemorySegment.allocateNative(100, SegmentScope.auto());
...
segment = null; // the segment region becomes available for deallocation after this point
Finally, clients can obtain a segment scope from an existing arenaPREVIEW, the arena scope. The regions of memory
backing memory segments associated with an arena scope are deallocated when the arena is closedPREVIEW.
When this happens, the arena scope becomes not alive and subsequent access operations on segments
associated with the arena scope will fail IllegalStateException.
MemorySegment segment = null;
try (Arena arena = Arena.openConfined()) {
segment = MemorySegment.allocateNative(100, arena.scope());
...
} // segment region deallocated here
segment.get(ValueLayout.JAVA_BYTE, 0); // throws IllegalStateException
access memory segments associated with an arena scope depends
on the arena kind. For instance, segments associated with the scope of a confined arenaPREVIEW
can only be accessed by the thread that created the arena. Conversely, segments associated with the scope of
shared arenaPREVIEW can be accessed by any thread.- Implementation Requirements:
- Implementations of this interface are thread-safe.
- Since:
- 20
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionstatic SegmentScopePREVIEWauto()Creates a new scope that is managed, automatically, by the garbage collector.static SegmentScopePREVIEWglobal()Obtains the global scope.booleanisAccessibleBy(Thread thread) Returnstrueif the provided thread can access and/or associate segments with this scope.booleanisAlive()Returnstrue, if this scope is alive.voidwhileAlive(Runnable action) Runs a critical action while this scope is kept alive.
-
Method Details
-
auto
Creates a new scope that is managed, automatically, by the garbage collector. Segments associated with the returned scope can be accessed by any thread.- Returns:
- a new scope that is managed, automatically, by the garbage collector.
-
global
Obtains the global scope. Segments associated with the global scope can be accessed by any thread.- Returns:
- the global scope.
-
isAlive
boolean isAlive()Returnstrue, if this scope is alive.- Returns:
true, if this scope is alive
-
isAccessibleBy
Returnstrueif the provided thread can access and/or associate segments with this scope.- Parameters:
thread- the thread to be tested.- Returns:
trueif the provided thread can access and/or associate segments with this scope
-
whileAlive
Runs a critical action while this scope is kept alive.- Parameters:
action- the action to be run.- Throws:
IllegalStateException- if this scope is not alive.WrongThreadException- if this method is called from a threadT, such thatisAccessibleBy(T) == false.
-
SegmentScopewhen preview features are enabled.