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
17package 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 */
26public 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     * Returns a copy of the VM's command-line property settings.
51     * These are in the form "name=value" rather than "-Dname=value".
52     */
53    public native String[] properties();
54
55    /**
56     * Returns the VM's boot class path.
57     */
58    public native String bootClassPath();
59
60    /**
61     * Returns the VM's class path.
62     */
63    public native String classPath();
64
65    /**
66     * Returns the VM's version.
67     */
68    public native String vmVersion();
69
70    /**
71     * Returns the name of the shared library providing the VM implementation.
72     */
73    public native String vmLibrary();
74
75    /**
76     * Gets the current ideal heap utilization, represented as a number
77     * between zero and one.  After a GC happens, the Dalvik heap may
78     * be resized so that (size of live objects) / (size of heap) is
79     * equal to this number.
80     *
81     * @return the current ideal heap utilization
82     */
83    public native float getTargetHeapUtilization();
84
85    /**
86     * Sets the current ideal heap utilization, represented as a number
87     * between zero and one.  After a GC happens, the Dalvik heap may
88     * be resized so that (size of live objects) / (size of heap) is
89     * equal to this number.
90     *
91     * <p>This is only a hint to the garbage collector and may be ignored.
92     *
93     * @param newTarget the new suggested ideal heap utilization.
94     *                  This value may be adjusted internally.
95     * @return the previous ideal heap utilization
96     * @throws IllegalArgumentException if newTarget is &lt;= 0.0 or &gt;= 1.0
97     */
98    public float setTargetHeapUtilization(float newTarget) {
99        if (newTarget <= 0.0f || newTarget >= 1.0f) {
100            throw new IllegalArgumentException(newTarget +
101                    " out of range (0,1)");
102        }
103        /* Synchronize to make sure that only one thread gets
104         * a given "old" value if both update at the same time.
105         * Allows for reliable save-and-restore semantics.
106         */
107        synchronized (this) {
108            float oldTarget = getTargetHeapUtilization();
109            nativeSetTargetHeapUtilization(newTarget);
110            return oldTarget;
111        }
112    }
113
114    /**
115     * Sets the target SDK version. Should only be called before the
116     * app starts to run, because it may change the VM's behavior in
117     * dangerous ways. Use 0 to mean "current" (since callers won't
118     * necessarily know the actual current SDK version, and the
119     * allocated version numbers start at 1).
120     */
121    public native void setTargetSdkVersion(int targetSdkVersion);
122
123    /**
124     * This method exists for binary compatibility.  It was part of a
125     * heap sizing API which was removed in Android 3.0 (Honeycomb).
126     */
127    @Deprecated
128    public long getMinimumHeapSize() {
129        return 0;
130    }
131
132    /**
133     * This method exists for binary compatibility.  It was part of a
134     * heap sizing API which was removed in Android 3.0 (Honeycomb).
135     */
136    @Deprecated
137    public long setMinimumHeapSize(long size) {
138        return 0;
139    }
140
141    /**
142     * This method exists for binary compatibility.  It used to
143     * perform a garbage collection that cleared SoftReferences.
144     */
145    @Deprecated
146    public void gcSoftReferences() {}
147
148    /**
149     * This method exists for binary compatibility.  It is equivalent
150     * to {@link System#runFinalization}.
151     */
152    @Deprecated
153    public void runFinalizationSync() {
154        System.runFinalization();
155    }
156
157    /**
158     * Implements setTargetHeapUtilization().
159     *
160     * @param newTarget the new suggested ideal heap utilization.
161     *                  This value may be adjusted internally.
162     */
163    private native void nativeSetTargetHeapUtilization(float newTarget);
164
165    /**
166     * This method exists for binary compatibility.  It was part of
167     * the external allocation API which was removed in Android 3.0 (Honeycomb).
168     */
169    @Deprecated
170    public boolean trackExternalAllocation(long size) {
171        return true;
172    }
173
174    /**
175     * This method exists for binary compatibility.  It was part of
176     * the external allocation API which was removed in Android 3.0 (Honeycomb).
177     */
178    @Deprecated
179    public void trackExternalFree(long size) {}
180
181    /**
182     * This method exists for binary compatibility.  It was part of
183     * the external allocation API which was removed in Android 3.0 (Honeycomb).
184     */
185    @Deprecated
186    public long getExternalBytesAllocated() {
187        return 0;
188    }
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    public native void startJitCompilation();
195
196    /**
197     * Tells the VM to disable the JIT compiler. If the VM does not have a JIT
198     * implementation, calling this method should have no effect.
199     */
200    public native void disableJitCompilation();
201
202    /**
203     * Returns an array allocated in an area of the Java heap where it will never be moved.
204     * This is used to implement native allocations on the Java heap, such as DirectByteBuffers
205     * and Bitmaps.
206     */
207    public native Object newNonMovableArray(Class<?> componentType, int length);
208
209    /**
210     * Returns the address of array[0]. This differs from using JNI in that JNI might lie and
211     * give you the address of a copy of the array when in forcecopy mode.
212     */
213    public native long addressOf(Object array);
214
215    /**
216     * Removes any growth limits, allowing the application to allocate
217     * up to the maximum heap size.
218     */
219    public native void clearGrowthLimit();
220
221    /**
222     * Returns true if either a Java debugger or native debugger is active.
223     */
224    public native boolean isDebuggerActive();
225
226    /**
227     * Registers a native allocation so that the heap knows about it and performs GC as required.
228     * If the number of native allocated bytes exceeds the native allocation watermark, the
229     * function requests a concurrent GC. If the native bytes allocated exceeds a second higher
230     * watermark, it is determined that the application is registering native allocations at an
231     * unusually high rate and a GC is performed inside of the function to prevent memory usage
232     * from excessively increasing.
233     */
234    public native void registerNativeAllocation(int bytes);
235
236    /**
237     * Registers a native free by reducing the number of native bytes accounted for.
238     */
239    public native void registerNativeFree(int bytes);
240
241    public native void trimHeap();
242    public native void concurrentGC();
243
244    public void preloadDexCaches() {
245        // Do nothing with ART, image generation already does this.
246    }
247}
248