com.sleepycat.je.evictor

Class OffHeapCache

java.lang.Object

com.sleepycat.je.evictor.OffHeapCache

All Implemented Interfaces:

EnvConfigObserver

public class OffHeapCache
extends Object
implements EnvConfigObserver

Off-heap cache and evictor. Overview -------- When an LN or BIN is evicted from the main cache it is moved off-heap. The off-heap evictor (this class) will apply the same LRU algorithm and CacheMode logic that is used by the main evictor. When an off-heap cache is used, the main evictor will not place dirty INs on a priority 2 LRU list, and will not perform LN stripping or BIN delta mutation; instead, these actions become the responsibility of the off-heap evictor. UINs are not stored off-heap because the complexity this would add is not worth the benefits. An extremely large data set can be represented by the UINs that fit in a 10GB main cache, so the lack of off-heap UINs is not considered a deficiency. Movement of LNs and BINs between the two caches is performed as follows. Note that LNs and BINs are not moved off-heap if they are deleted nor if they belong to an internal database. And of course, embedded and duplicate DB LNs are not stored separately off-heap. When an LN or a BIN is evicted from main, it is stored off-heap. If the off-heap memory block cannot be allocated, the object is not stored and no exception is thrown. This prevents allocation failures from causing CRUD operation failures. Stats about allocation failures are maintained and a SEVERE message is logged when the failure is because no more system memory is available. See the OffHeapAllocator interface for details. For an off-heap LN with a parent BIN in main cache, the LN's memory ID is maintained in the BIN. The BIN is assigned an off-heap LRU index so the off-heap evictor can perform off-heap LN stripping. In this case, the BIN is in both a main and off-heap LRU list. For now at least (TODO), because deferred write DBs are not supported, a priority-1 off-heap LRU list is used, since the LNs will never be logged. An off-heap BIN is assigned an off-heap LRU index, which is stored in its parent UIN slot in main cache. The slot also has an "off-heap dirty" flag that allows the checkpointer to discover dirty off-heap BINs, and "priority 2" flag that indicates whether the BIN is in the priority 1 or 2 LRU lists. When a BIN moves off-heap and the BIN currently has off-heap LNs, the references (memory IDs) of the off-heap LNs are stored with the serialized BIN. When the off-heap evictor processes the BIN, it will free the off-heap LNs and modify or replace the off-heap BIN so that it no longer references them. This is the equivalent of the LN stripping performed by the main cache evictor. An off-heap BIN will be mutated to a BIN-delta using the same rules used by the main evictor. The use of separate priority 1 and priority 1 LRU lists also copies the approach used in the main evictor (when no off-heap cache is configured). - Eviction of nodes on the priority 2 lists occurs only after emptying the priority 1 lists. - A BIN is moved from a priority 1 list to a priority 2 list when it is dirty, its LNs have been stripped and BIN-delta mutation has been attempted. - Therefore, only dirty BINs with no resident LNs, and which have been mutated to BIN-deltas (if possible), appear in the priority 2 lists. However, in the off-heap cache, all off-heap BINs appear in an LRU list, unlike the main cache where some INs do not appear because they have resident children and therefore are not evictable. Nodes in both caches at once ---------------------------- There are advantages and disadvantages to allowing duplication of a node (LN or BIN) in the off-heap and main cache. The advantage is when a node is loaded from off-heap into main, and we know (because CacheMode.EVICT_LN, EVICT_BIN or UNCHANGED is used) that when the operation is complete the node will be evicted from main and stored off-heap again. In this case it is more efficient to leave it off-heap and tolerate the duplication for the duration of the operation. However, the drawbacks of doing this are: 1. We cannot assume in code that a node is in only one cache at a time. When it appears in both caches, we must always use the object in the main cache, since the off-heap object may be stale. 2. If for some reason the node is NOT evicted from the main cache, we must remove it from off-heap. This can happen when the node is accessed with a different CacheMode (by the original thread or a different thread) prior to completing the operation. Removal from the off-heap cache should be done ASAP, so the duplication does not cause unnecessary eviction. 3. If the node in the main cache is modified, this invalidates the node in the off-heap cache and we must be sure not to use the off-heap version and to remove it ASAP. This is very complex for BINs in particular, because they can be modified in so many different ways. For LNs, on the other hand, the types of modifications are fairly limited. Because of the complexity issue in item 3, we do not allow duplication of BINs. We do allow duplication of LNs, and this is handled as follows: - freeRedundantLN is called when an LN is accessed via IN.fetchLN or getLN. If a CacheMode is used that will not evict the LN, the LN is removed from off-heap. - freeLN is called (via BIN.freeOffHeapLN) during any operation that will modify an LN. If for some reason these mechanisms fail to prevent unwanted duplication, eviction will eventually remove the redundant nodes. LRU data structures and concurrency control ------------------------------------------- LRU entries form linked lists. Like in the main cache, there are two sets of LRU lists for priority 1 and 2 BINs, and multiple lists in each set to reduce thread contention on the linked lists. LRU information is allocated using arrays to minimize per-entry object overhead. There is a single pool of allocated entries that are used for all LRULists. The entries are uniquely identified by an int ID. The arrays are allocated in Chunks and a Chunk is never de-allocated. This is for two reasons: - Chunks can be referenced without any locking (concurrency control is discussed below). - Using Chunks avoids having to pre-allocate all LRU entries, while still minimizing Object overhead (see CHUNK_SIZE). The 'chunks' array contains all allocated Chunks. In each Chunk there is an array for each field in an LRU entry. LRU entries are assigned sequential int IDs starting from zero. The chunk for a given entry ID is: chunks[entry / CHUNK_SIZE] and the array index within the chunk is: entry % CHUNK_SIZE The chunks array can be read (indexed to obtain a Chunk object) without any locking because a copy-on-write technique is used. When a new Chunk must be allocated, the addRemoveEntryMutex protects the assignment of the chunks array. This mutex also protects the free entry list (the firstFreeListEntry field and the next/prev indexes of the entries on the free list). This mutex is global per Environment, but is not frequently locked -- only when an LRU entry is added or removed. The fields of an LRU entry -- the array slots -- are protected as follows. - The linked list fields -- prev and next slots -- are protected by the LRUList mutex, for entries in an LRUList. For entries on the free list, these are protected by the addRemoveEntryMutex. - Other fields -- owners and memIds slots, for example -- are protected by the IN latch. The IN "owns" these fields for its associated LRU entry (in the case of a BIN) or entries (in the case of an IN). Of course the IN latch also protects the fields in the IN related to the LRU entry: the BIN's lruIdx field, and the arrays of child LN memId (for a BIN) and child IN lruIdx (for a UIN). When multiple locks are taken, the order is: IN latch, LRUList mutex -or- IN latch, addRemoveEntryMutex The LRUList mutex and addRemoveEntryMutex are never both locked. AN LRU entry is in a special state when it is removed from the LRU list and is being processed by the evictor. In this case the IN is latched, but there is a window after it is removed and before it is latched where anything can happen. Before processing, several checks are made to ensure that the entry still belongs to the IN, the IN has not been evicted, and the entry has not been put back on the LRUList. This last check requires synchronizing on the LRUList, so unfortunately we must synchronize twice on the LRU list: once to remove the entry, and again after latching the IN to ensure that it has not been put back on the LRUList by another thread. TODO: - Test allocation failures using an allocator that simulates random failures. Currently, allocation failures never happen in the real world, because Linux kills the process before memory is exhausted. But when we allow alternate allocators, failures may occur if a memory pool is filled.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	OffHeapCache.BINInfo

