Interface ResourceScope

public sealed interface ResourceScope extends AutoCloseable

A resource scope manages the lifecycle of one or more resources. Resources (e.g. MemorySegment) associated with a resource scope can only be accessed while the resource scope is alive (see isAlive()), and by the thread associated with the resource scope (if any).

Explicit resource scopes

Resource scopes obtained from newConfinedScope(), newSharedScope() support deterministic deallocation; We call these resource scopes explicit scopes. Explicit resource scopes can be closed explicitly (see close()). When a resource scope is closed, it is no longer alive (see isAlive(), and subsequent operations on resources associated with that scope (e.g. attempting to access a MemorySegment instance) will fail with IllegalStateException.

Closing a resource scope will cause all the cleanup actions associated with that scope (see addCloseAction(Runnable)) to be called. Moreover, closing a resource scope might trigger the releasing of the underlying memory resources associated with said scope; for instance:

• closing the scope associated with a native memory segment results in freeing the native memory associated with it (see MemorySegment.allocateNative(long, ResourceScope), or SegmentAllocator.arenaAllocator(ResourceScope))
• closing the scope associated with a mapped memory segment results in the backing memory-mapped file to be unmapped (see MemorySegment.mapFile(Path, long, long, FileChannel.MapMode, ResourceScope))
• closing the scope associated with an upcall stub results in releasing the stub (see CLinker.upcallStub(MethodHandle, FunctionDescriptor, ResourceScope)

Sometimes, explicit scopes can be associated with a Cleaner instance (see newConfinedScope(Cleaner) and newSharedScope(Cleaner)). We call these resource scopes managed resource scopes. A managed resource scope is closed automatically once the scope instance becomes unreachable.

Managed scopes can be useful to allow for predictable, deterministic resource deallocation, while still prevent accidental native memory leaks. In case a managed resource scope is closed explicitly, no further action will be taken when the scope becomes unreachable; that is, cleanup actions (see addCloseAction(Runnable)) associated with a resource scope, whether managed or not, are called exactly once.

Implicit resource scopes

Resource scopes obtained from newImplicitScope() cannot be closed explicitly. We call these resource scopes implicit scopes. Calling close() on an implicit resource scope always results in an exception. Resources associated with implicit scopes are released once the scope instance becomes unreachable.

An important implicit resource scope is the so called global scope; the global scope is an implicit scope that is guaranteed to never become unreachable. As a results, the global scope will never attempt to release resources associated with it. Such resources must, where needed, be managed independently by clients.

Thread confinement

Resource scopes can be further divided into two categories: thread-confined resource scopes, and shared resource scopes.

Confined resource scopes (see newConfinedScope()), support strong thread-confinement guarantees. Upon creation, they are assigned an owner thread, typically the thread which initiated the creation operation (see ownerThread()). After creating a confined resource scope, only the owner thread will be allowed to directly manipulate the resources associated with this resource scope. Any attempt to perform resource access from a thread other than the owner thread will result in a runtime failure.

Shared resource scopes (see newSharedScope() and newImplicitScope()), on the other hand, have no owner thread; as such resources associated with this shared resource scopes can be accessed by multiple threads. This might be useful when multiple threads need to access the same resource concurrently (e.g. in the case of parallel processing). For instance, a client might obtain a Spliterator from a shared segment, which can then be used to slice the segment and allow multiple threads to work in parallel on disjoint segment slices. The following code can be used to sum all int values in a memory segment in parallel:

SequenceLayout SEQUENCE_LAYOUT = MemoryLayout.sequenceLayout(1024, MemoryLayouts.JAVA_INT);
try (ResourceScope scope = ResourceScope.newSharedScope()) {
    MemorySegment segment = MemorySegment.allocateNative(SEQUENCE_LAYOUT, scope);
    VarHandle VH_int = SEQUENCE_LAYOUT.elementLayout().varHandle(int.class);
    int sum = StreamSupport.stream(segment.spliterator(SEQUENCE_LAYOUT), true)
        .mapToInt(s -> (int)VH_int.get(s.address()))
        .sum();
}
 

Explicit shared resource scopes, while powerful, must be used with caution: if one or more threads accesses a resource associated with a shared scope while the scope is being closed from another thread, an exception might occur on both the accessing and the closing threads. Clients should refrain from attempting to close a shared resource scope repeatedly (e.g. keep calling close() until no exception is thrown). Instead, clients of shared resource scopes should always ensure that proper synchronization mechanisms (e.g. using resource scope handles, see below) are put in place so that threads closing shared resource scopes can never race against threads accessing resources managed by same scopes.

Resource scope handles

Resource scopes can be made non-closeable by acquiring one or more resource scope handles (see acquire(). A resource scope handle can be used to make sure that resources associated with a given resource scope (either explicit or implicit) cannot be released for a certain period of time - e.g. during a critical region of code involving one or more resources associated with the scope. For instance, an explicit resource scope can only be closed after all the handles acquired against that scope have been closed (see close()). This can be useful when clients need to perform a critical operation on a memory segment, during which they have to ensure that the segment will not be released; this can be done as follows:

MemorySegment segment = ...
ResourceScope.Handle segmentHandle = segment.scope().acquire()
try {
   <critical operation on segment>
} finally {
   segment.scope().release(segmentHandle);
}
 

Acquiring implicit resource scopes is also possible, but it is often unnecessary: since resources associated with an implicit scope will only be released when the scope becomes unreachable, clients can use e.g. Reference.reachabilityFence(Object) to make sure that resources associated with implicit scopes are not released prematurely. That said, the above code snippet works (trivially) for implicit scopes too.