001 /* MemoryMXBean.java - Interface for a memory bean 002 Copyright (C) 2006 Free Software Foundation 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 package java.lang.management; 039 040 /** 041 * <p> 042 * Provides access to information about the memory used 043 * by the virtual machine. An instance of this bean is 044 * obtained by calling 045 * {@link ManagementFactory#getMemoryMXBean()}. 046 * </p> 047 * <p> 048 * The Java virtual machine uses two types of memory: 049 * heap memory and non-heap memory. The heap is the 050 * storage location for class and array instances, and is 051 * thus the main source of memory associated with running 052 * Java programs. The heap is created when the virtual 053 * machine is started, and is periodically scanned by the 054 * garbage collector(s), in order to reclaim memory which 055 * is no longer used (e.g. because an object reference has 056 * gone out of scope). 057 * </p> 058 * <p> 059 * Non-heap memory is used by the virtual machine in order to 060 * perform its duties. Thus, it mainly acts as the storage 061 * location for structures created as a result of parsing Java 062 * bytecode, such as the constant pool and constructor/method 063 * declarations. When a Just-In-Time (JIT) compiler is in 064 * operation, this will use non-heap memory to store compiled 065 * bytecode. 066 * </p> 067 * <p> 068 * Both types of memory may be non-contiguous. During the 069 * lifetime of the virtual machine, the size of both may 070 * either change (either expanding or contracting) or stay 071 * the same. 072 * </p> 073 * <h2>Notifications</h2> 074 * <p> 075 * Implementations of this interface also conform to the 076 * {@link javax.management.NotificationEmitter} interface, 077 * and supply two notifications reflecting memory usage. 078 * These notifications occur when a usage threshold is 079 * exceeded; for more details of these, see the documentation 080 * of {@link MemoryPoolMXBean}. If threshold monitoring 081 * is supported, then a notification will be emitted each time 082 * the threshold is crossed. Another notification will not 083 * be emitted unless the usage level has dropped below the 084 * threshold again in the meantime. 085 * </p> 086 * <p> 087 * The emitted notifications are instances of 088 * {@link javax.management.Notification}, with a type of 089 * either 090 * {@link java.lang.management.MemoryNotificationInfo#MEMORY_THRESHOLD_EXCEEDED} 091 * or 092 * {@link java.lang.management.MemoryNotificationInfo#MEMORY_COLLECTION_THRESHOLD_EXCEEDED} 093 * (depending on whether the notification refers to the general 094 * usage threshold or the garbage collection threshold) and an instance 095 * of {@link java.lang.management.MemoryNotificationInfo} contained 096 * in the user data section. This is wrapped inside an instance 097 * of {@link javax.management.openmbean.CompositeData}, as explained 098 * in the documentation for 099 * {@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 }