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 /*
18 * Maintain a table of references. Used for internal local references,
19 * JNI monitor references, and JNI pinned array references.
20 *
21 * None of the table functions are synchronized.
22 */
23 #ifndef DALVIK_REFERENCETABLE_H_
24 #define DALVIK_REFERENCETABLE_H_
25
26 /*
27 * Table definition.
28 *
29 * The expected common operations are adding a new entry and removing a
30 * recently-added entry (usually the most-recently-added entry).
31 *
32 * If "allocEntries" is not equal to "maxEntries", the table may expand when
33 * entries are added, which means the memory may move. If you want to keep
34 * pointers into "table" rather than offsets, use a fixed-size table.
35 *
36 * (This structure is still somewhat transparent; direct access to
37 * table/nextEntry is allowed.)
38 */
39 struct ReferenceTable {
40 Object** nextEntry; /* top of the list */
41 Object** table; /* bottom of the list */
42
43 int allocEntries; /* #of entries we have space for */
44 int maxEntries; /* max #of entries allowed */
45 };
46
47 /*
48 * Initialize a ReferenceTable.
49 *
50 * If "initialCount" != "maxCount", the table will expand as required.
51 *
52 * Returns "false" if table allocation fails.
53 */
54 bool dvmInitReferenceTable(ReferenceTable* pRef, int initialCount,
55 int maxCount);
56
57 /*
58 * Clears out the contents of a ReferenceTable, freeing allocated storage.
59 * Does not free "pRef".
60 *
61 * You must call dvmInitReferenceTable() before you can re-use this table.
62 */
63 void dvmClearReferenceTable(ReferenceTable* pRef);
64
65 /*
66 * Return the #of entries currently stored in the ReferenceTable.
67 */
dvmReferenceTableEntries(const ReferenceTable * pRef)68 INLINE size_t dvmReferenceTableEntries(const ReferenceTable* pRef)
69 {
70 return pRef->nextEntry - pRef->table;
71 }
72
73 /*
74 * Returns "true" if the table is full. The table is considered full if
75 * we would need to expand it to add another entry.
76 */
dvmIsReferenceTableFull(const ReferenceTable * pRef)77 INLINE size_t dvmIsReferenceTableFull(const ReferenceTable* pRef)
78 {
79 return dvmReferenceTableEntries(pRef) == (size_t)pRef->allocEntries;
80 }
81
82 /*
83 * Add a new entry. "obj" must be a valid non-NULL object reference
84 * (though it's okay if it's not fully-formed, e.g. the result from
85 * dvmMalloc doesn't have obj->clazz set).
86 *
87 * Returns "false" if the table is full.
88 */
89 bool dvmAddToReferenceTable(ReferenceTable* pRef, Object* obj);
90
91 /*
92 * Determine if "obj" is present in "pRef". Stops searching when we hit
93 * "bottom". To include the entire table, pass in "pRef->table" as the
94 * bottom.
95 *
96 * Returns NULL if "obj" was not found.
97 */
98 Object** dvmFindInReferenceTable(const ReferenceTable* pRef, Object** bottom,
99 Object* obj);
100
101 /*
102 * Remove an existing entry.
103 *
104 * We stop searching for a match after examining the element at "bottom".
105 * This is useful when entries are associated with a stack frame.
106 *
107 * Returns "false" if the entry was not found.
108 */
109 bool dvmRemoveFromReferenceTable(ReferenceTable* pRef, Object** bottom,
110 Object* obj);
111
112 /*
113 * Dump the contents of a reference table to the log file.
114 *
115 * The caller should lock any external sync before calling.
116 */
117 void dvmDumpReferenceTable(const ReferenceTable* pRef, const char* descr);
118
119 /*
120 * Internal function, shared with IndirectRefTable.
121 */
122 void dvmDumpReferenceTableContents(Object* const* refs, size_t count,
123 const char* descr);
124
125 #endif // DALVIK_REFERENCETABLE_H_
126