Field Summary

Fields

Modifier and Type	Field and Description
static long	MIN_MAIN_CACHE_OVERHEAD

Constructor Summary

Constructors

Constructor and Description
OffHeapCache(EnvironmentImpl envImpl)

Method Summary

Modifier and Type	Method and Description
long	clearCache(EnvironmentImpl matchEnv)
INLogEntry<BIN>	createBINLogEntryForCheckpoint(IN parent, int index)
void	doCriticalEviction(boolean backgroundIO)
void	doDaemonEviction(boolean backgroundIO)
void	doManualEvict()
boolean	ensureOffHeapLNsInLRU(BIN bin)
void	envConfigUpdate(DbConfigManager configManager, EnvironmentMutableConfig ignore) Notifies the observer that one or more mutable properties have been changed.
void	evictBINIfLsnMatch(EnvironmentImpl envImpl, int entry, long lsn)
long	freeBIN(BIN bin, IN parent, int index)
int	freeLN(BIN bin, int index)
void	freeRedundantLN(BIN bin, int index, LN ln, CacheMode cacheMode)
OffHeapAllocator	getAllocator()
byte[]	getBINBytes(IN parent, int index)
OffHeapCache.BINInfo	getBINInfo(EnvironmentImpl envImpl, int entry)
long	getMaxMemory()
long	getMemId(int entry)
long	getUsedMemory()
boolean	haveBINBytesChanged(IN parent, int index, byte[] bytes) Called when a BIN's bytes were obtained holding a shared latch, and then the latch was released and acquired again.
boolean	isEnabled()
BIN	loadBIN(EnvironmentImpl envImpl, int entry)
BIN	loadBINIfLsnMatches(EnvironmentImpl envImpl, int entry, long lsn) Loads a BIN for the given entry, if its last logged LSN is the given LSN.
LN	loadLN(BIN bin, int index, CacheMode cacheMode)
StatGroup	loadStats(StatsConfig config)
long	loadVLSN(BIN bin, int index)
BIN	materializeBIN(EnvironmentImpl envImpl, byte[] buf)
int	moveBack(int entry, boolean pri2)
long	mutateToBINDelta(IN parent, int index)
void	postBINLoad(IN parent, int index, BIN bin)
void	postBINLog(IN parent, int index, INLogEntry<BIN> logEntry, long newLsn)
void	preallocateLRUEntries() Forces allocation of the first chunk of entries.
long	removeINFromMain(IN in) Called: - after eviction of an IN from main cache, and in that case storeEvictedBIN was called and the eviction was completed.
void	requestShutdown()
void	setOwner(int entry, IN owner)
void	shutdown()
boolean	storeEvictedBIN(BIN bin, IN parent, int index) Called before eviction of a BIN from main cache to provide an opportunity to store the BIN off-heap.
boolean	storeEvictedLN(BIN bin, int index, LN ln) Called before eviction of an LN from main cache to provide an opportunity to store the LN off-heap.
boolean	storePreloadedBIN(BIN bin, IN parent, int index) Called when a BIN has been fetched from disk and should be stored off-heap.
boolean	storePreloadedLN(BIN bin, int index, LN ln) Called when an LN has been fetched from disk and should be stored off-heap.
long	stripLNs(IN parent, int index)

