trunk/libjava/classpath/java/lang/management/MemoryUsage.java

   1 /* MemoryUsage.java - Information on the usage of a memory pool.
   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 import javax.management.openmbean.CompositeData;
  41 import javax.management.openmbean.CompositeType;
  42 import javax.management.openmbean.SimpleType;
  43 /**
  44  * <p>
  45  * Retains information on the usage of a particular memory
  46  * pool, or heap/non-heap memory as a whole.  Memory usage
  47  * is represented by four values (all in bytes):
  48  * </p>
  49  * <ul>
  50  * <li><strong>Initial Level</strong>: This is the initial
  51  * amount of memory allocated for the pool by the operating
  52  * system.  This value may be undefined.</li>
  53  * <li><strong>Used Level</strong>: This is the amount of
  54  * memory currently in use.</li>
  55  * <li><strong>Committed Level</strong>: This is the current
  56  * amount of memory allocated for the pool by the operating
  57  * system.  This value will always be equal to or greater than
  58  * the current amount of memory in use.  It may drop below
  59  * the initial amount, if the virtual machine judges this to
  60  * be practical.</li>
  61  * <li><strong>Maximum Level</strong>: This is the maximum
  62  * amount of memory that may be allocated for the pool by
  63  * the operating system.  Like the initial amount, it may
  64  * be undefined.  If it is defined, it will be greater than
  65  * or equal to the used and committed amounts and may change
  66  * over time.  It is not guaranteed that the maximum amount
  67  * of memory may actually be allocated to the pool.  For
  68  * example, a request for an amount of memory greater than
  69  * the current committed level, but less than the maximum,
  70  * may still fail due to resources at the operating system
  71  * level not being sufficient to fulfill the demand.</li>
  72  * </ul>
  73  *
  74  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  75  * @since 1.5
  76  * @see MemoryMXBean
  77  * @see MemoryPoolMXBean
  78  */
  79 public class MemoryUsage
  80 {
  81
  82   /**
  83    * The initial amount of memory allocated.
  84    */
  85   private long init;
  86
  87   /**
  88    * The amount of memory used.
  89    */
  90   private long used;
  91
  92   /**
  93    * The amount of memory committed for use.
  94    */
  95   private long committed;
  96
  97   /**
  98    * The maximum amount of memory available.
  99    */
 100   private long maximum;
 101
 102   /**
 103    * Constructs a new {@link MemoryUsage} object with
 104    * the specified allocation levels.
 105    *
 106    * @param init the initial amount of memory allocated,
 107    *             or -1 if this value is undefined.  Must
 108    *             be >= -1.
 109    * @param used the amount of memory used.  Must be >= 0,
 110    *             and <= committed.
 111    * @param committed the amount of memory committed for use
 112    *                  at present.  Must be >= 0 and <=
 113    *                  maximum (if defined).
 114    * @param maximum the maximum amount of memory that may be
 115    *                used, or -1 if this value is undefined.
 116    *                Must be >= -1.
 117    * @throws IllegalArgumentException if the values break any
 118    *                                  of the limits specified
 119    *                                  above.
 120    */
 121   public MemoryUsage(long init, long used, long committed,
 122                      long maximum)
 123   {
 124     if (init < -1)
 125       throw new IllegalArgumentException("Initial value of "
 126                                          + init + " is too small.");
 127     if (used < 0)
 128       throw new IllegalArgumentException("Used value of "
 129                                          + used + " is too small.");
 130     if (committed < 0)
 131       throw new IllegalArgumentException("Committed value of "
 132                                          + committed + " is too small.");
 133     if (committed < used)
 134       throw new IllegalArgumentException("Committed value of "
 135                                          + committed + " is below "
 136                                          + used + ", the amount used.");
 137     if (maximum < -1)
 138       throw new IllegalArgumentException("Maximum value of "
 139                                          + maximum + " is too small.");
 140     if (maximum != -1 && maximum < committed)
 141       throw new IllegalArgumentException("Maximum value of "
 142                                          + maximum + " is below "
 143                                          + committed + ", the amount "
 144                                          + "committed.");
 145     this.init = init;
 146     this.used = used;
 147     this.committed = committed;
 148     this.maximum = maximum;
 149   }
 150
 151   /**
 152    * <p>
 153    * Returns a {@link MemoryUsage} instance using the values
 154    * given in the supplied
 155    * {@link javax.management.openmbean.CompositeData} object.
 156    * The composite data instance should contain the following
 157    * attributes:
 158    * </p>
 159    * <ul>
 160    * <li>init</li>
 161    * <li>used</li>
 162    * <li>committed</li>
 163    * <li>max</li>
 164    * </ul>
 165    * <p>
 166    * All should have the type, <code>java.lang.Long</code>.
 167    * </p>
 168    *
 169    * @param data the composite data structure to take values from.
 170    * @return a new instance containing the values from the
 171    *         composite data structure, or <code>null</code>
 172    *         if the data structure was also <code>null</code>.
 173    * @throws IllegalArgumentException if the composite data structure
 174    *                                  does not match the structure
 175    *                                  outlined above, or the values
 176    *                                  are invalid.
 177    */
 178   public static MemoryUsage from(CompositeData data)
 179   {
 180     if (data == null)
 181       return null;
 182     CompositeType type = data.getCompositeType();
 183     ThreadInfo.checkAttribute(type, "Init", SimpleType.LONG);
 184     ThreadInfo.checkAttribute(type, "Used", SimpleType.LONG);
 185     ThreadInfo.checkAttribute(type, "Committed", SimpleType.LONG);
 186     ThreadInfo.checkAttribute(type, "Max", SimpleType.LONG);
 187     return new MemoryUsage(((Long) data.get("Init")).longValue(),
 188                            ((Long) data.get("Used")).longValue(),
 189                            ((Long) data.get("Committed")).longValue(),
 190                            ((Long) data.get("Max")).longValue());
 191   }
 192
 193   /**
 194    * Returns the amount of memory committed for use by this
 195    * memory pool (in bytes).  This amount is guaranteed to
 196    * be available, unlike the maximum.
 197    *
 198    * @return the committed amount of memory.
 199    */
 200   public long getCommitted()
 201   {
 202     return committed;
 203   }
 204
 205   /**
 206    * Returns the initial amount of memory allocated to the
 207    * pool (in bytes).  This method may return -1, if the
 208    * value is undefined.
 209    *
 210    * @return the initial amount of memory allocated, or -1
 211    *         if this value is undefined.
 212    */
 213   public long getInit()
 214   {
 215     return init;
 216   }
 217
 218   /**
 219    * Returns the maximum amount of memory available for this
 220    * pool (in bytes).  This amount is not guaranteed to
 221    * actually be usable.  This method may return -1, if the
 222    * value is undefined.
 223    *
 224    * @return the maximum amount of memory available, or -1
 225    *         if this value is undefined.
 226    */
 227   public long getMax()
 228   {
 229     return maximum;
 230   }
 231
 232   /**
 233    * Returns the amount of memory used (in bytes).
 234    *
 235    * @return the amount of used memory.
 236    */
 237   public long getUsed()
 238   {
 239     return used;
 240   }
 241
 242   /**
 243    * Returns a {@link java.lang.String} representation of
 244    * this {@link MemoryUsage} object.  This takes the form
 245    * <code>java.lang.management.MemoryUsage[init=i, used=u,
 246    * committed=c, maximum=m]</code>, where <code>i</code>
 247    * is the initial level, <code>u</code> is the used level,
 248    * <code>c</code> is the committed level and <code>m</code>
 249    * is the maximum level.
 250    *
 251    * @return the string specified above.
 252    */
 253   public String toString()
 254   {
 255     int megabyte = 1024 * 1024;
 256     return getClass().getName() +
 257       "[init=" + init + " bytes (~" + (init / megabyte) +
 258       "MB), used=" + used + " bytes (~" + (used / megabyte) +
 259       "MB), committed=" + committed + " bytes (~" + (committed / megabyte) +
 260       "MB), maximum=" + maximum + " bytes (~" + (maximum / megabyte) +
 261       "MB)]";
 262   }
 263
 264 }
 265