src/vm/classcache.h

   1 /* src/vm/classcache.h - loaded class cache and loading constraints
   2
   3    Copyright (C) 1996-2005 R. Grafl, A. Krall, C. Kruegel, C. Oates,
   4    R. Obermaisser, M. Platter, M. Probst, S. Ring, E. Steiner,
   5    C. Thalinger, D. Thuernbeck, P. Tomsich, C. Ullrich, J. Wenninger,
   6    Institut f. Computersprachen - TU Wien
   7
   8    This file is part of CACAO.
   9
  10    This program is free software; you can redistribute it and/or
  11    modify it under the terms of the GNU General Public License as
  12    published by the Free Software Foundation; either version 2, or (at
  13    your option) any later version.
  14
  15    This program is distributed in the hope that it will be useful, but
  16    WITHOUT ANY WARRANTY; without even the implied warranty of
  17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18    General Public License for more details.
  19
  20    You should have received a copy of the GNU General Public License
  21    along with this program; if not, write to the Free Software
  22    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  23    02111-1307, USA.
  24
  25    Contact: cacao@complang.tuwien.ac.at
  26
  27    Authors: Edwin Steiner
  28
  29    Changes:
  30
  31    $Id: classcache.h 2725 2005-06-16 19:10:35Z edwin $
  32
  33 */
  34
  35
  36 #ifndef _CLASSCACHE_H
  37 #define _CLASSCACHE_H
  38
  39 #include <stdio.h>  /* for FILE */
  40
  41 #include "vm/references.h"
  42 #include "vm/tables.h"
  43
  44
  45 /* forward declarations *******************************************************/
  46
  47 typedef struct classcache_name_entry classcache_name_entry;
  48 typedef struct classcache_class_entry classcache_class_entry;
  49 typedef struct classcache_loader_entry classcache_loader_entry;
  50
  51 typedef java_objectheader classloader;
  52
  53 /* global variables ***********************************************************/
  54
  55 extern hashtable classcache_hash;
  56
  57 /* structs ********************************************************************/
  58
  59
  60 /*----------------------------------------------------------------------------*/
  61 /* The Loaded Class Cache                                                     */
  62 /*                                                                            */
  63 /* The loaded class cache is implemented as a two-level data structure.       */
  64 /*                                                                            */
  65 /* The first level is a hash table indexed by class names. For each class     */
  66 /* name in the cache there is a classcache_name_entry, which collects all     */
  67 /* information about classes with this class name.                            */
  68 /*                                                                            */
  69 /* Second level: For each classcache_name_entry there is a list of            */
  70 /* classcache_class_entry:s representing the possible different resolutions   */
  71 /* of the class name.                                                         */
  72 /*                                                                            */
  73 /* A classcache_class_entry records the following:                            */
  74 /*                                                                            */
  75 /* - the loaded class object, if this entry has been resolved, otherwise NULL */
  76 /* - the list of initiating loaders which have resolved the class name to     */
  77 /*   this class object                                                        */
  78 /* - the list of initiating loaders which are constrained to resolve this     */
  79 /*   class name to this class object in the future                            */
  80 /*                                                                            */
  81 /* The classcache_class_entry:s approximate the equivalence classes created   */
  82 /* by the loading constraints and (XXX?) the equivalence of loaded classes.   */
  83 /*                                                                            */
  84 /* When a loading constraint (loaderA,loaderB,NAME) is added, then the        */
  85 /* classcache_class_entry:s for NAME containing loaderA and loaderB resp.     */
  86 /* must be merged into one entry. If this is impossible, because the entries  */
  87 /* have already been resolved to different class objects, then the constraint */
  88 /* is violated and an expception must be thrown.                              */
  89 /*----------------------------------------------------------------------------*/
  90
  91
  92 /* classcache_name_entry
  93  *
  94  * For each classname a classcache_name_entry struct is created.
  95  */
  96
  97 struct classcache_name_entry
  98 {
  99         utf                     *name;        /* class name                       */
 100         classcache_name_entry   *hashlink;        /* link for external chaining       */
 101         classcache_class_entry  *classes;     /* equivalence classes for this name*/
 102 };
 103
 104 struct classcache_class_entry
 105 {
 106         classinfo               *classobj;    /* the loaded class object, or NULL */
 107         classcache_loader_entry *loaders;
 108         classcache_loader_entry *constraints;
 109         classcache_class_entry  *next;        /* next class entry for same name   */
 110 };
 111
 112 struct classcache_loader_entry
 113 {
 114         classloader              *loader;     /* class loader object              */
 115         classcache_loader_entry  *next;       /* next loader entry in the list    */
 116 };
 117
 118 /* function prototypes ********************************************************/
 119
 120 /* classcache_init *************************************************************
 121
 122    Initialize the loaded class cache
 123
 124 *******************************************************************************/
 125
 126 void classcache_init();
 127
 128 /* classcache_free *************************************************************
 129
 130    Free the memory used by the class cache
 131
 132    NOTE:
 133        The class cache may not be used any more after this call, except
 134            when it is reinitialized with classcache_init.
 135
 136 *******************************************************************************/
 137
 138 void classcache_free();
 139
 140 /* classcache_lookup ***********************************************************
 141
 142    Lookup a possibly loaded class
 143
 144    IN:
 145        initloader.......initiating loader for resolving the class name
 146        classname........class name to look up
 147
 148    RETURN VALUE:
 149        The return value is a pointer to the cached class object,
 150        or NULL, if the class is not in the cache.
 151
 152 *******************************************************************************/
 153
 154 classinfo * classcache_lookup(classloader *initloader,utf *classname);
 155
 156 /* classcache_lookup_defined ***************************************************
 157
 158    Lookup a class with the given name and defining loader
 159
 160    IN:
 161        defloader........defining loader
 162        classname........class name
 163
 164    RETURN VALUE:
 165        The return value is a pointer to the cached class object,
 166        or NULL, if the class is not in the cache.
 167
 168 *******************************************************************************/
 169
 170 classinfo * classcache_lookup_defined(classloader *defloader,utf *classname);
 171
 172 /* classcache_store_unique *****************************************************
 173
 174    Store a loaded class as loaded by the bootstrap loader. This is a wrapper
 175    aroung classcache_store that throws an exception if a class with the same
 176    name has already been loaded by the bootstrap loader.
 177
 178    This function is used to register a few special classes during startup.
 179    It should not be used otherwise.
 180
 181    IN:
 182        cls..............class object to cache
 183
 184    RETURN VALUE:
 185        true.............everything ok, the class was stored.
 186        false............an exception has been thrown.
 187
 188    Note: synchronized with global tablelock
 189
 190 *******************************************************************************/
 191
 192 bool classcache_store_unique(classinfo *cls);
 193
 194 /* classcache_store ************************************************************
 195
 196    Store a loaded class. If a class of the same name has already been stored
 197    with the same initiating loader, then the given class CLS is freed (if
 198    possible) and the previously stored class is returned.
 199
 200    IN:
 201        initloader.......initiating loader used to load the class
 202                             (may be NULL indicating the bootstrap loader)
 203        cls..............class object to cache
 204            mayfree..........true if CLS may be freed in case another class is
 205                             returned
 206
 207    RETURN VALUE:
 208        cls..............everything ok, the class was stored in the cache,
 209            other classinfo..another class with the same (initloader,name) has been
 210                             stored earlier. CLS has been freed and the earlier
 211                                                 stored class is returned.
 212        NULL.............an exception has been thrown.
 213
 214    Note: synchronized with global tablelock
 215
 216 *******************************************************************************/
 217
 218 classinfo * classcache_store(classloader *initloader,classinfo *cls,bool mayfree);
 219
 220 /* classcache_store_defined ****************************************************
 221
 222    Store a loaded class after it has been defined. If the class has already
 223    been defined by the same defining loader in another thread, free the given
 224    class and returned the one which has been defined earlier.
 225
 226    IN:
 227        cls..............class object to store. classloader must be set
 228                             (classloader may be NULL, for bootloader)
 229
 230    RETURN VALUE:
 231        cls..............everything ok, the class was stored the cache,
 232            other classinfo..the class had already been defined, CLS was freed, the
 233                             class which was defined earlier is returned,
 234        NULL.............an exception has been thrown.
 235
 236 *******************************************************************************/
 237
 238 classinfo * classcache_store_defined(classinfo *cls);
 239
 240 /* classcache_add_constraint ***************************************************
 241
 242    Add a loading constraint
 243
 244    IN:
 245        a................first initiating loader
 246        b................second initiating loader
 247        classname........class name
 248
 249    RETURN VALUE:
 250        true.............everything ok, the constraint has been added,
 251        false............an exception has been thrown.
 252
 253 *******************************************************************************/
 254
 255 bool classcache_add_constraint(classloader *a,classloader *b,utf *classname);
 256
 257 /* classcache_debug_dump *******************************************************
 258
 259    Print the contents of the loaded class cache to a stream
 260
 261    IN:
 262        file.............output stream
 263
 264 *******************************************************************************/
 265
 266 void classcache_debug_dump(FILE *file);
 267
 268 #endif /* _CLASSCACHE_H */
 269
 270 /*
 271  * These are local overrides for various environment variables in Emacs.
 272  * Please do not remove this and leave it at the end of the file, where
 273  * Emacs will automagically detect them.
 274  * ---------------------------------------------------------------------
 275  * Local variables:
 276  * mode: c
 277  * indent-tabs-mode: t
 278  * c-basic-offset: 4
 279  * tab-width: 4
 280  * End:
 281  * vim:noexpandtab:sw=4:ts=4:
 282  */
 283