com.sleepycat.je

Enum CacheMode

java.lang.Object

java.lang.Enum<CacheMode>

com.sleepycat.je.CacheMode

All Implemented Interfaces:

Serializable, Comparable<CacheMode>

public enum CacheMode
extends Enum<CacheMode>

Modes that can be specified for control over caching of records in the JE in-memory cache. When a record is stored or retrieved, the cache mode determines how long the record is subsequently retained in the JE in-memory cache, relative to other records in the cache.

When the cache overflows, JE must evict some records from the cache. By default, JE uses a Least Recently Used (LRU) algorithm for determining which records to evict. With the LRU algorithm, JE makes a best effort to evict the "coldest" (least recently used or accessed) records and to retain the "hottest" records in the cache for as long as possible.

When an off-heap cache is configured, records evicted from the main cache are placed in the off-heap cache, and a separate LRU is used to determine when to evict a record from the off-heap cache.

JE uses an approximate LRU approach with some exceptions and special cases.

• Individual records (LNs or Leaf Nodes) do not appear on the LRU list, i.e., their "hotness" is not explicitly tracked. Instead, their containing Btree node (BIN or bottom internal node) appears on the LRU list. Each BIN contains roughly 100 LNs (see EnvironmentConfig.NODE_MAX_ENTRIES). When an LN is accessed, its BIN is moved to the hot end of the LRU list, implying that all other LNs in the same BIN also are treated as if they are hot. The same applies if the BIN is moved to the cold end of the LRU list. The above statement applies to the off-heap cache also, when one is configured.
• When a BIN contains LNs and the BIN reaches the cold end of the LRU list, if memory can be reclaimed by deleting space for expired LNs or evicting resident LNs, then eviction of the BIN is deferred. The empty BIN is moved to the hot end of the LRU list. When an off-heap cache is configured, the eviction of LNs in this manner occurs independently in both caches.
• When a BIN contains no LNs, it may be evicted entirely. When the BINs parent node becomes empty, it may also be evicted, and so on. The BINs and INs are evicted on the basis of an LRU, but with two exceptions:

  1) Dirty BINs and INs are evicted only after eviction of all non-dirty BINs and INs. This is important to reduce logging and associated cleaning costs. When an off-heap cache is configured, BINs and INs are evicted from the main cache without regard to whether they are dirty. Dirty BINs and INs are evicted last, as just described, only from the off-heap cache.

  2) A BIN may be mutated to a BIN-delta to reclaim memory, rather then being evicted entirely. A BIN-delta contains only the dirty entries (for LNs recently logged). A BIN-delta is used when its size relative to the full BIN will be small enough so that it will be more efficient, both on disk and in memory, to store the delta rather than the full BIN. (see EnvironmentConfig.TREE_BIN_DELTA). The advantage of keeping a BIN-delta in cache is that some operations, particularly record insertions, can be performed using the delta without having the complete BIN in cache. When a BIN is mutated to a BIN-delta to reclaim memory, it is placed at the hot end of the LRU list. When an off-heap cache is configured, BINs are not mutated to BIN-deltas in the main cache, but rather this is done only in the off-heap cache.

• To reduce contention among threads on the LRU list, multiple LRU lists may be configured. See EnvironmentConfig.EVICTOR_N_LRU_LISTS. As described in the javadoc for this parameter, there is a trade-off between thread contention and the accuracy of the LRU. This parameter determines the number of main cache LRU lists as well as the number of off-heap cache LRU lists, when an off-heap cache is configured.
• A non-default cache mode may be explicitly specified to override the LRU behavior. See the CacheMode enumeration values for details. the normal LRU behavior described above. See the CacheMode enumeration values for details. The behavior of each CacheMode when an off-heap cache is configured is also described.

When no cache mode is explicitly specified, the default cache mode is DEFAULT. The default mode causes the normal LRU algorithm to be used.

An explicit cache mode may be specified as an Environment property, a Database property, a Cursor property, or on a per-operation basis using ReadOptions.setCacheMode(CacheMode) or WriteOptions.setCacheMode(CacheMode). If none are specified, DEFAULT is used. If more than one non-null property is specified, the Cursor property overrides the Database and Environment properties, and the Database property overrides the Environment property.

