com.bigdata.io.writecache.IWriteCache Maven / Gradle / Ivy

Go to download
/**

Copyright (C) SYSTAP, LLC DBA Blazegraph 2006-2016.  All rights reserved.

Contact:
     SYSTAP, LLC DBA Blazegraph
     2501 Calvert ST NW #106
     Washington, DC 20008
     [email protected]

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; version 2 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/
/*
 * Created on Feb 10, 2010
 */

package com.bigdata.io.writecache;

import java.io.IOException;
import java.nio.ByteBuffer;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

import com.bigdata.journal.IAtomicStore;
import com.bigdata.util.ChecksumError;

/**
 * Interface for a write cache with read back and the capability to update
 * records while they are still in the cache.
 * 
 * @author Bryan Thompson
 * @version $Id$
 */
public interface IWriteCache {

    /**
     * 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.
     * 
     * @param offset
     *            The file offset of that record in the backing file.
     * @param data
     *            The record. The bytes from the current
     *            {@link ByteBuffer#position()} to the
     *            {@link ByteBuffer#limit()} will be written and the
     *            {@link ByteBuffer#position()} will be advanced to the
     *            {@link ByteBuffer#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).
     * @param chk
     *            The checksum of the data (optional). When checksums are
     *            not enabled this should be ZERO (0). When checksums are
     *            enabled, {@link #read(long)} will validate the checksum before
     *            returning data.
     * 
     * @return 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
     * @throws IllegalStateException
     *             If the buffer is closed.
     * @throws 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.
     */
    public boolean write(final long offset, final ByteBuffer data, final int chk)
            throws InterruptedException;

    /**
     * Read a record from the write cache.
     * 
     * @param offset
     *            The file offset of that record in the backing file.
     * @param nbytes
     *            The length of the record (decoded from the address by the
     *            caller).
     * 
     * @return The data read -or- null iff the record does not lie
     *         within the {@link IWriteCache}. When non-null, this will be a
     *         newly allocated exact fit mutable {@link 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
     * @throws IllegalStateException
     *             if the buffer is closed.
     * @throws ChecksumError
     *             if checksums are enabled and the checksum for the record
     *             could not be validated.
     */
    public ByteBuffer read(final long offset, final int nbytes) throws InterruptedException,
            ChecksumError;

    /**
     * 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
     * @throws InterruptedException
     * 
     *             FIXME The [force] parameter is ignored and will be removed
     *             shortly.
     */
    public void flush(final 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
     * @throws TimeoutException
     * @throws InterruptedException
     * 
     *             FIXME The [force] parameter is ignored and will be removed
     *             shortly.
     */
    public boolean flush(final boolean force, final long timeout,
            final TimeUnit unit) throws IOException, TimeoutException,
            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 {@link 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
     */
    public void reset() throws InterruptedException;
    
    /**
     * Permanently take the {@link IWriteCache} out of service. Dirty records
     * are discarded, not flushed.
     * 
     * @throws InterruptedException
     */
    public void close() throws InterruptedException;

}