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.

Note that JE makes a best effort to implement an approximation of an LRU algorithm, and the very coldest record is not always evicted from the cache first. In addition, hotness and coldness are applied to the portion of the in-memory BTree that is accessed to perform the operation, not just to the record itself.

A non-default cache mode may be explicitly specified to override the default behavior of the LRU algorithm. 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, or a Cursor property. 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.

Enum Constant Summary

DEFAULT
The record's hotness is changed to "most recently used" by the operation where this cache mode is specified.

EVICT_BIN
The record LN (leaf node) and its parent BIN (bottom internal node) are evicted as soon as possible after the operation where this cache mode is specified.

EVICT_LN
The record LN (leaf node) is evicted as soon as possible after the operation where this cache mode is specified.

KEEP_HOT
The record is assigned "maximum hotness" by the operation where this cache mode is specified.

MAKE_COLD
The record is assigned "maximum coldness" by the operation where this cache mode is specified.

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

Method Summary

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 where this cache mode is specified.

The record will always be colder than other records accessed with a KEEP_HOT cache mode, and hotter than other records accessed with a MAKE_COLD cache mode. Among records accessed with the DEFAULT cache mode, the record will be hotter than other records accessed at an earlier time and colder then other records accessed at a later time.

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

KEEP_HOT

public static final CacheMode KEEP_HOT

The record is assigned "maximum hotness" by the operation where this cache mode is specified.

The record will have the same hotness as other records accessed with this cache mode. Its relative hotness will not be reduced over time as other records are accessed. It can only become colder over time if it is subsequently accessed with the DEFAULT or MAKE_COLD cache mode.

This cache mode is normally used when the application intends to access this record again soon.

UNCHANGED

public static final CacheMode UNCHANGED

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

If the record was present in the cache prior to this operation, then its pre-existing hotness or coldness will not be changed. If the record was added to the cache by this operation, it will have "maximum coldness" and will therefore be colder than other records.

This cache mode is normally used when the application prefers that the record be evicted from the cache when space is needed, but only if the record has not been accessed using DEFAULT or KEEP_HOT recently.

MAKE_COLD

public static final CacheMode MAKE_COLD

The record is assigned "maximum coldness" by the operation where this cache mode is specified. When the JE cache is full, operations using this cache mode will opportunistically perform explicit eviction of the the record LN (leaf node) and/or its parent BIN (bottom internal node).

If the record is not evicted (because the JE cache is not full), the record will have the same hotness as other records accessed with this cache mode. It is very likely that this record will be evicted from the cache when the cache fills. It can only become warmer over time if it is subsequently accessed with the DEFAULT or KEEP_HOT cache mode.

This cache mode is normally used when the application prefers that the record be evicted from the cache when space is needed, regardless of whether the record has been accessed using DEFAULT or KEEP_HOT recently.

A potential advantage of this cache mode is that blocking between threads may be reduced when eviction is a dominant performance factor. Blocking during eviction is uncommon but can occur if many threads are evicting concurrently.

Since:

3.3.98

EVICT_LN

public static final CacheMode EVICT_LN

The record LN (leaf node) is evicted as soon as possible after the operation where this cache mode is specified. The parent BIN (bottom internal node) for the record is assigned "maximum coldness" as if MAKE_COLD were used.

When a cursor is used, the LN is evicted only when the cursor is moved to a different record or is closed.

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

A potential advantage of this cache mode is that blocking between threads may be reduced when eviction is a dominant performance factor. Blocking during eviction is uncommon but can occur if many threads are evicting concurrently.

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

Since:

3.3.98

EVICT_BIN

public static final CacheMode EVICT_BIN

The record LN (leaf node) and its parent BIN (bottom internal node) are evicted as soon as possible after the operation where this cache mode is specified. Note that when the BIN is evicted, all record LNs (leaf nodes) in that BIN are also evicted. If the BIN cannot be evicted immediately, it is assigned "maximum coldness" as if MAKE_COLD were used.

When a cursor is used, the LN is evicted when the cursor is moved to a different record or is closed. The BIN is evicted when the cursor moves to a different BIN or is closed.

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

A potential advantage of this cache mode is that blocking between threads may be reduced when eviction is a dominant performance factor. Blocking during eviction is uncommon but can occur if many threads are evicting concurrently.

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

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