When all records in a given Database, or all Databases, should be treated the same with respect to caching, using the Database and/or Environment cache mode properties is sufficient. For applications that need finer grained control, the Cursor cache mode property can be used to provide a specific cache mode for individual records or operations. The Cursor cache mode property can be changed at any time, and the cache mode specified will apply to subsequent operations performed with that Cursor.

In a Replicated Environment where a non-default cache mode is desired, the cache mode can be configured on the Master node as described above. However, it is important to configure the cache mode on the Replica nodes using an Environment property. That way, the cache mode will apply to write operations that are replayed on the Replica for all Databases, even if the Databases are not open by the application on the Replica. Since all nodes may be Replicas at some point in their life cycle, it is recommended to configure the desired cache mode as an Environment property on all nodes in a Replicated Environment.

On a Replica, per-Database control over the cache mode for write operations is possible by opening the Database on the Replica and configuring the cache mode. Per-Cursor control (meaning per-record or per-operation) control of the cache mode is not possible on a Replica for write operations. For read operations, both per-Database and per-Cursor control is possible on the Replica, as described above.

The cache related stats in EnvironmentStats can provide some measure of the effectiveness of the cache mode choice.

See Also:

Cache Statistics: Sizing

Enum Constant Summary

Enum Constants

Enum Constant and Description
DEFAULT The record's hotness is changed to "most recently used" by the operation.
DYNAMIC
EVICT_BIN The record's BIN (and its LNs) are evicted after the operation.
EVICT_LN The record's LN is evicted after the operation, and the containing BIN is moved to the hot end of the LRU list.
KEEP_HOT Deprecated. please use DEFAULT instead. As of JE 4.0, this mode functions exactly as if DEFAULT were specified.
MAKE_COLD Deprecated. please use UNCHANGED instead. As of JE 4.0, this mode functions exactly as if UNCHANGED were specified.
UNCHANGED The record's hotness or coldness is unchanged by the operation where this cache mode is specified.

Method Summary

