org.gridgain.grid.kernal.processors.cache

Class GridCacheWriteBehindStore<K,V>

java.lang.Object

org.gridgain.grid.kernal.processors.cache.GridCacheWriteBehindStore<K,V>

All Implemented Interfaces:

GridCacheStore<K,V>, GridLifecycleAware

public class GridCacheWriteBehindStore<K,V>
extends Object
implements GridCacheStore<K,V>, GridLifecycleAware

Internal wrapper for a GridCacheStore that enables write-behind logic.

The general purpose of this approach is to reduce cache store load under high store update rate. The idea is to cache all write and remove operations in a pending map and delegate these changes to the underlying store either after timeout or if size of a pending map exceeded some pre-configured value. Another performance gain is achieved due to combining a group of similar operations to a single batch update.

The essential flush size for the write-behind cache should be at least the estimated count of simultaneously written keys. In case of significantly smaller value there would be triggered a lot of flush events that will result in a high cache store load.

Since write operations to the cache store are deferred, transaction support is lost; no transaction objects are passed to the underlying store.

Field Summary

Fields

Modifier and Type	Field and Description
static float	CACHE_OVERFLOW_RATIO Overflow ratio for critical cache size calculation.
static int	DFLT_CONCUR_LVL Default concurrency level of write cache.
static int	DFLT_INITIAL_CAPACITY Default write cache initial capacity.

Constructor Summary

Constructors

Constructor and Description
GridCacheWriteBehindStore(String gridName, String cacheName, GridLogger log, GridCacheStore<K,V> store) Creates a write-behind cache store for the given store and cache name.

Method Summary

Methods

Modifier and Type	Method and Description
void	forceFlush() Forces all entries collected to be flushed to the underlying store.
int	getWriteBehindBufferSize() Gets count of entries that were processed by the write-behind store and have not been flushed to the underlying store yet.
int	getWriteBehindCriticalOverflowCount() Gets count of write buffer overflow events in progress at the moment.
int	getWriteBehindErrorRetryCount() Gets count of cache entries that are in a store-retry state.
long	getWriteBehindFlushFrequency() Gets the cache flush frequency.
int	getWriteBehindFlushSize() Gets the maximum size of the write-behind buffer.
int	getWriteBehindFlushThreadCount() Gets the number of flush threads that will perform store update operations.
int	getWriteBehindStoreBatchSize() Gets the maximum count of similar (put or remove) operations that can be grouped to a single batch.
int	getWriteBehindTotalCriticalOverflowCount() Gets count of write buffer overflow events since initialization.
V	load(GridCacheTx tx, K key) Loads value for the key from underlying persistent storage.
void	loadAll(GridCacheTx tx, Collection<? extends K> keys, GridBiInClosure<K,V> c) Loads all values for given keys and passes every value to the provided closure.
void	loadCache(GridBiInClosure<K,V> clo, Object... args) Default empty implementation.
void	put(GridCacheTx tx, K key, V val) Stores a given value in persistent storage.
void	putAll(GridCacheTx tx, Map<? extends K,? extends V> map) Stores given key value pairs in persistent storage.
void	remove(GridCacheTx tx, K key) Removes the value identified by given key from persistent storage.
void	removeAll(GridCacheTx tx, Collection<? extends K> keys) Removes all vales identified by given keys from persistent storage.
void	setBatchSize(int batchSize) Sets the maximum count of similar operations that can be grouped to a single batch.
void	setConcurrencyLevel(int concurLvl) Sets concurrency level for the write cache.
void	setFlushFrequency(long cacheFlushFreq) Sets the cache flush frequency.
void	setFlushSize(int cacheMaxSize) Sets the maximum size of the write cache.
void	setFlushThreadCount(int flushThreadCnt) Sets the number of threads that will perform store update operations.
void	setInitialCapacity(int initCap) Sets initial capacity for the write cache.
void	start() Performs all the initialization logic for write-behind cache store.
void	stop() Performs shutdown logic for store.
GridCacheStore<K,V>	store()
String	toString()
void	txEnd(GridCacheTx tx, boolean commit) Tells store to commit or rollback a transaction depending on the value of the 'commit' parameter.

Methods inherited from class java.lang.Object

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

Field Detail

DFLT_INITIAL_CAPACITY

public static final int DFLT_INITIAL_CAPACITY

Default write cache initial capacity.

See Also:

Constant Field Values

CACHE_OVERFLOW_RATIO

public static final float CACHE_OVERFLOW_RATIO

Overflow ratio for critical cache size calculation.

