All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.gemstone.gemfire.cache.EvictionAttributes Maven / Gradle / Ivy

There is a newer version: 2.0-BETA
Show newest version
/*
 * Copyright (c) 2010-2015 Pivotal Software, Inc. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you
 * may not use this file except in compliance with the License. You
 * may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * permissions and limitations under the License. See accompanying
 * LICENSE file.
 */

package com.gemstone.gemfire.cache;

import com.gemstone.gemfire.DataSerializable;
import com.gemstone.gemfire.cache.control.ResourceManager;
import com.gemstone.gemfire.cache.util.ObjectSizer;
import com.gemstone.gemfire.internal.cache.EvictionAttributesImpl;
import com.gemstone.gemfire.internal.cache.lru.HeapLRUCapacityController;
import com.gemstone.gemfire.internal.cache.lru.LRUCapacityController;
import com.gemstone.gemfire.internal.cache.lru.MemLRUCapacityController;

/**
 * 

Attributes that describe how a Region's size is managed through an eviction controller. Eviction * controllers are defined by an {@link com.gemstone.gemfire.cache.EvictionAlgorithm} and a {@link * com.gemstone.gemfire.cache.EvictionAction}. Once a Region is created with an eviction controller, it can * not be removed, however it can be changed through an {@link com.gemstone.gemfire.cache.EvictionAttributesMutator}. * * @author Mitch Thomas * @see com.gemstone.gemfire.cache.AttributesFactory#setEvictionAttributes(EvictionAttributes) * @see com.gemstone.gemfire.cache.AttributesMutator * @since 5.0 */ public abstract class EvictionAttributes implements DataSerializable { /** *

* Creates the {@link EvictionAttributes} for an eviction controller that will remove the least recently used (LRU) * entry from a region once the region reaches a certain capacity. The entry is either locally destroyed or overflows * to disk when evicted by the eviction controller. *

*

* This is not supported when replication is enabled. *

*

* For a region with {@link DataPolicy#PARTITION}, the EvictionAttribute maximum, indicates number of * entries allowed in the region, collectively for its primary buckets and redundant copies for this VM. Once there * are maximum entries in the region's primary buckets and redundant copies for this VM, the least * recently used entry will be evicted from the bucket in which the subsequent put takes place. *

*

* If you are using a cache.xml file to create a Cache Region declaratively, you can include the * following to create an LRU entry eviction controller *

*

   *         <region-attributes>
   *            <eviction-attributes>
   *               <lru-entry-count maximum="1000" action="overflow-to-disk"/>
   *            </eviction-attributes>
   *         </region-attributes>
   * 
* * @return a new EvictionAttributes instance */ public static EvictionAttributes createLRUEntryAttributes() { return new EvictionAttributesImpl().setAlgorithm( EvictionAlgorithm.LRU_ENTRY).setAction( EvictionAction.DEFAULT_EVICTION_ACTION).internalSetMaximum( LRUCapacityController.DEFAULT_MAXIMUM_ENTRIES); } /** * Create attributes to remove the least recently used entries when the maximum number of entries exists in the * Region * * @param maximumEntries the number of entries to keep in the Region * @return a new EvictionAttributes instance * @see #createLRUEntryAttributes() */ public static EvictionAttributes createLRUEntryAttributes(int maximumEntries) { return new EvictionAttributesImpl().setAlgorithm(EvictionAlgorithm.LRU_ENTRY).setAction( EvictionAction.DEFAULT_EVICTION_ACTION).internalSetMaximum(maximumEntries); } /** * Create attributes to perform the given action when the maximum number of entries exists in the Region * * @return a new EvictionAttributes * @see #createLRUEntryAttributes() */ public static EvictionAttributes createLRUEntryAttributes(int maximumEntries, EvictionAction evictionAction) { return new EvictionAttributesImpl().setAlgorithm(EvictionAlgorithm.LRU_ENTRY).setAction(evictionAction) .internalSetMaximum(maximumEntries); } /** *

* Create EvictionAttributes for evicting the least recently used {@link Region.Entry} when heap usage exceeds the * {@link ResourceManager} eviction heap threshold. If the eviction heap threshold is exceeded the least recently used * {@link Region.Entry}s are evicted. *

*

* With other LRU-based eviction controllers, only cache actions (such as {@link Region#put(Object, Object) puts} and * {@link Region#get(Object) gets}) cause the LRU entry to be evicted. However, because the JVM's heap may be effected * by more than just the GemFire cache operations, a daemon thread will perform the eviction in the event threads are * not using the Region. *

*

* When using Heap LRU, the VM must be launched with the -Xmx and -Xms switches set to the * same values. Many virtual machine implementations have additional VM switches to control the behavior of the * garbage collector. We suggest that you investigate tuning the garbage collector when using this type of eviction * controller. A collector that frequently collects is needed to keep our heap usage up to date. In particular, on * the Sun HotSpot VM, the * -XX:+UseConcMarkSweepGC flag needs to be set, and -XX:CMSInitiatingOccupancyFraction=N * should be set with N being a percentage that is less than the {@link ResourceManager} eviction heap threshold. *

* The JRockit VM has similar flags, -Xgc:gencon and -XXgcTrigger:N, which are required if * using this LRU algorithm. Please Note: the JRockit gcTrigger flag is based on heap free, not heap in use like the * GemFire parameter. This means you need to set gcTrigger to 100-N. for example, if your eviction threshold is 30 * percent, you will need to set gcTrigger to 70 percent. *

* On the IBM VM, the flag to get a similar collector is -Xgcpolicy:gencon, but there is no corollary to * the gcTrigger/CMSInitiatingOccupancyFraction flags, so when using this feature with an IBM VM, the heap usage * statistics might lag the true memory usage of the VM, and thresholds may need to be set sufficiently high that the * VM will initiate GC before the thresholds are crossed. *

* If you are using a cache.xml file to create a Cache Region declaratively, you can include the * following to create an LRU heap eviction controller: *

*

   *         <region-attributes>
   *            <eviction-attributes>
   *               <lru-heap-percentage action="overflow-to-disk"
   *            </eviction-attributes>
   *         </region-attributes>
   * 
*

* *

This is equivalent to calling createLRUHeapAttributes({@link ObjectSizer#DEFAULT}) * * @return a new EvictionAttributes instance with {@link EvictionAlgorithm#LRU_HEAP} and the default heap percentage, * eviction interval and eviction action. */ public static EvictionAttributes createLRUHeapAttributes() { return new EvictionAttributesImpl() .setAlgorithm(EvictionAlgorithm.LRU_HEAP) .setAction(EvictionAction.DEFAULT_EVICTION_ACTION) // TODO HEAPLRUAPI remove perRegion Heap maximum, use cache .internalSetMaximum(HeapLRUCapacityController.DEFAULT_HEAP_PERCENTAGE) .setObjectSizer(ObjectSizer.DEFAULT); } /** * Creates EvictionAttributes for evicting the least recently used {@link Region.Entry} when heap usage exceeds the * {@link ResourceManager} critical heap threshold. * * @param sizer the sizer implementation used to determine how many entries to remove * @return a new instance of EvictionAttributes with {@link EvictionAlgorithm#LRU_HEAP} and the provided object sizer * and eviction action. * @see #createLRUHeapAttributes() */ public static EvictionAttributes createLRUHeapAttributes(final ObjectSizer sizer) { return new EvictionAttributesImpl() .setAlgorithm(EvictionAlgorithm.LRU_HEAP) .setAction(EvictionAction.DEFAULT_EVICTION_ACTION) .internalSetMaximum(HeapLRUCapacityController.DEFAULT_HEAP_PERCENTAGE) .setObjectSizer(sizer); } /** * Creates EvictionAttributes for evicting the least recently used {@link Region.Entry} when heap usage exceeds the * {@link ResourceManager} critical heap threshold. * * @param sizer the sizer implementation used to determine how many entries to remove * @param evictionAction the way in which entries should be evicted * @return a new instance of EvictionAttributes with {@link EvictionAlgorithm#LRU_HEAP} and the provided object sizer * and eviction action. * @see #createLRUHeapAttributes() */ public static EvictionAttributes createLRUHeapAttributes(final ObjectSizer sizer, final EvictionAction evictionAction) { return new EvictionAttributesImpl() .setAlgorithm(EvictionAlgorithm.LRU_HEAP) .setAction(evictionAction) .internalSetMaximum(HeapLRUCapacityController.DEFAULT_HEAP_PERCENTAGE) .setObjectSizer(sizer); } /** * Creates EvictionAttributes for an eviction controller that will remove the least recently used (LRU) entry from a * region once the region reaches a certain byte capacity. Capacity is determined by monitoring the size of entries * added and evicted. Capacity is specified in terms of megabytes. GemFire uses an efficient algorithm to determine * the amount of space a region entry occupies in the VM. However, this algorithm may not yield optimal results for * all kinds of data. The user may provide his or her own algorithm for determining the size of objects by * implementing an {@link ObjectSizer}. *

*

* For a region with {@link DataPolicy#PARTITION}, the EvictionAttribute maximum, is always equal to * {@link PartitionAttributesFactory#setLocalMaxMemory(int) " local max memory "} specified for the {@link * PartitionAttributes}. It signifies the amount of memory allowed in the region, collectively for its primary buckets * and redundant copies for this VM. It can be different for the same region in different VMs. *

* If you are using a cache.xml file to create a Cache Region declaratively, you can include the * following to create an LRU memory eviction controller: *

*

   *          <region-attributes>
   *            <eviction-attributes>
   *               <lru-memory-size maximum="1000" action="overflow-to-disk">
   *                  <class-name>com.foo.MySizer</class-name>
   *                  <parameter name="name">
   *                     <string>Super Sizer</string>
   *                  </parameter>
   *               </lru-memory-size>
   *            </eviction-attributes>
   *         </region-attributes>
   * 
* * @return a new EvictionAttributes */ public static EvictionAttributes createLRUMemoryAttributes() { return new EvictionAttributesImpl().setAlgorithm(EvictionAlgorithm.LRU_MEMORY).setAction( EvictionAction.DEFAULT_EVICTION_ACTION).internalSetMaximum(MemLRUCapacityController.DEFAULT_MAXIMUM_MEGABYTES) .setObjectSizer(ObjectSizer.DEFAULT); } /** * Creates EvictionAttributes for an eviction controller that will remove the least recently used (LRU) entry from a * region once the region reaches the given maximum capacity. *

*

* For a region with {@link DataPolicy#PARTITION}, even if maximumMegabytes are supplied, the EvictionAttribute * maximum, is always set to {@link PartitionAttributesFactory#setLocalMaxMemory(int) " local max memory * "} specified for the {@link PartitionAttributes}. *

* This is equivalent to calling createLRUMemoryAttributes(maximumMegabytes, {@link ObjectSizer#DEFAULT}) * * * @param maximumMegabytes the maximum allowed bytes in the Region * @return a new EvictionAttributes * @see #createLRUMemoryAttributes() */ public static EvictionAttributes createLRUMemoryAttributes(int maximumMegabytes) { return new EvictionAttributesImpl().setAlgorithm(EvictionAlgorithm.LRU_MEMORY).setAction( EvictionAction.DEFAULT_EVICTION_ACTION).internalSetMaximum(maximumMegabytes).setObjectSizer(null); } /** * Creates EvictionAttributes for an eviction controller that will remove the least recently used (LRU) entry from a * region once the region reaches the given maximum capacity. *

*

For a region with {@link DataPolicy#PARTITION}, even if maximumMegabytes are supplied, the EvictionAttribute * maximum, is always set to {@link PartitionAttributesFactory#setLocalMaxMemory(int) " local max * memory "} specified for the {@link PartitionAttributes}. * * @param maximumMegabytes the maximum allowed bytes in the Region * @param sizer calculates the size in bytes of the key and value for an entry. * @return a new EvictionAttributes * @see #createLRUMemoryAttributes() */ public static EvictionAttributes createLRUMemoryAttributes(int maximumMegabytes, ObjectSizer sizer) { return new EvictionAttributesImpl().setAlgorithm(EvictionAlgorithm.LRU_MEMORY).setAction( EvictionAction.DEFAULT_EVICTION_ACTION).internalSetMaximum(maximumMegabytes).setObjectSizer(sizer); } /** * Creates EvictionAttributes for an eviction controller that will remove the least recently used (LRU) entry from a * region once the region reaches the given maximum capacity. *

*

For a region with {@link DataPolicy#PARTITION}, even if maximumMegabytes are supplied, the EvictionAttribute * maximum, is always set to {@link PartitionAttributesFactory#setLocalMaxMemory(int) " local max * memory "} specified for the {@link PartitionAttributes}. * * @param maximumMegabytes the maximum allowed bytes in the Region * @param sizer calculates the size in bytes of the key and value for an entry. * @param evictionAction the action to take when the maximum has been reached. * @return a new EvictionAttributes instance * @see #createLRUMemoryAttributes() */ public static EvictionAttributes createLRUMemoryAttributes(int maximumMegabytes, ObjectSizer sizer, EvictionAction evictionAction) { return new EvictionAttributesImpl().setAlgorithm(EvictionAlgorithm.LRU_MEMORY).setAction(evictionAction) .internalSetMaximum(maximumMegabytes).setObjectSizer(sizer); } /** * Creates EvictionAttributes for an eviction controller that will remove the least recently used (LRU) entry from a * region once the region reaches the given maximum capacity. *

*

For a region with {@link DataPolicy#PARTITION}, even if maximumMegabytes are supplied, the EvictionAttribute * maximum, is always set to {@link PartitionAttributesFactory#setLocalMaxMemory(int) " local max * memory "} specified for the {@link PartitionAttributes}. * * @param sizer calculates the size in bytes of the key and value for an entry. * @return a new EvictionAttributes instance * @see #createLRUMemoryAttributes() * @since 6.0 */ public static EvictionAttributes createLRUMemoryAttributes(ObjectSizer sizer) { return new EvictionAttributesImpl().setAlgorithm(EvictionAlgorithm.LRU_MEMORY).setAction( EvictionAction.DEFAULT_EVICTION_ACTION).setObjectSizer(sizer).internalSetMaximum( MemLRUCapacityController.DEFAULT_MAXIMUM_MEGABYTES); } /** * Creates EvictionAttributes for an eviction controller that will remove the least recently used (LRU) entry from a * region once the region reaches the given maximum capacity. *

*

For a region with {@link DataPolicy#PARTITION}, even if maximumMegabytes are supplied, the EvictionAttribute * maximum, is always set to {@link PartitionAttributesFactory#setLocalMaxMemory(int) " local max * memory "} specified for the {@link PartitionAttributes}. * * @param sizer calculates the size in bytes of the key and value for an entry. * @param evictionAction the action to take when the maximum has been reached. * @return a new EvictionAttributes instance * @see #createLRUMemoryAttributes() * @since 6.0 */ public static EvictionAttributes createLRUMemoryAttributes(ObjectSizer sizer, EvictionAction evictionAction) { return new EvictionAttributesImpl().setAlgorithm(EvictionAlgorithm.LRU_MEMORY).setAction(evictionAction) .setObjectSizer(sizer).internalSetMaximum(MemLRUCapacityController.DEFAULT_MAXIMUM_MEGABYTES); } /** * An {@link ObjectSizer} is used by the {@link EvictionAlgorithm#LRU_MEMORY} algorithm to measure the size of each * Entry as it is entered into a Region. A default implementation is provided, see {@link * #createLRUMemoryAttributes()} for more. * * @return the sizer used by {@link EvictionAlgorithm#LRU_MEMORY}, for all algorithms null is returned. */ public abstract ObjectSizer getObjectSizer(); /** * The algorithm is used to identify entries that will be evicited. * * @return a non-null EvictionAlgorithm instance reflecting the configured value or NONE when no eviction controller * has been configured. */ public abstract EvictionAlgorithm getAlgorithm(); /** * The unit of this value is determined by the definition of the {@link EvictionAlgorithm} set by one of the creation * methods e.g. {@link EvictionAttributes#createLRUEntryAttributes()} * * @return maximum value used by the {@link EvictionAlgorithm} which determines when the {@link EvictionAction} is * performed. */ public abstract int getMaximum(); /** @return action that the {@link EvictionAlgorithm} takes when the maximum value is reached. */ public abstract EvictionAction getAction(); @Override public final boolean equals(final Object obj) { if (obj == this) { return true; } if (!(obj instanceof EvictionAttributes)) { return false; } final EvictionAttributes other = (EvictionAttributes) obj; if (!this.getAlgorithm().equals(other.getAlgorithm()) || !this.getAction().equals(other.getAction())) { return false; } // LRUHeap doesn't support maximum if (!this.getAlgorithm().isLRUHeap() && this.getMaximum() != other.getMaximum()) { return false; } return true; } @Override public final int hashCode() { return this.getAlgorithm().hashCode() ^ this.getMaximum(); } @Override public String toString() { final StringBuilder buffer = new StringBuilder(128); buffer.append(" algorithm=").append(this.getAlgorithm()); if (!this.getAlgorithm().isNone()) { buffer.append("; action=").append(this.getAction()); if (!getAlgorithm().isLRUHeap()) { buffer.append("; maximum=").append(this.getMaximum()); } if (this.getObjectSizer() != null) { buffer.append("; sizer=").append(this.getObjectSizer()); } } return buffer.toString(); } /** * @return an EvictionAttributes for the LIFOCapacityController * @since 5.7 */ public static EvictionAttributes createLIFOEntryAttributes(int maximumEntries, EvictionAction evictionAction) { return new EvictionAttributesImpl().setAlgorithm(EvictionAlgorithm.LIFO_ENTRY).setAction(evictionAction) .internalSetMaximum(maximumEntries); } /** * @return an EvictionAttributes for the MemLIFOCapacityController * @since 5.7 */ public static EvictionAttributes createLIFOMemoryAttributes(int maximumMegabytes, EvictionAction evictionAction) { return new EvictionAttributesImpl().setAlgorithm(EvictionAlgorithm.LIFO_MEMORY).setAction(evictionAction) .internalSetMaximum(maximumMegabytes).setObjectSizer(null); } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy