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 * @hide 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 * <p>This is only a hint to the garbage collector and may be ignored. 66 * 67 * @param newTarget the new suggested ideal heap utilization. 68 * This value may be adjusted internally. 69 * @return the previous ideal heap utilization 70 * @throws IllegalArgumentException if newTarget is <= 0.0 or >= 1.0 71 */ 72 public float setTargetHeapUtilization(float newTarget) { 73 if (newTarget <= 0.0 || newTarget >= 1.0) { 74 throw new IllegalArgumentException(newTarget + 75 " out of range (0,1)"); 76 } 77 /* Synchronize to make sure that only one thread gets 78 * a given "old" value if both update at the same time. 79 * Allows for reliable save-and-restore semantics. 80 */ 81 synchronized (this) { 82 float oldTarget = getTargetHeapUtilization(); 83 nativeSetTargetHeapUtilization(newTarget); 84 return oldTarget; 85 } 86 } 87 88 /** 89 * Returns the minimum heap size, or zero if no minimum is in effect. 90 * 91 * @return the minimum heap size value 92 */ 93 public long getMinimumHeapSize() { 94 return nativeMinimumHeapSize(0, false); 95 } 96 97 /** 98 * Sets the desired minimum heap size, and returns the 99 * old minimum size. If size is larger than the maximum 100 * size, the maximum size will be used. If size is zero 101 * or negative, the minimum size constraint will be removed. 102 * 103 * <p>Synchronized to make the order of the exchange reliable. 104 * 105 * <p>This is only a hint to the garbage collector and may be ignored. 106 * 107 * @param size the new suggested minimum heap size, in bytes 108 * @return the old minimum heap size value 109 */ 110 public synchronized long setMinimumHeapSize(long size) { 111 return nativeMinimumHeapSize(size, true); 112 } 113 114 /** 115 * If set is true, sets the new minimum heap size to size; always 116 * returns the current (or previous) size. 117 * 118 * @param size the new suggested minimum heap size, in bytes 119 * @param set if true, set the size based on the size parameter, 120 * otherwise ignore it 121 * @return the old or current minimum heap size value 122 */ 123 private native long nativeMinimumHeapSize(long size, boolean set); 124 125 /** 126 * Requests that the virtual machine collect available memory, 127 * and collects any SoftReferences that are not strongly-reachable. 128 */ 129 public native void gcSoftReferences(); 130 131 /** 132 * Does not return until any pending finalizers have been called. 133 * This may or may not happen in the context of the calling thread. 134 * No exceptions will escape. 135 */ 136 public native void runFinalizationSync(); 137 138 /** 139 * Implements setTargetHeapUtilization(). 140 * 141 * @param newTarget the new suggested ideal heap utilization. 142 * This value may be adjusted internally. 143 */ 144 private native void nativeSetTargetHeapUtilization(float newTarget); 145 146 /** 147 * Asks the VM if <size> bytes can be allocated in an external heap. 148 * This information may be used to limit the amount of memory available 149 * to Dalvik threads. Returns false if the VM would rather that the caller 150 * did not allocate that much memory. If the call returns false, the VM 151 * will not update its internal counts. May cause one or more GCs as a 152 * side-effect. 153 * 154 * Called by JNI code. 155 * 156 * {@hide} 157 * 158 * @param size The number of bytes that have been allocated. 159 * @return true if the VM thinks there's enough process memory 160 * to satisfy this request, or false if not. 161 */ 162 @Deprecated 163 public native boolean trackExternalAllocation(long size); 164 165 /** 166 * Tells the VM that <size> bytes have been freed in an external 167 * heap. This information may be used to control the amount of memory 168 * available to Dalvik threads. 169 * 170 * Called by JNI code. 171 * 172 * {@hide} 173 * 174 * @param size The number of bytes that have been freed. This same number 175 * should have been passed to trackExternalAlloc() when 176 * the underlying memory was originally allocated. 177 */ 178 @Deprecated 179 public native void trackExternalFree(long size); 180 181 /** 182 * Returns the number of externally-allocated bytes being tracked by 183 * trackExternalAllocation/Free(). 184 * 185 * @return the number of bytes 186 */ 187 @Deprecated 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