See Also:

Constant Field Values

DFLT_CONCUR_LVL

public static final int DFLT_CONCUR_LVL

Default concurrency level of write cache.

See Also:

Constant Field Values

Constructor Detail

GridCacheWriteBehindStore

public GridCacheWriteBehindStore(String gridName,
                         String cacheName,
                         GridLogger log,
                         GridCacheStore<K,V> store)

Creates a write-behind cache store for the given store and cache name.

Parameters:

gridName - Grid name.

cacheName - Cache name.

log - Grid logger.

store - GridCacheStore that need to be wrapped.

Method Detail

setInitialCapacity

public void setInitialCapacity(int initCap)

Sets initial capacity for the write cache.

Parameters:

initCap - Initial capacity.

setConcurrencyLevel

public void setConcurrencyLevel(int concurLvl)

Sets concurrency level for the write cache. Concurrency level is expected count of concurrent threads attempting to update cache.

Parameters:

concurLvl - Concurrency level.

setFlushSize

public void setFlushSize(int cacheMaxSize)

Sets the maximum size of the write cache. When the count of unique keys in write cache exceeds this value, the eldest entry in the cache is immediately scheduled for write to the underlying store.

Parameters:

cacheMaxSize - Max cache size.

getWriteBehindFlushSize

public int getWriteBehindFlushSize()

Gets the maximum size of the write-behind buffer. When the count of unique keys in write buffer exceeds this value, the buffer is scheduled for write to the underlying store.

If this value is 0, then flush is performed only on time-elapsing basis. However, when this value is 0, the cache critical size is set to GridCacheConfiguration.DFLT_WRITE_BEHIND_CRITICAL_SIZE

Returns:

Buffer size that triggers flush procedure.

setFlushThreadCount

public void setFlushThreadCount(int flushThreadCnt)

Sets the number of threads that will perform store update operations.

Parameters:

flushThreadCnt - Count of worker threads.

getWriteBehindFlushThreadCount

public int getWriteBehindFlushThreadCount()

Gets the number of flush threads that will perform store update operations.

Returns:

Count of worker threads.

setFlushFrequency

public void setFlushFrequency(long cacheFlushFreq)

Sets the cache flush frequency. All pending operations on the underlying store will be performed within time interval not less then this value.

Parameters:

cacheFlushFreq - Time interval value in milliseconds.

getWriteBehindFlushFrequency

public long getWriteBehindFlushFrequency()

Gets the cache flush frequency. All pending operations on the underlying store will be performed within time interval not less then this value.

If this value is 0, then flush is performed only when buffer size exceeds flush size.

Returns:

Flush frequency in milliseconds.

setBatchSize

public void setBatchSize(int batchSize)

Sets the maximum count of similar operations that can be grouped to a single batch.

Parameters:

batchSize - Maximum count of batch.

getWriteBehindStoreBatchSize

public int getWriteBehindStoreBatchSize()

Gets the maximum count of similar (put or remove) operations that can be grouped to a single batch.

Returns:

Maximum size of batch.

getWriteBehindBufferSize

public int getWriteBehindBufferSize()

Gets count of entries that were processed by the write-behind store and have not been flushed to the underlying store yet.

Returns:

Total count of entries in cache store internal buffer.

store

public GridCacheStore<K,V> store()

Returns:

Underlying store.

start

public void start()
           throws GridException

Performs all the initialization logic for write-behind cache store. This class must not be used until this method returns.

Specified by:

start in interface GridLifecycleAware

Throws:

GridException - If cache cannot be started due to some reasons.

getWriteBehindTotalCriticalOverflowCount

public int getWriteBehindTotalCriticalOverflowCount()

Gets count of write buffer overflow events since initialization. Each overflow event causes the ongoing flush operation to be performed synchronously.

Returns:

Count of cache overflow events since start.

getWriteBehindCriticalOverflowCount

public int getWriteBehindCriticalOverflowCount()

Gets count of write buffer overflow events in progress at the moment. Each overflow event causes the ongoing flush operation to be performed synchronously.

Returns:

Count of cache overflow events since start.

getWriteBehindErrorRetryCount

public int getWriteBehindErrorRetryCount()

Gets count of cache entries that are in a store-retry state. An entry is assigned a store-retry state when underlying store failed due some reason and cache has enough space to retain this entry till the next try.

Returns:

Count of entries in store-retry state.

stop

public void stop()
          throws GridException

Performs shutdown logic for store. No put, get and remove requests will be processed after this method is called.

Specified by:

stop in interface GridLifecycleAware

