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 memory segments.

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

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.

Implementation Requirements:
  Implementations of this interface are thread-safe.
Since:
  20
See Also:
  - `Arena`PREVIEW
  - `MemorySegment`PREVIEW

- ## 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 any thread.
    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 any thread.
    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`.