com.gemstone.gemfire.cache.control.ResourceManager Maven / Gradle / Ivy
Show all versions of gemfire-core Show documentation
/*
* 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.control;
import java.util.Set;
import com.gemstone.gemfire.cache.Cache;
import com.gemstone.gemfire.cache.EvictionAttributes;
import com.gemstone.gemfire.cache.LowMemoryException;
import com.gemstone.gemfire.cache.Region;
import com.gemstone.gemfire.cache.execute.Function;
import com.gemstone.gemfire.cache.query.QueryService;
/**
* Provides support for managing resources used by the local
* {@link com.gemstone.gemfire.cache GemFire Cache}.
*
* Re-balancing the GemFire Cache resources can be accomplished using a {@link
* RebalanceOperation}:
*
* ResourceManager resourceManager = cache.getResourceManager();
* RebalanceOperation rebalanceOp = resourceManager.createRebalanceFactory().start();
*
* Monitoring of heap utilization is enabled by setting the critical heap
* percentage using {@link #setCriticalHeapPercentage(float)}.
*
* @since 6.0
*/
public interface ResourceManager {
/**
* The default percent of heap memory at which the VM is considered in a
* critical state. Current value is 0.0.
*
* @see ResourceManager#setCriticalHeapPercentage(float)
* @see ResourceManager#getCriticalHeapPercentage()
*/
public static final float DEFAULT_CRITICAL_PERCENTAGE = 0.0f;
/**
* The default percent of heap memory at which the VM should begin evicting
* data. Current value is 0.0.
* Note that if a HeapLRU is created and the eviction heap percentage has not
* been set then it will default 80.0 unless the critical heap percentage
* has been set in which case it will default to a value 5.0 less than
* the critical heap percentage.
*
* @see ResourceManager#setEvictionHeapPercentage(float)
* @see ResourceManager#getEvictionHeapPercentage()
*/
public static final float DEFAULT_EVICTION_PERCENTAGE = 0.0f;
/**
* System property to set the percent to evict after critical heap percentage
* is breached.
*/
public static final String THRESHOLD_THICKNESS_PROP =
"gemfire.thresholdThickness";
/**
* System property to set the percent to evict after eviction heap percentage
* is breached. If not set then this defaults to the value set by
* {@link #THRESHOLD_THICKNESS_PROP}.
*/
public static final String THRESHOLD_THICKNESS_EVICT_PROP =
"gemfire.eviction-thresholdThickness";
/**
* System property to set the percentage of heap evicted by an evictor thread
* in one burst when the eviction heap percentage is breached.
*/
public static final String EVICTION_BURST_PERCENT_PROP =
"gemfire.HeapLRUCapacityController.evictionBurstPercentage";
/**
* Creates a factory for defining and starting {@link RebalanceOperation
* RebalanceOperations}.
*
* @return a factory for defining and starting RebalanceOperations
*/
public RebalanceFactory createRebalanceFactory();
/**
* Returns a set of all active {@link RebalanceOperation
* RebalanceOperations} that were started locally on this member.
*
* @return a set of all active RebalanceOperations started locally
*/
public Set getRebalanceOperations();
/**
* Set the percentage of heap at or above which the cache is considered in
* danger of becoming inoperable due to garbage collection pauses or out of
* memory exceptions.
*
*
* Changing this value can cause {@link LowMemoryException} to be thrown from
* the following {@link Cache} operations:
*
* - {@link Region#put(Object, Object)}
*
- {@link Region#put(Object, Object, Object)}
*
- {@link Region#create(Object, Object)}
*
- {@link Region#create(Object, Object, Object)}
*
- {@link Region#putAll(java.util.Map)}
*
- {@linkplain QueryService#createIndex(String, com.gemstone.gemfire.cache.query.IndexType, String, String) index creation}
*
- Execution of {@link Function}s whose {@link Function#optimizeForWrite()} returns true.
*
*
*
* Only one change to this attribute or the eviction heap percentage will be
* allowed at any given time and its effect will be fully realized before the
* next change is allowed.
*
* When using this threshold, 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} critical and eviction heap thresholds.
*
* The JRockit VM has similar flags, -Xgc:gencon and -XXgcTrigger:N, which are
* required if using this feature. 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.
*
* @param heapPercentage a percentage of the maximum tenured heap for the VM
* @throws IllegalStateException if the heapPercentage value is not >= 0 or
* <= 100 or when less than the current eviction heap percentage
* @see #getCriticalHeapPercentage()
* @see #getEvictionHeapPercentage()
* @since 6.0
*/
public void setCriticalHeapPercentage(float heapPercentage);
/**
* Get the percentage of heap at or above which the cache is considered in
* danger of becoming inoperable.
*
* @return either the current or recently used percentage of the maximum
* tenured heap
* @see #setCriticalHeapPercentage(float)
* @since 6.0
*/
public float getCriticalHeapPercentage();
/**
* Set the percentage of off-heap at or above which the cache is considered in
* danger of becoming inoperable due to out of memory exceptions.
*
*
* Changing this value can cause {@link LowMemoryException} to be thrown from
* the following {@link Cache} operations:
*
* - {@link Region#put(Object, Object)}
*
- {@link Region#put(Object, Object, Object)}
*
- {@link Region#create(Object, Object)}
*
- {@link Region#create(Object, Object, Object)}
*
- {@link Region#putAll(java.util.Map)}
*
- {@linkplain QueryService#createIndex(String, com.gemstone.gemfire.cache.query.IndexType, String, String) index creation}
*
- Execution of {@link Function}s whose {@link Function#optimizeForWrite()} returns true.
*
*
*
* Only one change to this attribute or the eviction off-heap percentage will be
* allowed at any given time and its effect will be fully realized before the
* next change is allowed.
*
* @param offHeapPercentage a percentage of the maximum off-heap memory available
* @throws IllegalStateException if the ofHeapPercentage value is not >= 0 or
* <= 100 or when less than the current eviction off-heap percentage
* @see #getCriticalOffHeapPercentage()
* @see #getEvictionOffHeapPercentage()
* @since 7.5
*/
public void setCriticalOffHeapPercentage(float offHeapPercentage);
/**
* Get the percentage of off-heap at or above which the cache is considered in
* danger of becoming inoperable.
*
* @return either the current or recently used percentage of the maximum
* off-heap memory
* @see #setCriticalOffHeapPercentage(float)
* @since 7.5
*/
public float getCriticalOffHeapPercentage();
/**
* Set the percentage of heap at or above which the eviction should begin on
* Regions configured for {@linkplain
* EvictionAttributes#createLRUHeapAttributes() HeapLRU eviction}.
*
*
* Changing this value may cause eviction to begin immediately.
*
*
* Only one change to this attribute or critical heap percentage will be
* allowed at any given time and its effect will be fully realized before the
* next change is allowed.
*
* This feature requires additional VM flags to perform properly. See {@linkplain
* ResourceManager#setCriticalHeapPercentage(float) setCriticalHeapPercentage() for details.}
*
* @param heapPercentage a percentage of the maximum tenured heap for the VM
* @throws IllegalStateException if the heapPercentage value is not >= 0 or
* <= 100 or when greater than the current critical heap percentage.
* @see #getEvictionHeapPercentage()
* @see #getCriticalHeapPercentage()
* @since 6.0
*/
public void setEvictionHeapPercentage(float heapPercentage);
/**
* Get the percentage of heap at or above which the eviction should begin on
* Regions configured for {@linkplain
* EvictionAttributes#createLRUHeapAttributes() HeapLRU eviction}.
*
* @return either the current or recently used percentage of the maximum
* tenured heap
* @see #setEvictionHeapPercentage(float)
* @since 6.0
*/
public float getEvictionHeapPercentage();
/**
* Set the percentage of off-heap at or above which the eviction should begin on
* Regions configured for {@linkplain
* EvictionAttributes#createLRUHeapAttributes() HeapLRU eviction}.
*
*
* Changing this value may cause eviction to begin immediately.
*
*
* Only one change to this attribute or critical off-heap percentage will be
* allowed at any given time and its effect will be fully realized before the
* next change is allowed.
*
* @param offHeapPercentage a percentage of the maximum off-heap memory available
* @throws IllegalStateException if the offHeapPercentage value is not >= 0 or
* <= 100 or when greater than the current critical off-heap percentage.
* @see #getEvictionOffHeapPercentage()
* @see #getCriticalOffHeapPercentage()
* @since 7.5
*/
public void setEvictionOffHeapPercentage(float offHeapPercentage);
/**
* Get the percentage of off-heap at or above which the eviction should begin on
* Regions configured for {@linkplain
* EvictionAttributes#createLRUHeapAttributes() HeapLRU eviction}.
*
* @return either the current or recently used percentage of the maximum
* off-heap memory
* @see #setEvictionOffHeapPercentage(float)
* @since 7.5
*/
public float getEvictionOffHeapPercentage();
}