Throws:

GridException - If shutdown failed for some reason.

forceFlush

public void forceFlush()
                throws GridException

Forces all entries collected to be flushed to the underlying store.

Throws:

GridException - If failed.

loadCache

public void loadCache(GridBiInClosure<K,V> clo,
             @Nullable
             Object... args)
               throws GridException

Default empty implementation. This method needs to be overridden only if GridCache.loadCache(GridBiPredicate, long, Object...) method is explicitly called.

Specified by:

loadCache in interface GridCacheStore<K,V>

Parameters:

clo - Closure for loaded values.

args - Arguments passes into GridCache.loadCache(GridBiPredicate, long, Object...) method.

Throws:

GridException - If loading failed.

loadAll

public void loadAll(@Nullable
           GridCacheTx tx,
           @Nullable
           Collection<? extends K> keys,
           GridBiInClosure<K,V> c)
             throws GridException

Loads all values for given keys and passes every value to the provided closure.

For every loaded value method GridInClosure.apply(Object) should be called on the passed in closure. The closure will then make sure that the loaded value is stored in cache.

Specified by:

loadAll in interface GridCacheStore<K,V>

Parameters:

tx - Cache transaction.

keys - Collection of keys to load.

c - Closure to call for every loaded element.

Throws:

GridException - If load failed.

load

public V load(@Nullable
     GridCacheTx tx,
     K key)
       throws GridException

Loads value for the key from underlying persistent storage.

Specified by:

load in interface GridCacheStore<K,V>

Parameters:

tx - Cache transaction.

key - Key to load.

Returns:

Loaded value or null if value was not found.

Throws:

GridException - If load failed.

putAll

public void putAll(@Nullable
          GridCacheTx tx,
          @Nullable
          Map<? extends K,? extends V> map)
            throws GridException

Stores given key value pairs in persistent storage. Note that cache transaction is implicitly created even for a single put. However, if write-behind is configured for a particular cache, transaction object passed in the cache store will be always null.

Specified by:

putAll in interface GridCacheStore<K,V>

Parameters:

tx - Cache transaction, if write-behind is not enabled, null otherwise.

map - Values to store.

Throws:

GridException - If store failed.

put

public void put(@Nullable
       GridCacheTx tx,
       K key,
       V val)
         throws GridException

Stores a given value in persistent storage. Note that cache transaction is implicitly created even for a single put. However, if write-behind is configured for a particular cache, transaction object passed in the cache store will be always null.

Specified by:

put in interface GridCacheStore<K,V>

Parameters:

tx - Cache transaction, if write-behind is not enabled, null otherwise.

key - Key to put.

val - Value to put.

Throws:

GridException - If put failed.

removeAll

public void removeAll(@Nullable
             GridCacheTx tx,
             @Nullable
             Collection<? extends K> keys)
               throws GridException

Removes all vales identified by given keys from persistent storage. Note that cache transaction is implicitly created even for a single put. However, if write-behind is configured for a particular cache, transaction object passed in the cache store will be always null.

Specified by:

removeAll in interface GridCacheStore<K,V>

Parameters:

tx - Cache transaction, if write-behind is not enabled, null otherwise.

keys - Keys to remove.

Throws:

GridException - If remove failed.

remove

public void remove(@Nullable
          GridCacheTx tx,
          K key)
            throws GridException

Removes the value identified by given key from persistent storage. Note that cache transaction is implicitly created even for a single put. However, if write-behind is configured for a particular cache, transaction object passed in the cache store will be always null.

Specified by:

remove in interface GridCacheStore<K,V>

Parameters:

tx - Cache transaction, if write-behind is not enabled, null otherwise.

key - Key to remove.

Throws:

GridException - If remove failed.

txEnd

public void txEnd(GridCacheTx tx,
         boolean commit)
           throws GridException

Tells store to commit or rollback a transaction depending on the value of the 'commit' parameter.

Note that if explicit transactions are not used in code, then it is possible to commit or rollback transactions directly in 'put(..)', or 'remove(..)' methods. In that case, this method should be left empty (GridCacheStoreAdapter provides empty implementation of this method).

Specified by:

txEnd in interface GridCacheStore<K,V>

Parameters:

tx - Cache transaction being ended.

commit - True if transaction should commit, false for rollback.

Throws:

GridException - If commit or rollback failed. Note that commit failure in some cases may bring cache transaction into GridCacheTxState.UNKNOWN which will consequently cause all transacted entries to be invalidated.

toString

public String toString()

Overrides:

toString in class Object