uk.ac.starlink.fits

## Class Unmapper

- java.lang.Object
- - uk.ac.starlink.fits.Unmapper

-     public abstract class Unmapper
      extends java.lang.Object

  Attempts to free resources from a MappedByteBuffer.

  This is a tricky business. There is no good way to unmap the memory mapped by a MappedByteBuffer. The MappedByteBuffer javadocs say "A mapped byte buffer and the file mapping that it represents remain valid until the buffer itself is garbage-collected.", and there is no explicit unmap method. However, since the resources locked by memory mapping are separate from the JVM heap, there is no guarantee that garbage collection will happen even when mapped memory reaches crisis levels, and in practice this can lead to cache thrashing and the OS locking up even when there are many MappedByteBuffers without active references, at least on some platforms (I see it on Scientific Linux 6.5 with 24Gb RAM, but not SL 6.3 with 4Gb, but I'm not sure what the relevant differences are).

  The preferred method used here is to employ classes in the implementation-specific `sun.*` namespace to do the unmapping. This is clearly not guaranteed to work on all J2SE implementations, and moreover it risks a JVM crash if the buffer instance is used after the umapping has been done. So use it WITH EXTREME CAUTION. If the relevant classes are not available at runtime, unmapping simply isn't done.

  See also Java Bug Java Bug #4724038.

  Forcing garbage collection with `System.gc()` calls would be another possibility (may be added here at some point), but it's not guaranteed to do anything, and doing it too often would impact performance.

  Since:
    2 Dec 2014

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `UNMAP_PROPERTY` Name of system property to control buffer unmapping ("startable.unmap").

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Unmapper()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Unmapper` | `getInstance()` Returns an instance of this class.
    `abstract boolean` | `unmap(java.nio.MappedByteBuffer buf)` Attempts to release the resources (mapped memory) used by a given MappedByteBuffer.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### UNMAP_PROPERTY

          public static final java.lang.String UNMAP_PROPERTY

      Name of system property to control buffer unmapping ("startable.unmap"). Possible values are currently:
      - "`sun`": best-efforts sun.misc-based option
      - "`cleaner`": sun.misc.Cleaner-based option (available in Oracle java6 through java8)
      - "`unsafe`": sun.misc.Unsafe-based option (available in Oracle java9 and later?)
      - "`none`": no unmapping
      The default is to use "`sun`" if available, else fall back to none. You can also give the classname of an `Unmapper` concrete subclass with a no-arg constructor.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Unmapper

          public Unmapper()

  - ### Method Detail

    - #### unmap

          public abstract boolean unmap(java.nio.MappedByteBuffer buf)

      Attempts to release the resources (mapped memory) used by a given MappedByteBuffer. The buffer MUST NOT be read after this call has been made.
      Parameters:
        `buf` - buffer
      Returns:
        true if unmapping was successfully performed

    - #### getInstance

          public static Unmapper getInstance()

      Returns an instance of this class.
      Returns:
        instance