/*
* Licensed to the Apache Software Foundation (ASF) under one or more contributor license
* agreements. See the NOTICE file distributed with this work for additional information regarding
* copyright ownership. The ASF licenses this file to You 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.
*/
package org.apache.geode.cache.control;
import java.util.Set;
import org.apache.geode.cache.Cache;
import org.apache.geode.cache.EvictionAttributes;
import org.apache.geode.cache.LowMemoryException;
import org.apache.geode.cache.Region;
import org.apache.geode.cache.execute.Function;
import org.apache.geode.cache.query.QueryService;
/**
* Provides support for managing resources used by the local {@link org.apache.geode.cache.Cache}.
* <p>
* Re-balancing the GemFire Cache resources can be accomplished using a {@link RebalanceOperation}:
*
* <pre>
* ResourceManager resourceManager = cache.getResourceManager();
* RebalanceOperation rebalanceOp = resourceManager.createRebalanceFactory().start();
* </pre>
*
* Monitoring of heap utilization is enabled by setting the critical heap percentage using
* {@link #setCriticalHeapPercentage(float)}.
*
* @since GemFire 6.0
*/
public interface ResourceManager {
/**
* The default percent of heap memory at which the VM is considered in a critical state. Current
* value is <code>0.0</code>.
*
* @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
* <code>0.0</code>. Note that if a HeapLRU is created and the eviction heap percentage has not
* been set then it will default <code>80.0</code> unless the critical heap percentage has been
* set in which case it will default to a value <code>5.0</code> less than the critical heap
* percentage.
*
* @see ResourceManager#setEvictionHeapPercentage(float)
* @see ResourceManager#getEvictionHeapPercentage()
*/
public static final float DEFAULT_EVICTION_PERCENTAGE = 0.0f;
/**
* 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<RebalanceOperation> 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.
*
* <p>
* Changing this value can cause {@link LowMemoryException} to be thrown from the following
* {@link Cache} operations:
* <ul>
* <li>{@link Region#put(Object, Object)}
* <li>{@link Region#put(Object, Object, Object)}
* <li>{@link Region#create(Object, Object)}
* <li>{@link Region#create(Object, Object, Object)}
* <li>{@link Region#putAll(java.util.Map)}
* <li>{@linkplain QueryService#createIndex(String, org.apache.geode.cache.query.IndexType, String, String)
* index creation}
* <li>Execution of {@link Function}s whose {@link Function#optimizeForWrite()} returns true.
* </ul>
*
* <p>
* 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 <code>-Xmx</code> and
* <code>-Xms</code> 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 <A href="http://java.sun.com/docs/hotspot/gc/index.html">HotSpot</a> VM, the
* <code>-XX:+UseConcMarkSweepGC</code> flag needs to be set, and
* <code>-XX:CMSInitiatingOccupancyFraction=N</code> 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, <code>-Xgc:gencon</code> and <code>-XXgcTrigger:N</code>,
* 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 <code>-Xgcpolicy:gencon</code>, 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 GemFire 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 GemFire 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.
*
* <p>
* Changing this value can cause {@link LowMemoryException} to be thrown from the following
* {@link Cache} operations:
* <ul>
* <li>{@link Region#put(Object, Object)}
* <li>{@link Region#put(Object, Object, Object)}
* <li>{@link Region#create(Object, Object)}
* <li>{@link Region#create(Object, Object, Object)}
* <li>{@link Region#putAll(java.util.Map)}
* <li>{@linkplain QueryService#createIndex(String, org.apache.geode.cache.query.IndexType, String, String)
* index creation}
* <li>Execution of {@link Function}s whose {@link Function#optimizeForWrite()} returns true.
* </ul>
*
* <p>
* 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 Geode 1.0
*/
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 Geode 1.0
*/
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}.
*
* <p>
* Changing this value may cause eviction to begin immediately.
*
* <p>
* 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 GemFire 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 GemFire 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}.
*
* <p>
* Changing this value may cause eviction to begin immediately.
*
* <p>
* 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 Geode 1.0
*/
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 Geode 1.0
*/
public float getEvictionOffHeapPercentage();
}