The management interface for a memory pool. A memory pool
represents the memory resource managed by the Java virtual machine
and is managed by one or more memory managers
.
A Java virtual machine has one or more instances of the
implementation class of this interface. An instance
implementing this interface is
a managed bean (MBean) conforming to the JMX Instrumentation
Specification. The MBean can be obtained by calling
the ManagementFactory.getMemoryPoolMBeans()
method.
An application can monitor the instrumentation of a memory pool
and manage certain characteristics in any of the following ways:
MBeanServer
.MBean proxy
and call the methods of the MBean proxy.The ManagementFactory.getPlatformMBeanServer()
method returns
the platform MBeanServer registered with all platform MBeans.
The ObjectName for uniquely identifying the MBean for a memory pool within an MBeanServer is:
java.lang:type=MemoryPool
,name=pool's name
The Java virtual machine has a heap for object allocation and also maintains non-heap memory for the method area and the Java virtual machine execution. The Java virtual machine can have one or more memory pools. Each memory pool represents a memory area of one of the following types:
getUsage()
method provides an estimate
of the current usage of a memory pool.
For a garbage-collected memory pool, the amount of used memory
includes the memory occupied by all objects in the pool
including both reachable and unreachable objects.
In general, this method is a lightweight operation for getting an approximate memory usage. For some memory pools, for example, when objects are not packed contiguously, this method may be an expensive operation that requires some computation to determine the current memory usage. An implementation should document when this is the case.
getPeakUsage()
method
and reset by calling the resetPeakUsage()
method.
setUsageThreshold
method.
If the default threshold is negative, then usage threshold
crossing checking is not supported for that memory pool and the threshold
value cannot be changed. The
isUsageThresholdSupported()
method can
be used to determine if this functionality is supported.
If the threshold is set to a positive value, the usage threshold crossing
checking is enabled in this memory pool.
If the usage threshold is set to zero, usage
threshold crossing checking on this memory pool is disabled.
A Java virtual machine performs usage threshold crossing checking on a
memory pool basis at its best appropriate time, typically,
at garbage collection time.
Each memory pool maintains an usage threshold count
that will get incremented
every time when the Java virtual machine
detects that the memory pool usage is crossing the threshold.
This manageable usage threshold attribute is designed for monitoring the increasing trend of memory usage with low overhead. Usage threshold may not be appropriate for some memory pools. For example, a generational garbage collector, a common garbage collection algorithm used in many Java virtual machine implementations, manages two or more generations segregating objects by age. Most of the objects are allocated in the youngest generation (say a nursery memory pool). The nursery memory pool is designed to be filled up and collecting the nursery memory pool will free most of its memory space since it is expected to contain mostly short-lived objects and mostly are unreachable at garbage collection time. In this case, it is more appropriate for the nursery memory pool not to support a usage threshold. In addition, if the cost of an object allocation in one memory pool is very low (for example, just atomic pointer exchange), the Java virtual machine would probably not support the usage threshold for that memory pool since the overhead in comparing the usage with the threshold is higher than the cost of object allocation.
The memory usage of the system can be monitored using polling or threshold notification mechanisms.
An application can continuously monitor its memory usage
by calling either the getUsage()
method for all
memory pools or the isUsageThresholdCrossed()
method
for those memory pools that support a usage threshold.
Below is example code that has a thread delicated for
task distribution and processing. At every interval,
it will determine if it should receive and process new tasks based
on its memory usage. If the memory usage exceeds its usage threshold,
it will redistribute all outstanding tasks to other VMs and
stop receiving new tasks until the memory usage returns
below its usage threshold.
// Assume the usage threshold is supported for this pool. // Set the threshold to myThreshold above which no new tasks // should be taken. pool.setUsageThreshold(myThreshold); .... boolean lowMemory = false; while (true) { if (pool.isUsageThresholdCrossed()) { // potential low memory, so redistribute tasks to other VMs lowMemory = true; redistributeTasks(); // stop receiving new tasks stopReceivingTasks(); } else { if (lowMemory) { // resume receiving tasks lowMemory = false; resumeReceivingTasks(); } // processing outstanding task ... } // sleep for sometime try { Thread.sleep(sometime); } catch (InterruptedException e) { ... } }
getUsageThresholdCount()
method
can be used to determine
if the memory usage has returned below the threshold
between two polls.
Below shows another example that takes some action if a memory pool is under low memory and ignores the memory usage changes during the action processing time.
// Assume the usage threshold is supported for this pool. // Set the threshold to myThreshold which determines if // the application will take some action under low memory condition. pool.setUsageThreshold(myThreshold); int prevCrossingCount = 0; while (true) { // A busy loop to detect when the memory usage // has crossed the threshold. while (!pool.isUsageThresholdCrossed() || pool.getUsageThresholdCount() == prevCrossingCount) { try { Thread.sleep(sometime) } catch (InterruptException e) { .... } } // Do some processing such as check for memory usage // and issue a warning .... // Gets the current threshold count. The busy loop will then // ignore any crossing of threshold happens during the processing. prevCrossingCount = pool.getUsageThresholdCount(); }
Usage threshold notification will be emitted by MemoryMBean
.
When the Java virtual machine detects that the memory usage of
a memory pool has reached or exceeded the usage threshold
the virtual machine will trigger the MemoryMBean to emit an
usage threshold exceeded notification
.
Another usage threshold exceeded notification
will not be generated until
the usage has fallen below the threshold and then exceeded it again.
Below is an example code implementing the same logic as the first example above but using the usage threshold notification mechanism to detect low memory conditions instead of polling. In this example code, upon receiving notification, the notification listener notifies another thread to perform the actual action such as to redistribute outstanding tasks, stop receiving tasks, or resume receiving tasks. The handleNotification method should be designed to do a very minimal amount of work and return without delay to avoid causing delay in delivering subsequent notifications. Time-consuming actions should be performed by a separate thread. The notification listener may be invoked by multiple threads concurrently; so the tasks performed by the listener should be properly synchronized.
class MyListener implements javax.management.NotificationListener { public void handleNotification(Notification notification, Object handback) { String notifType = notification.getType(); if (notifType.equals(MemoryNotification.MEMORY_THRESHOLD_EXCEEDED)) { // potential low memory, notify another thread // to redistribute outstanding tasks to other VMs // and stop receiving new tasks. lowMemory = true; notifyAnotherThread(lowMemory); } } } // Register MyListener with MemoryMBean MemoryMBean mbean = ManagementFactory.getMemoryMBean(); NotificationEmitter emitter = (NotificationEmitter) mbean; MyListener listener = new MyListener(); emitter.addNotificationListener(listener, null, null); // Assume this pool supports a usage threshold. // Set the threshold to myThreshold above which no new tasks // should be taken. pool.setUsageThreshold(myThreshold); // Usage threshold detection is enabled and notification will be // handled by MyListener. Continue for other processing. ....
There is no guarantee about when the MemoryMBean will emit
a threshold notification and when the notification will be delivered.
When a notification listener is invoked, the memory usage of
the memory pool may have crossed the usage threshold more
than once.
The MemoryNotification.getCount()
method returns the number
of times that the memory usage has crossed the usage threshold
at the point in time when the notification was constructed.
It can be compared with the current usage threshold count returned
by the getUsageThresholdCount()
method to determine if
such situation has occurred.
MemoryMBean
.
In addition, the collection usage threshold count
will then be incremented.
The isCollectionUsageThresholdSupported()
method can
be used to determine if this functionality is supported.
A Java virtual machine performs collection usage threshold checking on a memory pool basis. This checking is enabled if the collection usage threshold is set to a positive value. If the collection usage threshold is set to zero, this checking is disabled on this memory pool. Default value is zero. The Java virtual machine performs the collection usage threshold checking at garbage collection time.
The collection usage threshold is designed for monitoring the memory usage after the Java virtual machine has expended effort in reclaiming memory space.
Some garbage-collected memory pools may choose not to support the collection usage threshold. For example, a memory pool is only managed by a continuous concurrent garbage collector. Objects can be allocated in this memory pool by some thread while the unused objects are reclaimed by the concurrent garbage collector simultaneously. Unless there is a well-defined garbage collection time which is the best appropriate time to check the memory usage, the collection usage threshold should not be supported.
Method Summary | |
---|---|
MemoryUsage |
getCollectionUsage()
Returns the memory usage after the Java virtual machine most recently expended effort in recycling unused objects in this memory pool. |
long |
getCollectionUsageThreshold()
Returns the collection usage threshold value of this memory pool in bytes. |
long |
getCollectionUsageThresholdCount()
Returns the number of times that the Java virtual machine has detected that the memory usage has crossed the collection usage threshold. |
List |
getMemoryManagerNames()
Returns a list of the names of memory managers that manages this memory pool. |
String |
getName()
Returns the name representing this memory pool. |
MemoryUsage |
getPeakUsage()
Returns the peak memory usage of this memory pool since the Java virtual machine was started or since the peak was reset. |
MemoryType |
getType()
Returns the type of this memory pool. |
MemoryUsage |
getUsage()
Returns an estimate of the memory usage of this memory pool. |
long |
getUsageThreshold()
Returns the usage threshold value of this memory pool in bytes. |
long |
getUsageThresholdCount()
Returns the number of times that the memory usage has crossed the usage threshold. |
boolean |
isCollectionUsageThresholdCrossed()
Tests if the memory usage of this memory pool after the most recent collection on which the Java virtual machine has expended effort has exceeded its collection usage threshold. |
boolean |
isCollectionUsageThresholdSupported()
Tests if this memory pool supports a collection usage threshold. |
boolean |
isUsageThresholdCrossed()
Tests if the memory usage of this memory pool crosses its usage threshold value. |
boolean |
isUsageThresholdSupported()
Tests if this memory pool supports usage threshold. |
boolean |
isValid()
Tests if this memory pool is valid in the Java virtual machine. |
void |
resetPeakUsage()
Resets the peak memory usage statistic of this memory pool to the current memory usage. |
void |
setCollectionUsageThreshold(long threhsold)
Sets the collection usage threshold of this memory pool to the given threshold value. |
void |
setUsageThreshold(long threshold)
Sets the threshold of this memory pool to the given threshold value if this memory pool supports the usage threshold. |
Method Detail |
---|
String getName()
MemoryType getType()
MemoryUsage getUsage()
This method requests the Java virtual machine to make a best-effort estimate of the current memory usage of this memory pool. For some memory pools, this method may be an expensive operation that requires some computation to determine the estimate. An implementation should document when this is the case.
This method is designed for use in monitoring system memory usage and detecting low memory condition.
MemoryUsage getPeakUsage()
void resetPeakUsage()
SecurityException
- if a security manager
exists and the caller does not have
ManagementPermission("control").boolean isValid()
List getMemoryManagerNames()
long getUsageThreshold()
setUsageThreshold
method.
If this memory pool does not support the usage threshold,
this method will return -1.
isUsageThresholdSupported()
void setUsageThreshold(long threshold)
threshold
- the new threshold value in bytes. Must be non-negative.
IllegalArgumentException
- if threshold is negative
or greater than the maximum amount of memory that
this memory pool can use.
UnsupportedOperationException
- if this memory pool
does not support a usage threshold.
SecurityException
- if a security manager
exists and the caller does not have
ManagementPermission("control").getUsageThreshold()
,
isUsageThresholdSupported()
boolean isUsageThresholdCrossed()
UnsupportedOperationException
- if this memory pool
does not support a usage threshold.long getUsageThresholdCount()
UnsupportedOperationException
- if this memory pool
does not support a usage threshold.boolean isUsageThresholdSupported()
long getCollectionUsageThreshold()
setCollectionUsageThreshold
method.
UnsupportedOperationException
- if this memory pool
does not support a collection usage threshold.isCollectionUsageThresholdSupported()
void setCollectionUsageThreshold(long threhsold)
threhsold
- the new collection usage threshold value in bytes.
Must be non-negative.
IllegalArgumentException
- if limit is negative
or greater than the maximum amount of memory that
this memory pool can use.
UnsupportedOperationException
- if this memory pool
does not support a collection usage threshold.
SecurityException
- if a security manager
exists and the caller does not have
ManagementPermission("control").isCollectionUsageThresholdSupported()
boolean isCollectionUsageThresholdCrossed()
UnsupportedOperationException
- if this memory pool
does not support a usage threshold.long getCollectionUsageThresholdCount()
UnsupportedOperationException
- if this memory pool
does not support a collection usage threshold.isCollectionUsageThresholdSupported()
MemoryUsage getCollectionUsage()
This method returns null if the Java virtual machine does not support this method.
boolean isCollectionUsageThresholdSupported()