Package org.apache.datasketches.memory

Interface Handle

  • All Superinterfaces:
    AutoCloseable
    All Known Subinterfaces:
    MapHandle, WritableHandle, WritableMapHandle
    public interface Handle
extends AutoCloseable
    A handle for read-only Memory resource.

    The purpose of a Handle is to

    • Provide a strong reference to an external resource.
    • Extend AutoCloseable, which provides a means to close the resource.
    • Provide other capabilites unique to a particular resource.

    Maintaining strong references to external resources is critical to avoid accidental use-after-free scenarios, where the Garbage Collector will automatically close an external resource if there are no remaining strong references to it. One very common mistake, is to allow a newly created Handle to fall out-of-scope from the block where it was created, such as from a try-with-resources statement. The Garbage Collector will eventually close the Handle referent resource.

    Another use-after-free scenario is where a thread or agent, with access to the Handle, prematurely closes a resource, when another part of the program is still using that same resource. Avoiding this scenario requires careful planning and design.

    The design philosophy here is that whatever process created the external resource has the responsibility to close() that resource when it is no longer needed. This responsibility can be delegated, by passing the appropriate Handle to the delegatee. In principle, however, at any one time there should be only one agent holding the Handle and responsible for closing the resource.

    Author:
    Lee Rhodes, Roman Leventov

    • Method Detail

      • get

        Memory get()
        Gets a Memory
        Returns:
        a Memory