libcore/dalvik/src/main/java/dalvik/system/VMRuntime.java

   1 /*
   2  * Copyright (C) 2007 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package dalvik.system;
  18
  19 /**
  20  * Provides an interface to VM-global, Dalvik-specific features.
  21  * An application cannot create its own Runtime instance, and must obtain
  22  * one from the getRuntime method.
  23  *
  24  * @since Android 1.0
  25  */
  26 public final class VMRuntime {
  27
  28     /**
  29      * Holds the VMRuntime singleton.
  30      */
  31     private static final VMRuntime THE_ONE = new VMRuntime();
  32
  33     /**
  34      * Prevents this class from being instantiated.
  35      */
  36     private VMRuntime() {
  37     }
  38
  39     /**
  40      * Returns the object that represents the VM instance's Dalvik-specific
  41      * runtime environment.
  42      *
  43      * @return the runtime object
  44      */
  45     public static VMRuntime getRuntime() {
  46         return THE_ONE;
  47     }
  48
  49     /**
  50      * Gets the current ideal heap utilization, represented as a number
  51      * between zero and one.  After a GC happens, the Dalvik heap may
  52      * be resized so that (size of live objects) / (size of heap) is
  53      * equal to this number.
  54      *
  55      * @return the current ideal heap utilization
  56      */
  57     public native float getTargetHeapUtilization();
  58
  59     /**
  60      * Sets the current ideal heap utilization, represented as a number
  61      * between zero and one.  After a GC happens, the Dalvik heap may
  62      * be resized so that (size of live objects) / (size of heap) is
  63      * equal to this number.
  64      *
  65      * @param newTarget the new suggested ideal heap utilization.
  66      *                  This value may be adjusted internally.
  67      * @return the previous ideal heap utilization
  68      * @throws IllegalArgumentException if newTarget is &lt;= 0.0 or &gt;= 1.0
  69      */
  70     public float setTargetHeapUtilization(float newTarget) {
  71         if (newTarget <= 0.0 || newTarget >= 1.0) {
  72             throw new IllegalArgumentException(newTarget +
  73                     " out of range (0,1)");
  74         }
  75         /* Synchronize to make sure that only one thread gets
  76          * a given "old" value if both update at the same time.
  77          * Allows for reliable save-and-restore semantics.
  78          */
  79         synchronized (this) {
  80             float oldTarget = getTargetHeapUtilization();
  81             nativeSetTargetHeapUtilization(newTarget);
  82             return oldTarget;
  83         }
  84     }
  85
  86     /**
  87      * Returns the minimum heap size, or zero if no minimum is in effect.
  88      *
  89      * @return the minimum heap size value
  90      */
  91     public long getMinimumHeapSize() {
  92         return nativeMinimumHeapSize(0, false);
  93     }
  94
  95     /**
  96      * Sets the desired minimum heap size, and returns the
  97      * old minimum size.  If size is larger than the maximum
  98      * size, the maximum size will be used.  If size is zero
  99      * or negative, the minimum size constraint will be removed.
 100      *
 101      * Synchronized to make the order of the exchange reliable.
 102      *
 103      * @param size the new suggested minimum heap size, in bytes
 104      * @return the old minimum heap size value
 105      */
 106     public synchronized long setMinimumHeapSize(long size) {
 107         return nativeMinimumHeapSize(size, true);
 108     }
 109
 110     /**
 111      * If set is true, sets the new minimum heap size to size; always
 112      * returns the current (or previous) size.
 113      *
 114      * @param size the new suggested minimum heap size, in bytes
 115      * @param set if true, set the size based on the size parameter,
 116      *            otherwise ignore it
 117      * @return the old or current minimum heap size value
 118      */
 119     private native long nativeMinimumHeapSize(long size, boolean set);
 120
 121     /**
 122      * Requests that the virtual machine collect available memory,
 123      * and collects any SoftReferences that are not strongly-reachable.
 124      */
 125     public native void gcSoftReferences();
 126
 127     /**
 128      * Does not return until any pending finalizers have been called.
 129      * This may or may not happen in the context of the calling thread.
 130      * No exceptions will escape.
 131      */
 132     public native void runFinalizationSync();
 133
 134     /**
 135      * Implements setTargetHeapUtilization().
 136      *
 137      * @param newTarget the new suggested ideal heap utilization.
 138      *                  This value may be adjusted internally.
 139      */
 140     private native void nativeSetTargetHeapUtilization(float newTarget);
 141
 142     /**
 143      * Asks the VM if &lt;size&gt; bytes can be allocated in an external heap.
 144      * This information may be used to limit the amount of memory available
 145      * to Dalvik threads.  Returns false if the VM would rather that the caller
 146      * did not allocate that much memory.  If the call returns false, the VM
 147      * will not update its internal counts.  May cause one or more GCs as a
 148      * side-effect.
 149      *
 150      * Called by JNI code.
 151      *
 152      * {@hide}
 153      *
 154      * @param size The number of bytes that have been allocated.
 155      * @return true if the VM thinks there's enough process memory
 156      *         to satisfy this request, or false if not.
 157      */
 158     public native boolean trackExternalAllocation(long size);
 159
 160     /**
 161      * Tells the VM that &lt;size&gt; bytes have been freed in an external
 162      * heap.  This information may be used to control the amount of memory
 163      * available to Dalvik threads.
 164      *
 165      * Called by JNI code.
 166      *
 167      * {@hide}
 168      *
 169      * @param size The number of bytes that have been freed.  This same number
 170      *             should have been passed to trackExternalAlloc() when
 171      *             the underlying memory was originally allocated.
 172      */
 173     public native void trackExternalFree(long size);
 174
 175     /**
 176      * Returns the number of externally-allocated bytes being tracked by
 177      * trackExternalAllocation/Free().
 178      *
 179      * @return the number of bytes
 180      */
 181     public native long getExternalBytesAllocated();
 182 }