Alloc.h revision 364f9d924cbd9d392744a66f80cc084c3d80caf0 
1/*
2 * Copyright (C) 2008 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 * Garbage-collecting allocator.
18 */
19#ifndef _DALVIK_ALLOC_ALLOC
20#define _DALVIK_ALLOC_ALLOC
21
22#include <stddef.h>
23
24/*
25 * Initialization.
26 */
27bool dvmGcStartup(void);
28bool dvmCreateStockExceptions(void);
29bool dvmGcStartupAfterZygote(void);
30void dvmGcShutdown(void);
31
32/*
33 * Do any last-minute preparation before we call fork() for the first time.
34 */
35bool dvmGcPreZygoteFork(void);
36
37/*
38 * Basic allocation function.
39 *
40 * The new object will be added to the "tracked alloc" table unless
41 * flags is ALLOC_DONT_TRACK.
42 *
43 * Returns NULL and throws an exception on failure.
44 */
45void* dvmMalloc(size_t size, int flags);
46
47/*
48 * Allocate a new object.
49 *
50 * The new object will be added to the "tracked alloc" table unless
51 * flags is ALLOC_DONT_TRACK.
52 *
53 * Returns NULL and throws an exception on failure.
54 */
55Object* dvmAllocObject(ClassObject* clazz, int flags);
56
57/* flags for dvmMalloc */
58enum {
59    ALLOC_DEFAULT       = 0x00,
60    ALLOC_DONT_TRACK    = 0x01,     /* don't add to internal tracking list */
61    ALLOC_FINALIZABLE   = 0x02,     /* call finalize() before freeing */
62};
63
64/*
65 * Call when a request is so far off that we can't call dvmMalloc().  Throws
66 * an exception with the specified message.
67 */
68void dvmThrowBadAllocException(const char* msg);
69
70/*
71 * Track an object reference that is currently only visible internally.
72 * This is called automatically by dvmMalloc() unless ALLOC_DONT_TRACK
73 * is set.
74 *
75 * The "self" argument is allowed as an optimization; it may be NULL.
76 */
77void dvmAddTrackedAlloc(Object* obj, Thread* self);
78
79/*
80 * Remove an object from the internal tracking list.
81 *
82 * Does nothing if "obj" is NULL.
83 *
84 * The "self" argument is allowed as an optimization; it may be NULL.
85 */
86void dvmReleaseTrackedAlloc(Object* obj, Thread* self);
87
88/*
89 * Returns true iff <obj> points to a valid allocated object.
90 */
91bool dvmIsValidObject(const Object* obj);
92
93/*
94 * Returns true iff <ptr> points within allocation-managed address space.
95 */
96bool dvmIsValidObjectAddress(const void *ptr);
97
98/*
99 * Create a copy of an object.
100 *
101 * The new object will be added to the "tracked alloc" table.
102 */
103Object* dvmCloneObject(Object* obj);
104
105/*
106 * Validate the object pointer.  Returns "false" and throws an exception if
107 * "obj" is null or invalid.
108 *
109 * This may be used in performance critical areas as a null-pointer check;
110 * anything else here should be for debug builds only.  In particular, for
111 * "release" builds we want to skip the call to dvmIsValidObject() -- the
112 * classfile validation will screen out code that puts invalid data into
113 * object reference registers.
114 */
115INLINE int dvmValidateObject(Object* obj)
116{
117    if (obj == NULL) {
118        dvmThrowException("Ljava/lang/NullPointerException;", NULL);
119        return false;
120    }
121#ifdef WITH_EXTRA_OBJECT_VALIDATION
122    if (!dvmIsValidObject(obj)) {
123        dvmAbort();
124        dvmThrowException("Ljava/lang/InternalError;",
125            "VM detected invalid object ptr");
126        return false;
127    }
128#endif
129#ifndef NDEBUG
130    /* check for heap corruption */
131    if (obj->clazz == NULL || ((u4) obj->clazz) <= 65536) {
132        dvmAbort();
133        dvmThrowException("Ljava/lang/InternalError;",
134            "VM detected invalid object class ptr");
135        return false;
136    }
137#endif
138    return true;
139}
140
141/*
142 * Determine the exact number of GC heap bytes used by an object.  (Internal
143 * to heap code except for debugging.)
144 */
145size_t dvmObjectSizeInHeap(const Object* obj);
146
147/*
148 * Gets the current ideal heap utilization, represented as a number
149 * between zero and one.
150 */
151float dvmGetTargetHeapUtilization(void);
152
153/*
154 * Sets the new ideal heap utilization, represented as a number
155 * between zero and one.
156 */
157void dvmSetTargetHeapUtilization(float newTarget);
158
159/*
160 * If set is true, sets the new minimum heap size to size; always
161 * returns the current (or previous) size.  If size is zero,
162 * removes the current minimum constraint (if present).
163 */
164size_t dvmMinimumHeapSize(size_t size, bool set);
165
166/*
167 * Updates the internal count of externally-allocated memory.  If there's
168 * enough room for that memory, returns true.  If not, returns false and
169 * does not update the count.
170 *
171 * May cause a GC as a side-effect.
172 */
173bool dvmTrackExternalAllocation(size_t n);
174
175/*
176 * Reduces the internal count of externally-allocated memory.
177 */
178void dvmTrackExternalFree(size_t n);
179
180/*
181 * Returns the number of externally-allocated bytes being tracked by
182 * dvmTrackExternalAllocation/Free().
183 */
184size_t dvmGetExternalBytesAllocated(void);
185
186#endif /*_DALVIK_ALLOC_ALLOC*/
187