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 * @deprecated this is an internal Dalvik class that is not appropriate for 25 * general use. It will be removed from the public API in a future release. 26 * 27 * @since Android 1.0 28 */ 29 public final class VMRuntime { 30 31 /** 32 * Holds the VMRuntime singleton. 33 */ 34 private static final VMRuntime THE_ONE = new VMRuntime(); 35 36 /** 37 * Prevents this class from being instantiated. 38 */ 39 private VMRuntime() { 40 } 41 42 /** 43 * Returns the object that represents the VM instance's Dalvik-specific 44 * runtime environment. 45 * 46 * @return the runtime object 47 */ 48 public static VMRuntime getRuntime() { 49 return THE_ONE; 50 } 51 52 /** 53 * Gets the current ideal heap utilization, represented as a number 54 * between zero and one. After a GC happens, the Dalvik heap may 55 * be resized so that (size of live objects) / (size of heap) is 56 * equal to this number. 57 * 58 * @return the current ideal heap utilization 59 */ 60 public native float getTargetHeapUtilization(); 61 62 /** 63 * Sets the current ideal heap utilization, represented as a number 64 * between zero and one. After a GC happens, the Dalvik heap may 65 * be resized so that (size of live objects) / (size of heap) is 66 * equal to this number. 67 * 68 * <p>This is only a hint to the garbage collector and may be ignored. 69 * 70 * @param newTarget the new suggested ideal heap utilization. 71 * This value may be adjusted internally. 72 * @return the previous ideal heap utilization 73 * @throws IllegalArgumentException if newTarget is <= 0.0 or >= 1.0 74 */ 75 public float setTargetHeapUtilization(float newTarget) { 76 if (newTarget <= 0.0 || newTarget >= 1.0) { 77 throw new IllegalArgumentException(newTarget + 78 " out of range (0,1)"); 79 } 80 /* Synchronize to make sure that only one thread gets 81 * a given "old" value if both update at the same time. 82 * Allows for reliable save-and-restore semantics. 83 */ 84 synchronized (this) { 85 float oldTarget = getTargetHeapUtilization(); 86 nativeSetTargetHeapUtilization(newTarget); 87 return oldTarget; 88 } 89 } 90 91 /** 92 * Returns the minimum heap size, or zero if no minimum is in effect. 93 * 94 * @return the minimum heap size value 95 */ 96 public long getMinimumHeapSize() { 97 return nativeMinimumHeapSize(0, false); 98 } 99 100 /** 101 * Sets the desired minimum heap size, and returns the 102 * old minimum size. If size is larger than the maximum 103 * size, the maximum size will be used. If size is zero 104 * or negative, the minimum size constraint will be removed. 105 * 106 * <p>Synchronized to make the order of the exchange reliable. 107 * 108 * <p>This is only a hint to the garbage collector and may be ignored. 109 * 110 * @param size the new suggested minimum heap size, in bytes 111 * @return the old minimum heap size value 112 */ 113 public synchronized long setMinimumHeapSize(long size) { 114 return nativeMinimumHeapSize(size, true); 115 } 116 117 /** 118 * If set is true, sets the new minimum heap size to size; always 119 * returns the current (or previous) size. 120 * 121 * @param size the new suggested minimum heap size, in bytes 122 * @param set if true, set the size based on the size parameter, 123 * otherwise ignore it 124 * @return the old or current minimum heap size value 125 */ 126 private native long nativeMinimumHeapSize(long size, boolean set); 127 128 /** 129 * Requests that the virtual machine collect available memory, 130 * and collects any SoftReferences that are not strongly-reachable. 131 */ 132 public native void gcSoftReferences(); 133 134 /** 135 * Does not return until any pending finalizers have been called. 136 * This may or may not happen in the context of the calling thread. 137 * No exceptions will escape. 138 */ 139 public native void runFinalizationSync(); 140 141 /** 142 * Implements setTargetHeapUtilization(). 143 * 144 * @param newTarget the new suggested ideal heap utilization. 145 * This value may be adjusted internally. 146 */ 147 private native void nativeSetTargetHeapUtilization(float newTarget); 148 149 /** 150 * Asks the VM if <size> bytes can be allocated in an external heap. 151 * This information may be used to limit the amount of memory available 152 * to Dalvik threads. Returns false if the VM would rather that the caller 153 * did not allocate that much memory. If the call returns false, the VM 154 * will not update its internal counts. May cause one or more GCs as a 155 * side-effect. 156 * 157 * Called by JNI code. 158 * 159 * {@hide} 160 * 161 * @param size The number of bytes that have been allocated. 162 * @return true if the VM thinks there's enough process memory 163 * to satisfy this request, or false if not. 164 */ 165 public native boolean trackExternalAllocation(long size); 166 167 /** 168 * Tells the VM that <size> bytes have been freed in an external 169 * heap. This information may be used to control the amount of memory 170 * available to Dalvik threads. 171 * 172 * Called by JNI code. 173 * 174 * {@hide} 175 * 176 * @param size The number of bytes that have been freed. This same number 177 * should have been passed to trackExternalAlloc() when 178 * the underlying memory was originally allocated. 179 */ 180 public native void trackExternalFree(long size); 181 182 /** 183 * Returns the number of externally-allocated bytes being tracked by 184 * trackExternalAllocation/Free(). 185 * 186 * @return the number of bytes 187 */ 188 public native long getExternalBytesAllocated(); 189 190 /** 191 * Tells the VM to enable the JIT compiler. If the VM does not have a JIT 192 * implementation, calling this method should have no effect. 193 * 194 * {@hide} 195 */ 196 public native void startJitCompilation(); 197 198 /** 199 * Tells the VM to disable the JIT compiler. If the VM does not have a JIT 200 * implementation, calling this method should have no effect. 201 * 202 * {@hide} 203 */ 204 public native void disableJitCompilation(); 205 } 206