Methods inherited from class java.lang.Object

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

Field Detail

MIN_MAIN_CACHE_OVERHEAD

public static final long MIN_MAIN_CACHE_OVERHEAD

See Also:

Constant Field Values

Constructor Detail

OffHeapCache

public OffHeapCache(EnvironmentImpl envImpl)

Method Detail

envConfigUpdate

public void envConfigUpdate(DbConfigManager configManager,
                            EnvironmentMutableConfig ignore)

Description copied from interface: EnvConfigObserver

Notifies the observer that one or more mutable properties have been changed.

Specified by:

envConfigUpdate in interface EnvConfigObserver

requestShutdown

public void requestShutdown()

shutdown

public void shutdown()

isEnabled

public boolean isEnabled()

clearCache

public long clearCache(EnvironmentImpl matchEnv)

loadStats

public StatGroup loadStats(StatsConfig config)

getMaxMemory

public long getMaxMemory()

getUsedMemory

public long getUsedMemory()

preallocateLRUEntries

public void preallocateLRUEntries()

Forces allocation of the first chunk of entries. Used by tests that need to more precisely control cache behavior.

getAllocator

public OffHeapAllocator getAllocator()

moveBack

public int moveBack(int entry,
                    boolean pri2)

getMemId

public long getMemId(int entry)

setOwner

public void setOwner(int entry,
                     IN owner)

storeEvictedLN

public boolean storeEvictedLN(BIN bin,
                              int index,
                              LN ln)

Called before eviction of an LN from main cache to provide an opportunity to store the LN off-heap.

storePreloadedLN

public boolean storePreloadedLN(BIN bin,
                                int index,
                                LN ln)

Called when an LN has been fetched from disk and should be stored off-heap.

ensureOffHeapLNsInLRU

public boolean ensureOffHeapLNsInLRU(BIN bin)

