uk.ac.starlink.fits

## Class BufferManager

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

-     public class BufferManager
      extends java.lang.Object

  Manages access to a region of a file using monolithic byte buffers. The region is only mapped once, and subsequent buffer requests are handled by duplicating the original mapped buffer.

  Buffers are acquired using `createBuffer()`, and should be disposed of using `disposeBuffer(java.nio.ByteBuffer)` when no longer in use. When none of the buffers are in use any more, `close()` should be called.

  Note: the mapped buffer is unmapped using the supplied `Unmapper` when all created buffers have been disposed, or when close() is called. If any of the created buffers is used after this has happened, and unmapping is actually attempted, very bad consequences may ensue. Therefore this class, or at least its `disposeBuffer(java.nio.ByteBuffer)` and `close()` methods, should be used with extreme caution, or a null Unmapper should be supplied.

  Since:
    12 May 2022

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `BufferManager(java.nio.channels.FileChannel channel, long offset, int leng, java.lang.String logLabel, Unmapper unmapper)` Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Asserts that neither this manager, nor any of the buffers it has supplied, will be used again.
    `java.nio.ByteBuffer` | `createBuffer()` Returns a new read-only ByteBuffer providing access to the file region.
    `void` | `disposeBuffer(java.nio.ByteBuffer buf)` Asserts that the supplied buffer, originally acquired from `createBuffer()`, will no longer be used.

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

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

- - ### Constructor Detail

    - #### BufferManager

          public BufferManager(java.nio.channels.FileChannel channel,
                               long offset,
                               int leng,
                               java.lang.String logLabel,
                               Unmapper unmapper)

      Constructor.
      Parameters:
        `channel` - file channel
        `offset` - offset into file of start of mapped region
        `leng` - length of mapped region
        `logLabel` - description of mapped region suitable for use in logging messages
        `unmapper` - used to unmap buffers, may be null for safety (equivalent to Unmapper.NOP)

  - ### Method Detail

    - #### createBuffer

          public java.nio.ByteBuffer createBuffer()
                                           throws java.io.IOException

      Returns a new read-only ByteBuffer providing access to the file region. The returned object should if possible be passed to `disposeBuffer(java.nio.ByteBuffer)` after it is known that it will no longer be used.
      Returns:
        buffer
      Throws:
        `java.io.IOException`

    - #### disposeBuffer

          public void disposeBuffer(java.nio.ByteBuffer buf)

      Asserts that the supplied buffer, originally acquired from `createBuffer()`, will no longer be used. Resources may be reclaimed.
      Parameters:
        `buf` - previously created buffer

    - #### close

          public void close()

      Asserts that neither this manager, nor any of the buffers it has supplied, will be used again.