KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > lang > management > MemoryPoolMXBean


1 /*
2  * @(#)MemoryPoolMXBean.java 1.21 06/03/08
3  *
4  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.lang.management;
9
10 /**
11  * The management interface for a memory pool. A memory pool
12  * represents the memory resource managed by the Java virtual machine
13  * and is managed by one or more {@link MemoryManagerMXBean memory managers}.
14  *
15  * <p> A Java virtual machine has one or more instances of the
16  * implementation class of this interface. An instance
17  * implementing this interface is
18  * an <a HREF="ManagementFactory.html#MXBean">MXBean</a>
19  * that can be obtained by calling
20  * the {@link ManagementFactory#getMemoryPoolMXBeans} method or
21  * from the {@link ManagementFactory#getPlatformMBeanServer
22  * platform <tt>MBeanServer</tt>} method.
23  *
24  * <p>The <tt>ObjectName</tt> for uniquely identifying the MXBean for
25  * a memory pool within an <tt>MBeanServer</tt> is:
26  * <blockquote>
27  * {@link ManagementFactory#MEMORY_POOL_MXBEAN_DOMAIN_TYPE
28  * <tt>java.lang:type=MemoryPool</tt>}<tt>,name=</tt><i>pool's name</i>
29  * </blockquote>
30  *
31  * <h4>Memory Type</h4>
32  * <p>The Java virtual machine has a heap for object allocation and also
33  * maintains non-heap memory for the method area and the Java virtual
34  * machine execution. The Java virtual machine can have one or more
35  * memory pools. Each memory pool represents a memory area
36  * of one of the following types:
37  * <ul>
38  * <li>{@link MemoryType#HEAP heap}</li>
39  * <li>{@link MemoryType#NON_HEAP non-heap}</li>
40  * </ul>
41  *
42  * <h4>Memory Usage Monitoring</h4>
43  *
44  * A memory pool has the following attributes:
45  * <ul>
46  * <li><a HREF="#Usage">Memory usage</a></li>
47  * <li><a HREF="#PeakUsage">Peak memory usage</a></li>
48  * <li><a HREF="#UsageThreshold">Usage Threshold</a></li>
49  * <li><a HREF="#CollectionThreshold">Collection Usage Threshold</a>
50  * (only supported by some <em>garbage-collected</em> memory pools)</li>
51  * </ul>
52  *
53  * <h4><a name="Usage">1. Memory Usage</a></h4>
54  *
55  * The {@link #getUsage} method provides an estimate
56  * of the current usage of a memory pool.
57  * For a garbage-collected memory pool, the amount of used memory
58  * includes the memory occupied by all objects in the pool
59  * including both <em>reachable</em> and <em>unreachable</em> objects.
60  *
61  * <p>In general, this method is a lightweight operation for getting
62  * an approximate memory usage. For some memory pools, for example,
63  * when objects are not packed contiguously, this method may be
64  * an expensive operation that requires some computation to determine
65  * the current memory usage. An implementation should document when
66  * this is the case.
67  *
68  * <h4><a name="PeakUsage">2. Peak Memory Usage</a></h4>
69  *
70  * The Java virtual machine maintains the peak memory usage of a memory
71  * pool since the virtual machine was started or the peak was reset.
72  * The peak memory usage is returned by the {@link #getPeakUsage} method
73  * and reset by calling the {@link #resetPeakUsage} method.
74  *
75  * <h4><a name="UsageThreshold">3. Usage Threshold</a></h4>
76  *
77  * Each memory pool has a manageable attribute
78  * called the <i>usage threshold</i> which has a default value supplied
79  * by the Java virtual machine. The default value is platform-dependent.
80  * The usage threshold can be set via the
81  * {@link #setUsageThreshold setUsageThreshold} method.
82  * If the threshold is set to a positive value, the usage threshold crossing
83  * checking is enabled in this memory pool.
84  * If the usage threshold is set to zero, usage
85  * threshold crossing checking on this memory pool is disabled.
86  * The {@link MemoryPoolMXBean#isUsageThresholdSupported} method can
87  * be used to determine if this functionality is supported.
88  * <p>
89  * A Java virtual machine performs usage threshold crossing checking on a
90  * memory pool basis at its best appropriate time, typically,
91  * at garbage collection time.
92  * Each memory pool maintains a {@link #getUsageThresholdCount
93  * usage threshold count} that will get incremented
94  * every time when the Java virtual machine
95  * detects that the memory pool usage is crossing the threshold.
96  * <p>
97  * This manageable usage threshold attribute is designed for monitoring the
98  * increasing trend of memory usage with low overhead.
99  * Usage threshold may not be appropriate for some memory pools.
100  * For example, a generational garbage collector, a common garbage collection
101  * algorithm used in many Java virtual machine implementations,
102  * manages two or more generations segregating objects by age.
103  * Most of the objects are allocated in
104  * the <em>youngest generation</em> (say a nursery memory pool).
105  * The nursery memory pool is designed to be filled up and
106  * collecting the nursery memory pool will free most of its memory space
107  * since it is expected to contain mostly short-lived objects
108  * and mostly are unreachable at garbage collection time.
109  * In this case, it is more appropriate for the nursery memory pool
110  * not to support a usage threshold. In addition,
111  * if the cost of an object allocation
112  * in one memory pool is very low (for example, just atomic pointer exchange),
113  * the Java virtual machine would probably not support the usage threshold
114  * for that memory pool since the overhead in comparing the usage with
115  * the threshold is higher than the cost of object allocation.
116  *
117  * <p>
118  * The memory usage of the system can be monitored using
119  * <a HREF="#Polling">polling</a> or
120  * <a HREF="#ThresholdNotification">threshold notification</a> mechanisms.
121  *
122  * <ol type="a">
123  * <li><a name="Polling"><b>Polling</b></a>
124  * <p>
125  * An application can continuously monitor its memory usage
126  * by calling either the {@link #getUsage} method for all
127  * memory pools or the {@link #isUsageThresholdExceeded} method
128  * for those memory pools that support a usage threshold.
129  * Below is example code that has a thread delicated for
130  * task distribution and processing. At every interval,
131  * it will determine if it should receive and process new tasks based
132  * on its memory usage. If the memory usage exceeds its usage threshold,
133  * it will redistribute all outstanding tasks to other VMs and
134  * stop receiving new tasks until the memory usage returns
135  * below its usage threshold.
136  *
137  * <pre>
138  * // Assume the usage threshold is supported for this pool.
139  * // Set the threshold to myThreshold above which no new tasks
140  * // should be taken.
141  * pool.setUsageThreshold(myThreshold);
142  * ....
143  *
144  * boolean lowMemory = false;
145  * while (true) {
146  * if (pool.isUsageThresholdExceeded()) {
147  * // potential low memory, so redistribute tasks to other VMs
148  * lowMemory = true;
149  * redistributeTasks();
150  * // stop receiving new tasks
151  * stopReceivingTasks();
152  * } else {
153  * if (lowMemory) {
154  * // resume receiving tasks
155  * lowMemory = false;
156  * resumeReceivingTasks();
157  * }
158  * // processing outstanding task
159  * ...
160  * }
161  * // sleep for sometime
162  * try {
163  * Thread.sleep(sometime);
164  * } catch (InterruptedException e) {
165  * ...
166  * }
167  * }
168  * </pre>
169  *
170  * <hr>
171  * The above example does not differentiate the case where
172  * the memory usage has temporarily dropped below the usage threshold
173  * from the case where the memory usage remains above the threshould
174  * between two iterations. The usage threshold count returned by
175  * the {@link #getUsageThresholdCount} method
176  * can be used to determine
177  * if the memory usage has returned below the threshold
178  * between two polls.
179  * <p>
180  * Below shows another example that takes some action if a
181  * memory pool is under low memory and ignores the memory usage
182  * changes during the action processing time.
183  *
184  * <pre>
185  * // Assume the usage threshold is supported for this pool.
186  * // Set the threshold to myThreshold which determines if
187  * // the application will take some action under low memory condition.
188  * pool.setUsageThreshold(myThreshold);
189  *
190  * int prevCrossingCount = 0;
191  * while (true) {
192  * // A busy loop to detect when the memory usage
193  * // has exceeded the threshold.
194  * while (!pool.isUsageThresholdExceeded() ||
195  * pool.getUsageThresholdCount() == prevCrossingCount) {
196  * try {
197  * Thread.sleep(sometime)
198  * } catch (InterruptException e) {
199  * ....
200  * }
201  * }
202  *
203  * // Do some processing such as check for memory usage
204  * // and issue a warning
205  * ....
206  *
207  * // Gets the current threshold count. The busy loop will then
208  * // ignore any crossing of threshold happens during the processing.
209  * prevCrossingCount = pool.getUsageThresholdCount();
210  * }
211  * </pre><hr>
212  * </li>
213  * <li><a name="ThresholdNotification"><b>Usage Threshold Notifications</b></a>
214  * <p>
215  * Usage threshold notification will be emitted by {@link MemoryMXBean}.
216  * When the Java virtual machine detects that the memory usage of
217  * a memory pool has reached or exceeded the usage threshold
218  * the virtual machine will trigger the <tt>MemoryMXBean</tt> to emit an
219  * {@link MemoryNotificationInfo#MEMORY_THRESHOLD_EXCEEDED
220  * usage threshold exceeded notification}.
221  * Another usage threshold exceeded notification will not be
222  * generated until the usage has fallen below the threshold and
223  * then exceeded it again.
224  * <p>
225  * Below is an example code implementing the same logic as the
226  * first example above but using the usage threshold notification
227  * mechanism to detect low memory conditions instead of polling.
228  * In this example code, upon receiving notification, the notification
229  * listener notifies another thread to perform the actual action
230  * such as to redistribute outstanding tasks, stop receiving tasks,
231  * or resume receiving tasks.
232  * The <tt>handleNotification</tt> method should be designed to
233  * do a very minimal amount of work and return without delay to avoid
234  * causing delay in delivering subsequent notifications. Time-consuming
235  * actions should be performed by a separate thread.
236  * The notification listener may be invoked by multiple threads
237  * concurrently; so the tasks performed by the listener
238  * should be properly synchronized.
239  *
240  * <pre>
241  * class MyListener implements javax.management.NotificationListener {
242  * public void handleNotification(Notification notification, Object handback) {
243  * String notifType = notification.getType();
244  * if (notifType.equals(MemoryNotificationInfo.MEMORY_THRESHOLD_EXCEEDED)) {
245  * // potential low memory, notify another thread
246  * // to redistribute outstanding tasks to other VMs
247  * // and stop receiving new tasks.
248  * lowMemory = true;
249  * notifyAnotherThread(lowMemory);
250  * }
251  * }
252  * }
253  *
254  * // Register MyListener with MemoryMXBean
255  * MemoryMXBean mbean = ManagementFactory.getMemoryMXBean();
256  * NotificationEmitter emitter = (NotificationEmitter) mbean;
257  * MyListener listener = new MyListener();
258  * emitter.addNotificationListener(listener, null, null);
259  *
260  * // Assume this pool supports a usage threshold.
261  * // Set the threshold to myThreshold above which no new tasks
262  * // should be taken.
263  * pool.setUsageThreshold(myThreshold);
264  *
265  * // Usage threshold detection is enabled and notification will be
266  * // handled by MyListener. Continue for other processing.
267  * ....
268  *
269  * </pre>
270  * <hr>
271  * <p>
272  * There is no guarantee about when the <tt>MemoryMXBean</tt> will emit
273  * a threshold notification and when the notification will be delivered.
274  * When a notification listener is invoked, the memory usage of
275  * the memory pool may have crossed the usage threshold more
276  * than once.
277  * The {@link MemoryNotificationInfo#getCount} method returns the number
278  * of times that the memory usage has crossed the usage threshold
279  * at the point in time when the notification was constructed.
280  * It can be compared with the current usage threshold count returned
281  * by the {@link #getUsageThresholdCount} method to determine if
282  * such situation has occurred.
283  * </li>
284  * </ol>
285  *
286  * <h4><a name="CollectionThreshold">4. Collection Usage Threshold</a></h4>
287  *
288  * Collection usage threshold is a manageable attribute only applicable
289  * to some garbage-collected memory pools.
290  * After a Java virtual machine has expended effort in reclaiming memory
291  * space by recycling unused objects in a memory pool at garbage collection
292  * time, some number of bytes in the memory pools that are garbaged
293  * collected will still be in use. The collection usage threshold
294  * allows a value to be set for this number of bytes such
295  * that if the threshold is exceeded,
296  * a {@link MemoryNotificationInfo#MEMORY_THRESHOLD_EXCEEDED
297  * collection usage threshold exceeded notification}
298  * will be emitted by the {@link MemoryMXBean}.
299  * In addition, the {@link #getCollectionUsageThresholdCount
300  * collection usage threshold count} will then be incremented.
301  *
302  * <p>
303  * The {@link MemoryPoolMXBean#isCollectionUsageThresholdSupported} method can
304  * be used to determine if this functionality is supported.
305  *
306  * <p>
307  * A Java virtual machine performs collection usage threshold checking
308  * on a memory pool basis. This checking is enabled if the collection
309  * usage threshold is set to a positive value.
310  * If the collection usage threshold is set to zero, this checking
311  * is disabled on this memory pool. Default value is zero.
312  * The Java virtual machine performs the collection usage threshold
313  * checking at garbage collection time.
314  *
315  * <p>
316  * Some garbage-collected memory pools may
317  * choose not to support the collection usage threshold. For example,
318  * a memory pool is only managed by a continuous concurrent garbage
319  * collector. Objects can be allocated in this memory pool by some thread
320  * while the unused objects are reclaimed by the concurrent garbage
321  * collector simultaneously. Unless there is a well-defined
322  * garbage collection time which is the best appropriate time
323  * to check the memory usage, the collection usage threshold should not
324  * be supported.
325  *
326  * <p>
327  * The collection usage threshold is designed for monitoring the memory usage
328  * after the Java virtual machine has expended effort in reclaiming
329  * memory space. The collection usage could also be monitored
330  * by the polling and threshold notification mechanism
331  * described above for the <a HREF="#UsageThreshold">usage threshold</a>
332  * in a similar fashion.
333  *
334  * @see <a HREF="../../../javax/management/package-summary.html">
335  * JMX Specification.</a>
336  * @see <a HREF="package-summary.html#examples">
337  * Ways to Access MXBeans</a>
338  *
339  * @author Mandy Chung
340  * @version 1.21, 03/08/06
341  * @since 1.5
342  */
343 public interface MemoryPoolMXBean {
344     /**
345      * Returns the name representing this memory pool.
346      *
347      * @return the name of this memory pool.
348      */
349     public String JavaDoc getName();
350
351     /**
352      * Returns the type of this memory pool.
353      *
354      * <p>
355      * <b>MBeanServer access</b>:<br>
356      * The mapped type of <tt>MemoryType</tt> is <tt>String</tt>
357      * and the value is the name of the <tt>MemoryType</tt>.
358      *
359      * @return the type of this memory pool.
360      */
361     public MemoryType JavaDoc getType();
362     
363     /**
364      * Returns an estimate of the memory usage of this memory pool.
365      * This method returns <tt>null</tt>
366      * if this memory pool is not valid (i.e. no longer exists).
367      *
368      * <p>
369      * This method requests the Java virtual machine to make
370      * a best-effort estimate of the current memory usage of this
371      * memory pool. For some memory pools, this method may be an
372      * expensive operation that requires some computation to determine
373      * the estimate. An implementation should document when
374      * this is the case.
375      *
376      * <p>This method is designed for use in monitoring system
377      * memory usage and detecting low memory condition.
378      *
379      * <p>
380      * <b>MBeanServer access</b>:<br>
381      * The mapped type of <tt>MemoryUsage</tt> is
382      * <tt>CompositeData</tt> with attributes as specified in
383      * {@link MemoryUsage#from MemoryUsage}.
384      *
385      * @return a {@link MemoryUsage} object; or <tt>null</tt> if
386      * this pool not valid.
387      */
388     public MemoryUsage JavaDoc getUsage();
389
390     /**
391      * Returns the peak memory usage of this memory pool since the
392      * Java virtual machine was started or since the peak was reset.
393      * This method returns <tt>null</tt>
394      * if this memory pool is not valid (i.e. no longer exists).
395      *
396      * <p>
397      * <b>MBeanServer access</b>:<br>
398      * The mapped type of <tt>MemoryUsage</tt> is
399      * <tt>CompositeData</tt> with attributes as specified in
400      * {@link MemoryUsage#from MemoryUsage}.
401      *
402      * @return a {@link MemoryUsage} object representing the peak
403      * memory usage; or <tt>null</tt> if this pool is not valid.
404      *
405      */
406     public MemoryUsage JavaDoc getPeakUsage();
407  
408     /**
409      * Resets the peak memory usage statistic of this memory pool
410      * to the current memory usage.
411      *
412      * @throws java.lang.SecurityException if a security manager
413      * exists and the caller does not have
414      * ManagementPermission("control").
415      */
416     public void resetPeakUsage();
417
418     /**
419      * Tests if this memory pool is valid in the Java virtual
420      * machine. A memory pool becomes invalid once the Java virtual
421      * machine removes it from the memory system.
422      *
423      * @return <tt>true</tt> if the memory pool is valid in the running
424      * Java virtual machine;
425      * <tt>false</tt> otherwise.
426      */
427     public boolean isValid();
428
429     /**
430      * Returns the name of memory managers that manages this memory pool.
431      * Each memory pool will be managed by at least one memory manager.
432      *
433      * @return an array of <tt>String</tt> objects, each is the name of
434      * a memory manager managing this memory pool.
435      */
436     public String JavaDoc[] getMemoryManagerNames();
437
438     /**
439      * Returns the usage threshold value of this memory pool in bytes.
440      * Each memory pool has a platform-dependent default threshold value.
441      * The current usage threshold can be changed via the
442      * {@link #setUsageThreshold setUsageThreshold} method.
443      *
444      * @return the usage threshold value of this memory pool in bytes.
445      *
446      * @throws UnsupportedOperationException if this memory pool
447      * does not support a usage threshold.
448      *
449      * @see #isUsageThresholdSupported
450      */
451     public long getUsageThreshold();
452
453     /**
454      * Sets the threshold of this memory pool to the given <tt>threshold</tt>
455      * value if this memory pool supports the usage threshold.
456      * The usage threshold crossing checking is enabled in this memory pool
457      * if the threshold is set to a positive value.
458      * The usage threshold crossing checking is disabled
459      * if it is set to zero.
460      *
461      * @param threshold the new threshold value in bytes. Must be non-negative.
462      *
463      * @throws IllegalArgumentException if <tt>threshold</tt> is negative
464      * or greater than the maximum amount of memory for
465      * this memory pool if defined.
466      *
467      * @throws UnsupportedOperationException if this memory pool
468      * does not support a usage threshold.
469      *
470      * @throws java.lang.SecurityException if a security manager
471      * exists and the caller does not have
472      * ManagementPermission("control").
473      *
474      * @see #isUsageThresholdSupported
475      * @see <a HREF="#UsageThreshold">Usage threshold</a>
476      */
477     public void setUsageThreshold(long threshold);
478
479     /**
480      * Tests if the memory usage of this memory pool
481      * reaches or exceeds its usage threshold value.
482      *
483      * @return <tt>true</tt> if the memory usage of
484      * this memory pool reaches or exceeds the threshold value;
485      * <tt>false</tt> otherwise.
486      *
487      * @throws UnsupportedOperationException if this memory pool
488      * does not support a usage threshold.
489      */
490     public boolean isUsageThresholdExceeded();
491
492     /**
493      * Returns the number of times that the memory usage has crossed
494      * the usage threshold.
495      *
496      * @return the number of times that the memory usage
497      * has crossed its usage threshold value.
498      *
499      * @throws UnsupportedOperationException if this memory pool
500      * does not support a usage threshold.
501      */
502     public long getUsageThresholdCount();
503
504     /**
505      * Tests if this memory pool supports usage threshold.
506      *
507      * @return <tt>true</tt> if this memory pool supports usage threshold;
508      * <tt>false</tt> otherwise.
509      */
510     public boolean isUsageThresholdSupported();
511
512     /**
513      * Returns the collection usage threshold value of this memory pool
514      * in bytes. The default value is zero. The collection usage
515      * threshold can be changed via the
516      * {@link #setCollectionUsageThreshold setCollectionUsageThreshold} method.
517      *
518      * @return the collection usage threshold of this memory pool in bytes.
519      *
520      * @throws UnsupportedOperationException if this memory pool
521      * does not support a collection usage threshold.
522      *
523      * @see #isCollectionUsageThresholdSupported
524      */
525     public long getCollectionUsageThreshold();
526
527     /**
528      * Sets the collection usage threshold of this memory pool to
529      * the given <tt>threshold</tt> value.
530      * When this threshold is set to positive, the Java virtual machine
531      * will check the memory usage at its best appropriate time after it has
532      * expended effort in recycling unused objects in this memory pool.
533      * <p>
534      * The collection usage threshold crossing checking is enabled
535      * in this memory pool if the threshold is set to a positive value.
536      * The collection usage threshold crossing checking is disabled
537      * if it is set to zero.
538      *
539      * @param threhsold the new collection usage threshold value in bytes.
540      * Must be non-negative.
541      *
542      * @throws IllegalArgumentException if <tt>threshold</tt> is negative
543      * or greater than the maximum amount of memory for
544      * this memory pool if defined.
545      *
546      * @throws UnsupportedOperationException if this memory pool
547      * does not support a collection usage threshold.
548      *
549      * @throws java.lang.SecurityException if a security manager
550      * exists and the caller does not have
551      * ManagementPermission("control").
552      *
553      * @see #isCollectionUsageThresholdSupported
554      * @see <a HREF="#CollectionThreshold">Collection usage threshold</a>
555      */
556     public void setCollectionUsageThreshold(long threhsold);
557
558     /**
559      * Tests if the memory usage of this memory pool after
560      * the most recent collection on which the Java virtual
561      * machine has expended effort has reached or
562      * exceeded its collection usage threshold.
563      * This method does not request the Java virtual
564      * machine to perform any garbage collection other than its normal
565      * automatic memory management.
566      *
567      * @return <tt>true</tt> if the memory usage of this memory pool
568      * reaches or exceeds the collection usage threshold value
569      * in the most recent collection;
570      * <tt>false</tt> otherwise.
571      *
572      * @throws UnsupportedOperationException if this memory pool
573      * does not support a usage threshold.
574      */
575     public boolean isCollectionUsageThresholdExceeded();
576
577     /**
578      * Returns the number of times that the Java virtual machine
579      * has detected that the memory usage has reached or
580      * exceeded the collection usage threshold.
581      *
582      * @return the number of times that the memory
583      * usage has reached or exceeded the collection usage threshold.
584      *
585      * @throws UnsupportedOperationException if this memory pool
586      * does not support a collection usage threshold.
587      *
588      * @see #isCollectionUsageThresholdSupported
589      */
590     public long getCollectionUsageThresholdCount();
591
592     /**
593      * Returns the memory usage after the Java virtual machine
594      * most recently expended effort in recycling unused objects
595      * in this memory pool.
596      * This method does not request the Java virtual
597      * machine to perform any garbage collection other than its normal
598      * automatic memory management.
599      * This method returns <tt>null</tt> if the Java virtual
600      * machine does not support this method.
601      *
602      * <p>
603      * <b>MBeanServer access</b>:<br>
604      * The mapped type of <tt>MemoryUsage</tt> is
605      * <tt>CompositeData</tt> with attributes as specified in
606      * {@link MemoryUsage#from MemoryUsage}.
607      *
608      * @return a {@link MemoryUsage} representing the memory usage of
609      * this memory pool after the Java virtual machine most recently
610      * expended effort in recycling unused objects;
611      * <tt>null</tt> if this method is not supported.
612      */
613     public MemoryUsage JavaDoc getCollectionUsage();
614
615     /**
616      * Tests if this memory pool supports a collection usage threshold.
617      *
618      * @return <tt>true</tt> if this memory pool supports the
619      * collection usage threshold; <tt>false</tt> otherwise.
620      */
621     public boolean isCollectionUsageThresholdSupported();
622 }
623
Popular Tags