dalvik/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 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  */
  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  */
  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_