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