com.sleepycat.je.CacheMode Maven / Gradle / Ivy
/*-
* Copyright (C) 2002, 2018, Oracle and/or its affiliates. All rights reserved.
*
* This file was distributed by Oracle as part of a version of Oracle Berkeley
* DB Java Edition made available at:
*
* http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index.html
*
* Please see the LICENSE file included in the top-level directory of the
* appropriate version of Oracle Berkeley DB Java Edition for a copy of the
* license and additional information.
*/
package com.sleepycat.je;
/**
* 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 {@link EnvironmentMutableConfig#setOffHeapCacheSize 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 {@link com.sleepycat.je.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 {@link com.sleepycat.je.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
* {@link com.sleepycat.je.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
* {@link #DEFAULT}. The default mode causes the normal LRU algorithm to be
* used.
*
* An explicit cache mode may be specified as an {@link
* EnvironmentConfig#setCacheMode Environment property}, a {@link
* DatabaseConfig#setCacheMode Database property}, a {@link
* Cursor#setCacheMode Cursor property}, or on a per-operation basis using
* {@link ReadOptions#setCacheMode(CacheMode)} or {@link
* WriteOptions#setCacheMode(CacheMode)}. If none are specified, {@link
* #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 {@link EnvironmentStats} can provide some measure
* of the effectiveness of the cache mode choice.
*
* @see Cache Statistics:
* Sizing
*/
public enum CacheMode {
/**
* 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 {@code null} may be specified to use the {@code 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.
*
*/
DEFAULT,
/**
* @deprecated please use {@link #DEFAULT} instead. As of JE 4.0, this mode
* functions exactly as if {@link #DEFAULT} were specified.
*/
KEEP_HOT,
/**
* 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.
*
*/
UNCHANGED,
/**
* @deprecated please use {@link #UNCHANGED} instead. As of JE 4.0, this
* mode functions exactly as if {@link #UNCHANGED} were specified.
*/
MAKE_COLD,
/**
* 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_LN,
/**
* 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
*/
EVICT_BIN,
/**
* @hidden
* For internal use only.
* Placeholder to avoid DPL class evolution errors. Never actually used.
* @since 4.0.97
*/
DYNAMIC
}