com.bigdata.io.writecache

Interface IWriteCache

All Known Implementing Classes:

RWWriteCacheService, WriteCache, WriteCache.FileChannelScatteredWriteCache, WriteCache.FileChannelWriteCache, WriteCache.ReadCache, WriteCacheService

public interface IWriteCache

Interface for a write cache with read back and the capability to update records while they are still in the cache.

Version:

$Id$

Author:

Bryan Thompson

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Permanently take the IWriteCache out of service.
void	flush(boolean force) Flush the writes to the backing channel but does not force anything to the backing channel.
boolean	flush(boolean force, long timeout, TimeUnit unit) Flush the writes to the backing channel but does not force anything to the backing channel.
ByteBuffer	read(long offset, int nbytes) Read a record from the write cache.
void	reset() Reset the write cache, discarding any writes which have not been written through to the backing channel yet.
boolean	write(long offset, ByteBuffer data, int chk) Write the record on the cache.

Method Detail

write

boolean write(long offset,
            ByteBuffer data,
            int chk)
              throws InterruptedException

Write the record on the cache. This interface DOES NOT provide any guarantee about the ordering of writes. Callers who require a specific ordering must coordinate that ordering themselves, e.g., by synchronizing across their writes onto the cache.

Parameters:

offset - The file offset of that record in the backing file.

data - The record. The bytes from the current Buffer.position() to the Buffer.limit() will be written and the Buffer.position() will be advanced to the Buffer.limit() . The caller may subsequently modify the contents of the buffer without changing the state of the cache (i.e., the data are copied into the cache).

chk - The checksum of the data (optional). When checksums are not enabled this should be ZERO (0). When checksums are enabled, #read(long) will validate the checksum before returning data.

Returns:

true iff the caller's record was transferred to the cache. When false, there is not enough room left in the write cache for this record.

Throws:

InterruptedException

IllegalStateException - If the buffer is closed.

IllegalArgumentException - If the caller's record is larger than the maximum capacity of cache (the record could not fit within the cache). The caller should check for this and provide special handling for such large records. For example, they can be written directly onto the backing channel.

read

ByteBuffer read(long offset,
              int nbytes)
                throws InterruptedException,
                       ChecksumError

Read a record from the write cache.

Parameters:

offset - The file offset of that record in the backing file.

nbytes - The length of the record (decoded from the address by the caller).

Returns:

The data read -or- null iff the record does not lie within the IWriteCache. When non-null, this will be a newly allocated exact fit mutable ByteBuffer backed by a Java byte[]. The buffer will be flipped to prepare for reading (the position will be zero and the limit will be the #of bytes read). The data DOES NOT include the bytes used to code checksum even when checksums are enabled.

Throws:

InterruptedException

IllegalStateException - if the buffer is closed.

ChecksumError - if checksums are enabled and the checksum for the record could not be validated.

flush

void flush(boolean force)
           throws IOException,
                  InterruptedException

Flush the writes to the backing channel but does not force anything to the backing channel. The caller is responsible for managing when the channel is forced to the disk (if it is backed by disk) and whether file data or file data and file metadata are forced to the disk.

Throws:

IOException

InterruptedException - FIXME The [force] parameter is ignored and will be removed shortly.

flush

boolean flush(boolean force,
            long timeout,
            TimeUnit unit)
              throws IOException,
                     TimeoutException,
                     InterruptedException

Flush the writes to the backing channel but does not force anything to the backing channel. The caller is responsible for managing when the channel is forced to the disk (if it is backed by disk) and whether file data or file data and file metadata are forced to the disk.

Throws:

IOException

TimeoutException

InterruptedException - FIXME The [force] parameter is ignored and will be removed shortly.

reset

void reset()
           throws InterruptedException

Reset the write cache, discarding any writes which have not been written through to the backing channel yet. This method IS NOT responsible for discarding writes which have been written through since those are in general available for reading directly from the backing channel. The abort protocol at the IAtomicStore level is responsible for ensuring that processes do not see old data after an abort. This is generally handled by re-loading the appropriate root block and reinitializing various things from that root block.

Throws:

InterruptedException

close

void close()
           throws InterruptedException

Permanently take the IWriteCache out of service. Dirty records are discarded, not flushed.

Throws:

InterruptedException