Module java.base
Package java.lang.foreign

Interface SegmentScope

public sealed interface SegmentScope
SegmentScope is a preview API of the Java platform.
Programs can only use SegmentScope when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A segment scope controls access to a memory segment.

A memory segment can only be accessed while its scope is alive. Moreoever, 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
Memory segments associated with an automatic scope can also be accessed from any thread.

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
Which threads can 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.
Since:
20
See Also:
Implementation Requirements:
Implementations of this interface are thread-safe.

  • Method Summary

    Modifier and Type
    Method
    Description
    static SegmentScopePREVIEW
    auto()
    Creates a new scope that is managed, automatically, by the garbage collector.
    static SegmentScopePREVIEW
    global()
    Obtains the global scope.
    boolean
    isAccessibleBy(Thread thread)
    Returns true if the provided thread can access and/or associate segments with this scope.
    boolean
    isAlive()
    Returns true, if this scope is alive.
    void
    whileAlive(Runnable action)
    Runs a critical action while this scope is kept alive.

  • Method Details

    • auto

      static SegmentScopePREVIEW auto()
      Creates a new scope that is managed, automatically, by the garbage collector. Segments associated with the returned scope can be accessed by multiple threads.
      Returns:
      a new scope that is managed, automatically, by the garbage collector.

    • global

      static SegmentScopePREVIEW global()
      Obtains the global scope. Segments associated with the global scope can be accessed by multiple threads.
      Returns:
      the global scope.

    • isAlive

      boolean isAlive()
      Returns true, if this scope is alive.
      Returns:
      true, if this scope is alive

    • isAccessibleBy

      boolean isAccessibleBy(Thread thread)
      Returns true if the provided thread can access and/or associate segments with this scope.
      Parameters:
      thread - the thread to be tested.
      Returns:
      true if the provided thread can access and/or associate segments with this scope

    • whileAlive

      void whileAlive(Runnable action)
      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 thread T, such that isAccessibleBy(T) == false.