public enum CacheMode extends java.lang.Enum<CacheMode>
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.
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.
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.
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.
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.
Enum Constant and Description |
---|
DEFAULT
The record's hotness is changed to "most recently used" by the
operation.
|
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
|
MAKE_COLD
|
UNCHANGED
The record's hotness or coldness is unchanged by the operation where
this cache mode is specified.
|
Modifier and Type | Method and Description |
---|---|
static CacheMode |
valueOf(java.lang.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.
|
public static final CacheMode DEFAULT
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:
public static final CacheMode KEEP_HOT
public static final CacheMode UNCHANGED
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:
public static final CacheMode MAKE_COLD
public static final CacheMode EVICT_LN
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:
public static final CacheMode EVICT_BIN
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:
public static CacheMode[] values()
for (CacheMode c : CacheMode.values()) System.out.println(c);
public static CacheMode valueOf(java.lang.String name)
name
- the name of the enum constant to be returned.java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is nullCopyright (c) 2002, 2017 Oracle and/or its affiliates. All rights reserved.