org.eclipse.jgit.storage.dht.spi.util
Class AbstractWriteBuffer

java.lang.Object
  extended by org.eclipse.jgit.storage.dht.spi.util.AbstractWriteBuffer
All Implemented Interfaces:
WriteBuffer
Direct Known Subclasses:
CacheBuffer

public abstract class AbstractWriteBuffer
extends java.lang.Object
implements WriteBuffer

Abstract buffer service built on top of an ExecutorService.

Writes are combined together into batches, to reduce RPC overhead when there are many small writes occurring. Batches are sent asynchronously when they reach 512 KiB worth of key/column/value data. The calling application is throttled when the outstanding writes are equal to the buffer size, waiting until the cluster has replied with success or failure.

This buffer implementation is not thread-safe, it assumes only one thread will use the buffer instance. (It does however correctly synchronize with the background tasks it spawns.)


Constructor Summary
protected AbstractWriteBuffer(java.util.concurrent.ExecutorService executor, int bufferSize)
          Initialize a buffer with a backing executor service.
 
Method Summary
 void abort()
          Abort pending writes, and wait for acknowledgment.
protected  boolean add(int size)
          Notify the buffer data is being added onto it.
 void flush()
          Flush any pending writes, and wait for them to complete.
protected  void queued(int size)
          Notify the buffer bytes were enqueued.
protected
<T> void
start(java.util.concurrent.Callable<T> task, int size)
          Start a mutation task.
protected abstract  void startQueuedOperations(int bufferedByteCount)
          Start all queued operations.
protected
<T> AsyncCallback<T>
wrap(AsyncCallback<T> callback, int size)
          Wrap a callback to update the buffer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbstractWriteBuffer

protected AbstractWriteBuffer(java.util.concurrent.ExecutorService executor,
                              int bufferSize)
Initialize a buffer with a backing executor service.

Parameters:
executor - service to run mutation tasks on.
bufferSize - maximum number of bytes to have pending at once.
Method Detail

add

protected boolean add(int size)
               throws DhtException
Notify the buffer data is being added onto it.

This method waits until the buffer has sufficient space for the requested data, thereby throttling the calling application code. It returns true if its recommendation is for the buffer subclass to copy the data onto its internal buffer and defer starting until later. It returns false if the recommendation is to start the operation immediately, due to the large size of the request.

Buffer implementors should keep in mind that the return value is offered as advice only, they may choose to implement different behavior.

Parameters:
size - an estimated number of bytes that the buffer will be responsible for until the operation completes. This should include the row keys and column headers, in addition to the data values.
Returns:
true to enqueue the operation; false to start it right away.
Throws:
DhtException - the current thread was interrupted before space became available in the buffer.

queued

protected void queued(int size)
               throws DhtException
Notify the buffer bytes were enqueued.

Parameters:
size - the estimated number of bytes that were enqueued.
Throws:
DhtException - a previously started operation completed and failed.

startQueuedOperations

protected abstract void startQueuedOperations(int bufferedByteCount)
                                       throws DhtException
Start all queued operations.

This method is invoked by queued(int) or by flush() when there is a non-zero number of bytes already enqueued as a result of prior add(int) and {#link queued(int) calls.

Implementors should use start(Callable, int) to begin their mutation tasks in the background.

Parameters:
bufferedByteCount - number of bytes that were already enqueued. This count should be passed to start(Callable, int).
Throws:
DhtException - a previously started operation completed and failed.

flush

public void flush()
           throws DhtException
Description copied from interface: WriteBuffer
Flush any pending writes, and wait for them to complete.

Specified by:
flush in interface WriteBuffer
Throws:
DhtException - one or more writes failed. As writes may occur in any order, the exact state of the database is unspecified.

abort

public void abort()
           throws DhtException
Description copied from interface: WriteBuffer
Abort pending writes, and wait for acknowledgment.

Once a buffer has been aborted, it cannot be reused. Application code must discard the buffer instance and use a different buffer to issue subsequent operations.

If writes have not been started yet, they should be discarded and not submitted to the storage system.

If writes have already been started asynchronously in the background, this method may try to cancel them, but must wait for the operation to either complete or abort before returning. This allows callers to clean up by scanning the storage system and making corrections to clean up any partial writes.

Specified by:
abort in interface WriteBuffer
Throws:
DhtException - one or more already started writes failed.

start

protected <T> void start(java.util.concurrent.Callable<T> task,
                         int size)
              throws DhtException
Start a mutation task.

Type Parameters:
T - any type the task might return.
Parameters:
task - the mutation task. The result of the task is discarded, so callers should perform result validation within the task.
size - number of bytes that are buffered within the task.
Throws:
DhtException - a prior task has completed, and failed.

wrap

protected <T> AsyncCallback<T> wrap(AsyncCallback<T> callback,
                                    int size)
                         throws DhtException
Wrap a callback to update the buffer.

Flushing the buffer will wait for the returned callback to complete.

Type Parameters:
T - any type the task might return.
Parameters:
callback - callback invoked when the task has finished.
size - number of bytes that are buffered within the task.
Returns:
wrapped callback that will update the buffer state when the callback is invoked.
Throws:
DhtException - a prior task has completed, and failed.


Copyright © 2011. All Rights Reserved.