loadLN

public LN loadLN(BIN bin,
                 int index,
                 CacheMode cacheMode)

freeRedundantLN

public void freeRedundantLN(BIN bin,
                            int index,
                            LN ln,
                            CacheMode cacheMode)

loadVLSN

public long loadVLSN(BIN bin,
                     int index)

freeLN

public int freeLN(BIN bin,
                  int index)

storeEvictedBIN

public boolean storeEvictedBIN(BIN bin,
                               IN parent,
                               int index)

Called before eviction of a BIN from main cache to provide an opportunity to store the BIN off-heap. removeINFromMain is called after this method by the main evictor. It is removeINFromMain that removes the main BIN's off-heap LRU entry, if it has one. The bin and parent latches are held across the calls to storeEvictedBIN and removeINFromMain. removeINFromMain will also free any off-heap LN IDs in the main BIN, and therefore this method must clear those IDs in the main BIN. When the BIN is stored off-heap by this method, the LN IDs will be stored along with the off-heap BIN.

storePreloadedBIN

public boolean storePreloadedBIN(BIN bin,
                                 IN parent,
                                 int index)

Called when a BIN has been fetched from disk and should be stored off-heap.

removeINFromMain

public long removeINFromMain(IN in)

Called: - after eviction of an IN from main cache, and in that case storeEvictedBIN was called and the eviction was completed. - when an IN is removed from the main cache for another reason, such as a reverse split or Database removal. - for all INs in an Environment being removed from the shared cache.

loadBIN

public BIN loadBIN(EnvironmentImpl envImpl,
                   int entry)

loadBINIfLsnMatches

public BIN loadBINIfLsnMatches(EnvironmentImpl envImpl,
                               int entry,
                               long lsn)

Loads a BIN for the given entry, if its last logged LSN is the given LSN. Can be used to store an entry for a BIN (the off-heap BIN ID) without holding its parent IN latch, and later find out whether that entry still refers to the same BIN. If the BIN was split, the LSN will have changed and null is returned. If the BIN is no longer off-heap, or was moved off-heap and back on, null is also returned. If the BIN is redundantly resident in the main and off-heap caches, the main cache "live" version is returned. Otherwise the BIN is deserialized from the off-heap version and is not "live". When non-null is returned, the returned BIN is latched.

evictBINIfLsnMatch

public void evictBINIfLsnMatch(EnvironmentImpl envImpl,
                               int entry,
                               long lsn)

getBINBytes

public byte[] getBINBytes(IN parent,
                          int index)

haveBINBytesChanged

public boolean haveBINBytesChanged(IN parent,
                                   int index,
                                   byte[] bytes)

Called when a BIN's bytes were obtained holding a shared latch, and then the latch was released and acquired again. We need to determine whether the BIN was changed and moved off-heap again, while unlatched. Currently we just get the bytes again and compare. Possible optimization: Maintain a generation count in the serialized BIN, whose value comes from a global counter that is incremented whenever a BIN is serialized. But would the range of such a counter be large enough to guarantee that wrapping won't be a problem? Certainly the odds are low, but how can we guarantee it won't happen? Another approach is to maintain the counter in the BIN in main cache, so it is a per BIN value.

postBINLoad

public void postBINLoad(IN parent,
                        int index,
                        BIN bin)

freeBIN

public long freeBIN(BIN bin,
                    IN parent,
                    int index)

materializeBIN

public BIN materializeBIN(EnvironmentImpl envImpl,
                          byte[] buf)

createBINLogEntryForCheckpoint

public INLogEntry<BIN> createBINLogEntryForCheckpoint(IN parent,
                                                      int index)

postBINLog

public void postBINLog(IN parent,
                       int index,
                       INLogEntry<BIN> logEntry,
                       long newLsn)

getBINInfo

public OffHeapCache.BINInfo getBINInfo(EnvironmentImpl envImpl,
                                       int entry)

doCriticalEviction

public void doCriticalEviction(boolean backgroundIO)

doDaemonEviction

public void doDaemonEviction(boolean backgroundIO)

doManualEvict

public void doManualEvict()

stripLNs

public long stripLNs(IN parent,
                     int index)

mutateToBINDelta

public long mutateToBINDelta(IN parent,
                             int index)