uk.ac.starlink.fits

Class BlockMappedInput

java.lang.Object

uk.ac.starlink.fits.BlockInput

uk.ac.starlink.fits.BlockMappedInput

All Implemented Interfaces:

BasicInput

public abstract class BlockMappedInput
extends BlockInput

Random-access BasicInput implementation that maps a given region of a file as a number of byte buffers. The most recently-used buffer is always kept, but there is a choice of what to do with less-recently used ones. Concrete subclasses are provided that either discard them automatically or keep them around for a period of time before discarding them. If and when a buffer is discarded, an attempt is made to unmap it.

Note: DO NOT use an instance of this class from multiple threads - see Unmapper.

Since:

2 Dec 2014

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_BLOCKSIZE Default maximum size in bytes for mapped blocks.
static long	DEFAULT_EXPIRYMILLIS Default time in milliseconds after which buffers will be discarded.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BlockMappedInput(java.nio.channels.FileChannel channel, long pos, long size, java.lang.String logName, int blockSize) Constructor.

Method Summary

Modifier and Type	Method and Description
void	close() Releases resources belonging to this object.
static BlockMappedInput	createInput(java.nio.channels.FileChannel channel, long pos, long size, java.lang.String logName, boolean caching) Constructs an instance that does or does not support caching.
static BlockMappedInput	createInput(java.nio.channels.FileChannel channel, long pos, long size, java.lang.String logName, int blockSize, long expiryMillis) Constructs an instance with explicit configuration.
long	getBlockOffset(int iblock, int offsetInBlock) Returns the offset into this stream corresponding to a given block index and offset into that block.
int[]	getBlockPos(long offset) Returns the block location of a given byte offset.

Methods inherited from class uk.ac.starlink.fits.BlockInput

acquireBlock, getBlockCount, getOffset, isRandom, readByte, readBytes, readDouble, readFloat, readInt, readLong, readShort, seek, skip

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BLOCKSIZE

public static final int DEFAULT_BLOCKSIZE

Default maximum size in bytes for mapped blocks.

See Also:

Constant Field Values

DEFAULT_EXPIRYMILLIS

public static final long DEFAULT_EXPIRYMILLIS

Default time in milliseconds after which buffers will be discarded.

See Also:

Constant Field Values

Constructor Detail

BlockMappedInput

protected BlockMappedInput(java.nio.channels.FileChannel channel,
                           long pos,
                           long size,
                           java.lang.String logName,
                           int blockSize)
                    throws java.io.IOException

Constructor.

Parameters:

channel - file channel, preferably read-only

pos - offset into file of stream start

size - number of bytes in stream

logName - name for mapped region used in logging messages

blockSize - (maximum) number of bytes per mapped block

Throws:

java.io.IOException

Method Detail

getBlockPos

public int[] getBlockPos(long offset)

Description copied from class: BlockInput

Returns the block location of a given byte offset.

This does the opposite of getBlockOffset.

Specified by:

getBlockPos in class BlockInput

Parameters:

offset - offset into this input stream

Returns:

2-element array giving [blockIndex, offsetInBlock]

getBlockOffset

public long getBlockOffset(int iblock,
                           int offsetInBlock)

Description copied from class: BlockInput

Returns the offset into this stream corresponding to a given block index and offset into that block.

This does the opposite of getBlockPos.

Specified by:

getBlockOffset in class BlockInput

Parameters:

iblock - block index

offsetInBlock - offset into that block

Returns:

offset into stream

close

public void close()

Description copied from interface: BasicInput

Releases resources belonging to this object. Attempts to use it after a call to this method result in undefined behaviour.

Specified by:

close in interface BasicInput

Overrides:

close in class BlockInput

createInput

public static BlockMappedInput createInput(java.nio.channels.FileChannel channel,
                                           long pos,
                                           long size,
                                           java.lang.String logName,
                                           boolean caching)
                                    throws java.io.IOException

Constructs an instance that does or does not support caching. If caching is requested, recently used block buffers are kept around for a while in case they are needed again. If not, as soon as a new block is used, any others are discarded. A default block size is used.

Parameters:

channel - file channel, preferably read-only

pos - offset into file of stream start

size - number of bytes in stream

logName - name for mapped region used in logging messages

caching - whether buffers are cached

Returns:

new instance

Throws:

java.io.IOException

createInput

public static BlockMappedInput createInput(java.nio.channels.FileChannel channel,
                                           long pos,
                                           long size,
                                           java.lang.String logName,
                                           int blockSize,
                                           long expiryMillis)
                                    throws java.io.IOException

Constructs an instance with explicit configuration. The expiryMillis parameter controls caching. If zero, the current buffer is discarded an unmapped as soon as a different one is used. Otherwise, an attempt is made to discard buffers only after they have been unused for a certain number of milliseconds.

Parameters:

channel - file channel, preferably read-only

pos - offset into file of stream start

size - number of bytes in stream

logName - name for mapped region used in logging messages

blockSize - maximum number of bytes per block

expiryMillis - buffer caching period in milliseconds

Returns:

new instance

Throws:

java.io.IOException