Modifier and Type	Method and Description
static CacheMode	valueOf(String name) Returns the enum constant of this type with the specified name.
static CacheMode[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

DEFAULT

public static final CacheMode DEFAULT

The record's hotness is changed to "most recently used" by the operation.

This cache mode is used when the application does not need explicit control over the cache and a standard LRU approach is sufficient.

Note that null may be specified to use the DEFAULT mode.

Specifically:

• The BIN containing the record's LN will remain in the main cache, and it is moved to the hot end of its LRU list.
• When an off-heap cache is configured, the record's LN and BIN will be loaded into the main cache only. They will be removed from the off-heap cache, if they were present there. However, if other LNs belonging to this BIN were present in the off-heap cache, they will remain there.

KEEP_HOT

public static final CacheMode KEEP_HOT

Deprecated. please use DEFAULT instead. As of JE 4.0, this mode functions exactly as if DEFAULT were specified.

UNCHANGED

public static final CacheMode UNCHANGED

The record's hotness or coldness is unchanged by the operation where this cache mode is specified.

This cache mode is normally used when the application prefers that the operation should not perturb the cache, for example, when scanning over all records in a database.

Specifically:

• A record's LN and BIN must be loaded into the main cache in order to perform the operation. However, they may be removed from the main cache after the operation, to avoid a net change to the cache, according to the rules below.
• If the record's LN was not present in the main cache prior to the operation, then the LN will be evicted from the main cache after the operation. The LN will not be added to, or removed from, the off-heap cache.
• When the LN is to be evicted from the main cache (according to the above rules) and the operation is not performed via a cursor, the LN is evicted when the operation is complete. When a cursor is used, the LN is evicted when the cursor is moved to a different record or closed.
• If the record's BIN was not present in the main cache prior to the operation, the action taken depends on whether the BIN is dirty and whether an off-heap cache is configured.
  • When the BIN is not dirty, the BIN (and LN) will be evicted from the main cache after the operation. The BIN (and LN) will not be added to, or removed from, the off-heap cache.
  • When the BIN is dirty and an off-heap cache is not configured, the BIN will not be evicted from the main cache and will be moved to the hot end of its main cache LRU list. This is done to reduce logging.
  • When the BIN is dirty and an off-heap cache is configured, we evict the BIN from the main cache even when it is dirty because the BIN (and LN) will be stored in the off-heap cache and the BIN will not be logged. The BIN will be placed at the hot end of its off-heap LRU list.
  • Note that when this operation loaded the BIN and the BIN becomes dirty, it is normally because this operation is a write operation. However, other concurrent threads can also dirty the BIN.
• When the BIN is to be evicted from the main cache (according to the above rules) and the operation is not performed via a cursor, the BIN is evicted when the operation is complete. When a cursor is used, the BIN is evicted only when the cursor moves to a different BIN or is closed. Because of the way BINs are evicted, when multiple operations are performed using a single cursor and not perturbing the cache is desired, it is important to use this cache mode for all of the operations.
• When the BIN was present in the main cache prior to the operation, its position in the LRU list will not be changed. Its position in the off-heap LRU list, if it is present in the off-heap cache, will also not be changed.

MAKE_COLD

public static final CacheMode MAKE_COLD

Deprecated. please use UNCHANGED instead. As of JE 4.0, this mode functions exactly as if UNCHANGED were specified.

EVICT_LN

public static final CacheMode EVICT_LN

The record's LN is evicted after the operation, and the containing BIN is moved to the hot end of the LRU list.

This cache mode is normally used when not all LNs will fit into the main cache, and the application prefers to read the LN from the log file or load it from the off-heap cache when the record is accessed again, rather than have it take up space in the main cache and potentially cause expensive Java GC. By using this mode, the file system cache or off-heap cache can be relied on for holding LNs, which complements the use of the JE cache to hold BINs and INs.

Note that using this mode for all operations will prevent the cache from filling, if all internal nodes fit in cache.

Specifically:

• The record's LN will be evicted from the main cache after the operation. The LN will be added to the off-heap cache, if it is not already present and an off-heap cache is configured.
• When the operation is not performed via a cursor, the LN is evicted when the operation is complete. When a cursor is used, the LN is evicted when the cursor is moved to a different record or closed.

Since:

3.3.98

EVICT_BIN

public static final CacheMode EVICT_BIN

The record's BIN (and its LNs) are evicted after the operation.

This cache mode is normally used when not all BINs will fit into the main cache, and the application prefers to read the LN and BIN from the log file or load it from the off-heap cache when the record is accessed again, rather than have them take up space in the JE cache and potentially cause expensive Java GC.

Because this mode evicts all LNs in the BIN, even if they are "hot" from the perspective of a different accessor, this mode should be used with caution. One valid use case is where all accessors use this mode; in this case the cache mode might be set on a per-Database or per-Environment basis.

Note that using this mode for all operations will prevent the cache from filling, if all upper internal nodes fit in cache.

Specifically:

• The record's LN will be evicted from the main cache after the operation. The LN will be added to the off-heap cache, if it is not already present and an off-heap cache is configured.
• When the operation is not performed via a cursor, the LN is evicted when the operation is complete. When a cursor is used, the LN is evicted when the cursor is moved to a different record or closed.
• Whether the BIN is evicted depends on whether the BIN is dirty and whether an off-heap cache is configured.
  • When the BIN is not dirty, the BIN (and LN) will be evicted from the main cache after the operation. The BIN (and LN) will be added to the off-heap cache, if they are not already present and an off-heap cache is configured. The BIN will be placed at the hot end of its off-heap LRU list.
  • When the BIN is dirty and an off-heap cache is not configured, the BIN will not be evicted from the main cache and will be moved to the hot end of its main cache LRU list. This is done to reduce logging.
  • When the BIN is dirty and an off-heap cache is configured, we evict the BIN from the main cache even when it is dirty because the BIN (and LN) will be stored in the off-heap cache and the BIN will not be logged. The BIN will be placed at the hot end of its off-heap LRU list.
  • Note that BIN may have been dirtied by this operation, if it is a write operation, or by earlier write operations.
• When the BIN is to be evicted from the main cache (according to the above rules) and the operation is not performed via a cursor, the BIN is evicted when the operation is complete. When a cursor is used, the BIN is evicted only when the cursor moves to a different BIN or is closed. Because of the way BINs are evicted, when multiple operations are performed using a single cursor and not perturbing the cache is desired, it is important to use this cache mode for all of the operations.

Since:

4.0.97

DYNAMIC

public static final CacheMode DYNAMIC

Since:

4.0.97

Method Detail

values

public static CacheMode[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (CacheMode c : CacheMode.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static CacheMode valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null