vm/ReferenceTable.h

   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
  27 extern "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  */
  43 typedef 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  */
  58 bool 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  */
  67 void dvmClearReferenceTable(ReferenceTable* pRef);
  68
  69 /*
  70  * Return the #of entries currently stored in the ReferenceTable.
  71  */
  72 INLINE 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  */
  81 INLINE 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  */
  93 bool 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  */
 102 Object** 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  */
 113 bool 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  */
 121 void dvmDumpReferenceTable(const ReferenceTable* pRef, const char* descr);
 122
 123 /*
 124  * Internal function, shared with IndirectRefTable.
 125  */
 126 void dvmDumpReferenceTableContents(Object* const* refs, size_t count,
 127     const char* descr);
 128
 129 #ifdef __cplusplus
 130 }
 131 #endif
 132
 133 #endif /*_DALVIK_REFERENCETABLE*/