| Frames | No Frames |
1: /* MemoryMXBean.java - Interface for a memory bean 2: Copyright (C) 2006 Free Software Foundation 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: package java.lang.management; 39: 40: /** 41: * <p> 42: * Provides access to information about the memory used 43: * by the virtual machine. An instance of this bean is 44: * obtained by calling 45: * {@link ManagementFactory#getMemoryMXBean()}. 46: * </p> 47: * <p> 48: * The Java virtual machine uses two types of memory: 49: * heap memory and non-heap memory. The heap is the 50: * storage location for class and array instances, and is 51: * thus the main source of memory associated with running 52: * Java programs. The heap is created when the virtual 53: * machine is started, and is periodically scanned by the 54: * garbage collector(s), in order to reclaim memory which 55: * is no longer used (e.g. because an object reference has 56: * gone out of scope). 57: * </p> 58: * <p> 59: * Non-heap memory is used by the virtual machine in order to 60: * perform its duties. Thus, it mainly acts as the storage 61: * location for structures created as a result of parsing Java 62: * bytecode, such as the constant pool and constructor/method 63: * declarations. When a Just-In-Time (JIT) compiler is in 64: * operation, this will use non-heap memory to store compiled 65: * bytecode. 66: * </p> 67: * <p> 68: * Both types of memory may be non-contiguous. During the 69: * lifetime of the virtual machine, the size of both may 70: * either change (either expanding or contracting) or stay 71: * the same. 72: * </p> 73: * <h2>Notifications</h2> 74: * <p> 75: * Implementations of this interface also conform to the 76: * {@link javax.management.NotificationEmitter} interface, 77: * and supply two notifications reflecting memory usage. 78: * These notifications occur when a usage threshold is 79: * exceeded; for more details of these, see the documentation 80: * of {@link MemoryPoolMXBean}. If threshold monitoring 81: * is supported, then a notification will be emitted each time 82: * the threshold is crossed. Another notification will not 83: * be emitted unless the usage level has dropped below the 84: * threshold again in the meantime. 85: * </p> 86: * <p> 87: * The emitted notifications are instances of 88: * {@link javax.management.Notification}, with a type of 89: * either 90: * {@link java.lang.management.MemoryNotificationInfo#MEMORY_THRESHOLD_EXCEEDED} 91: * or 92: * {@link java.lang.management.MemoryNotificationInfo#MEMORY_COLLECTION_THRESHOLD_EXCEEDED} 93: * (depending on whether the notification refers to the general 94: * usage threshold or the garbage collection threshold) and an instance 95: * of {@link java.lang.management.MemoryNotificationInfo} contained 96: * in the user data section. This is wrapped inside an instance 97: * of {@link javax.management.openmbean.CompositeData}, as explained 98: * in the documentation for 99: * {@link java.lang.management.MemoryNotificationInfo}. 100: * </p> 101: * 102: * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 103: * @since 1.5 104: */ 105: public interface MemoryMXBean 106: { 107: 108: /** 109: * Instigates a garbage collection cycle. The virtual 110: * machine's garbage collector should make the best 111: * attempt it can at reclaiming unused memory. This 112: * is equivalent to invoking {@link java.lang.System.gc()}. 113: * 114: * @see java.lang.System#gc() 115: */ 116: void gc(); 117: 118: /** 119: * Returns a {@link MemoryUsage} object representing the 120: * current state of the heap. This incorporates various 121: * statistics on both the initial and current memory 122: * allocations used by the heap. 123: * 124: * @return a {@link MemoryUsage} object for the heap. 125: */ 126: MemoryUsage getHeapMemoryUsage(); 127: 128: /** 129: * Returns a {@link MemoryUsage} object representing the 130: * current state of non-heap memory. This incorporates 131: * various statistics on both the initial and current 132: * memory allocations used by non-heap memory.. 133: * 134: * @return a {@link MemoryUsage} object for non-heap 135: * memory. 136: */ 137: MemoryUsage getNonHeapMemoryUsage(); 138: 139: /** 140: * Returns the number of objects which are waiting to 141: * be garbage collected (finalized). An object is 142: * finalized when the garbage collector determines that 143: * there are no more references to that object are in 144: * use. 145: * 146: * @return the number of objects awaiting finalization. 147: */ 148: int getObjectPendingFinalizationCount(); 149: 150: /** 151: * Returns true if the virtual machine will emit additional 152: * information when memory is allocated and deallocated. The 153: * format of the output is left up to the virtual machine. 154: * 155: * @return true if verbose memory output is on. 156: */ 157: boolean isVerbose(); 158: 159: /** 160: * Turns on or off the emission of additional information 161: * when memory is allocated and deallocated. The format of the 162: * output is left up to the virtual machine. This method 163: * may be called by multiple threads concurrently, but there 164: * is only one global setting of verbosity that is affected. 165: * 166: * @param verbose the new setting for verbose memory output. 167: * @throws SecurityException if a security manager exists and 168: * denies ManagementPermission("control"). 169: */ 170: void setVerbose(boolean verbose); 171: 172: }