src/vm/descriptor.h

   1 /* vm/descriptor.h - checking and parsing of field / method descriptors
   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: descriptor.h 2112 2005-03-29 21:29:08Z twisti $
  32
  33 */
  34
  35
  36 #ifndef _DESCRIPTOR_H
  37 #define _DESCRIPTOR_H
  38
  39 /* forward typedefs ***********************************************************/
  40
  41 typedef struct descriptor_pool descriptor_pool;
  42 typedef struct typedesc typedesc;
  43 typedef struct methoddesc methoddesc;
  44 typedef union parseddesc parseddesc;
  45
  46
  47 #include "types.h"
  48 #include "vm/class.h"
  49 #include "vm/global.h"
  50 #include "vm/tables.h"
  51 #include "vm/utf8.h"
  52
  53
  54 /* data structures ************************************************************/
  55
  56 /*----------------------------------------------------------------------------*/
  57 /* Descriptor Pools                                                           */
  58 /*                                                                            */
  59 /* A descriptor_pool is a temporary data structure used during loading of     */
  60 /* a class. The descriptor_pool is used to allocate the table of              */
  61 /* constant_classrefs the class uses, and for parsing the field and method    */
  62 /* descriptors which occurr within the class. The inner workings of           */
  63 /* descriptor_pool are not important for outside code.                        */
  64 /*                                                                            */
  65 /* You use a descriptor_pool as follows:                                      */
  66 /*                                                                            */
  67 /* 1. create one with descriptor_pool_new                                     */
  68 /* 2. add all explicit class references with descriptor_pool_add_class        */
  69 /* 3. add all field/method descriptors with descriptor_pool_add               */
  70 /* 4. call descriptor_pool_create_classrefs                                   */
  71 /*    You can now lookup classrefs with descriptor_pool_lookup_classref       */
  72 /* 5. call descriptor_pool_alloc_parsed_descriptors                           */
  73 /* 6. for each field descriptor call descriptor_pool_parse_field_descriptor   */
  74 /*    for each method descriptor call descriptor_pool_parse_method_descriptor */
  75 /* 7. call descriptor_pool_get_parsed_descriptors                             */
  76 /*                                                                            */
  77 /* IMPORTANT: The descriptor_pool functions use DNEW and DMNEW for allocating */
  78 /*            memory which can be thrown away when the steps above have been  */
  79 /*            done.                                                           */
  80 /*----------------------------------------------------------------------------*/
  81
  82 struct descriptor_pool {
  83         classinfo         *referer;
  84         u4                 fieldcount;
  85         u4                 methodcount;
  86         u4                 paramcount;
  87         u4                 descriptorsize;
  88         u1                *descriptors;
  89         u1                *descriptors_next;
  90         hashtable          descriptorhash;
  91         constant_classref *classrefs;
  92         hashtable          classrefhash;
  93         u1                *descriptor_kind;       /* useful for debugging */
  94         u1                *descriptor_kind_next;  /* useful for debugging */
  95 };
  96
  97
  98 /* data structures for parsed field/method descriptors ************************/
  99
 100 struct typedesc {
 101         constant_classref *classref;   /* class reference for TYPE_ADR types      */
 102         u1                 type;       /* TYPE_??? constant                       */
 103         u1                 arraydim;   /* array dimension (0 if no array)         */
 104 };
 105
 106 struct methoddesc {
 107         s2                 paramcount; /* number of parameters                    */
 108         s2                 paramslots; /* like above but LONG,DOUBLE count twice  */
 109         typedesc           returntype; /* parsed descriptor of the return type    */
 110         typedesc           paramtypes[1]; /* parameter types, variable length!    */
 111 };
 112
 113 union parseddesc {
 114         typedesc          *fd;        /* parsed field descriptor                  */
 115         methoddesc        *md;        /* parsed method descriptor                 */
 116         void              *any;       /* used for simple test against NULL        */
 117 };
 118
 119
 120 /* function prototypes ********************************************************/
 121
 122 /* descriptor_debug_print_typedesc *********************************************
 123
 124    Print the given typedesc to the given stream
 125
 126    IN:
 127            file.............stream to print to
 128            d................the parsed descriptor
 129
 130 *******************************************************************************/
 131
 132 void descriptor_debug_print_typedesc(FILE *file,typedesc *d);
 133
 134 /* descriptor_debug_print_methoddesc *******************************************
 135
 136    Print the given methoddesc to the given stream
 137
 138    IN:
 139            file.............stream to print to
 140            d................the parsed descriptor
 141
 142 *******************************************************************************/
 143
 144 void descriptor_debug_print_methoddesc(FILE *file,methoddesc *d);
 145
 146 /* descriptor_pool_new *********************************************************
 147
 148    Allocate a new descriptor_pool
 149
 150    IN:
 151        referer..........class for which to create the pool
 152
 153    RETURN VALUE:
 154        a pointer to the new descriptor_pool
 155
 156 *******************************************************************************/
 157
 158 descriptor_pool * descriptor_pool_new(classinfo *referer);
 159
 160 /* descriptor_pool_add_class ***************************************************
 161
 162    Add the given class reference to the pool
 163
 164    IN:
 165        pool.............the descriptor_pool
 166            name.............the class reference to add
 167
 168    RETURN VALUE:
 169        true.............reference has been added
 170            false............an exception has been thrown
 171
 172 *******************************************************************************/
 173
 174 bool descriptor_pool_add_class(descriptor_pool *pool,utf *name);
 175
 176 /* descriptor_pool_add *********************************************************
 177
 178    Check the given descriptor and add it to the pool
 179
 180    IN:
 181        pool.............the descriptor_pool
 182            desc.............the descriptor to add. Maybe a field or method desc.
 183
 184    RETURN VALUE:
 185        true.............descriptor has been added
 186            false............an exception has been thrown
 187
 188 *******************************************************************************/
 189
 190 bool descriptor_pool_add(descriptor_pool *pool,utf *desc);
 191
 192 /* descriptor_pool_create_classrefs ********************************************
 193
 194    Create a table containing all the classrefs which were added to the pool
 195
 196    IN:
 197        pool.............the descriptor_pool
 198
 199    OUT:
 200        *count...........if count is non-NULL, this is set to the number
 201                             of classrefs in the table
 202
 203    RETURN VALUE:
 204        a pointer to the constant_classref table
 205
 206 *******************************************************************************/
 207
 208 constant_classref * descriptor_pool_create_classrefs(descriptor_pool *pool,
 209                                                                                                          s4 *count);
 210
 211 /* descriptor_pool_lookup_classref *********************************************
 212
 213    Return the constant_classref for the given class name
 214
 215    IN:
 216        pool.............the descriptor_pool
 217            classname........name of the class to look up
 218
 219    RETURN VALUE:
 220        a pointer to the constant_classref, or
 221            NULL if an exception has been thrown
 222
 223 *******************************************************************************/
 224
 225 constant_classref * descriptor_pool_lookup_classref(descriptor_pool *pool,utf *classname);
 226
 227 /* descriptor_pool_alloc_parsed_descriptors ************************************
 228
 229    Allocate space for the parsed descriptors
 230
 231    IN:
 232        pool.............the descriptor_pool
 233
 234    NOTE:
 235        This function must be called after all descriptors have been added
 236            with descriptor_pool_add.
 237
 238 *******************************************************************************/
 239
 240 void descriptor_pool_alloc_parsed_descriptors(descriptor_pool *pool);
 241
 242 /* descriptor_pool_parse_field_descriptor **************************************
 243
 244    Parse the given field descriptor
 245
 246    IN:
 247        pool.............the descriptor_pool
 248            desc.............the field descriptor
 249
 250    RETURN VALUE:
 251        a pointer to the parsed field descriptor, or
 252            NULL if an exception has been thrown
 253
 254    NOTE:
 255        descriptor_pool_alloc_parsed_descriptors must be called (once) before this
 256            function is used.
 257
 258 *******************************************************************************/
 259
 260 typedesc * descriptor_pool_parse_field_descriptor(descriptor_pool *pool,utf *desc);
 261
 262 /* descriptor_pool_parse_method_descriptor *************************************
 263
 264    Parse the given method descriptor
 265
 266    IN:
 267        pool.............the descriptor_pool
 268            desc.............the method descriptor
 269
 270    RETURN VALUE:
 271        a pointer to the parsed method descriptor, or
 272            NULL if an exception has been thrown
 273
 274    NOTE:
 275        descriptor_pool_alloc_parsed_descriptors must be called (once) before this
 276            function is used.
 277
 278 *******************************************************************************/
 279
 280 methoddesc * descriptor_pool_parse_method_descriptor(descriptor_pool *pool,utf *desc);
 281
 282 /* descriptor_pool_get_parsed_descriptors **************************************
 283
 284    Return a pointer to the block of parsed descriptors
 285
 286    IN:
 287        pool.............the descriptor_pool
 288
 289    OUT:
 290            *size............if size is non-NULL, this is set to the size of the
 291                             parsed descriptor block (in u1)
 292
 293    RETURN VALUE:
 294        a pointer to the block of parsed descriptors,
 295            NULL if there are no descriptors in the pool
 296
 297    NOTE:
 298        descriptor_pool_alloc_parsed_descriptors must be called (once) before this
 299            function is used.
 300
 301 *******************************************************************************/
 302
 303 void * descriptor_pool_get_parsed_descriptors(descriptor_pool *pool,
 304                                                                                           s4 *size);
 305
 306 /* descriptor_pool_get_sizes ***************************************************
 307
 308    Get the sizes of the class reference table and the parsed descriptors
 309
 310    IN:
 311        pool.............the descriptor_pool
 312
 313    OUT:
 314        *classrefsize....set to size of the class reference table
 315            *descsize........set to size of the parsed descriptors
 316
 317    NOTE:
 318        This function may only be called after both
 319                descriptor_pool_create_classrefs, and
 320                    descriptor_pool_alloc_parsed_descriptors
 321            have been called.
 322
 323 *******************************************************************************/
 324
 325 void descriptor_pool_get_sizes(descriptor_pool *pool,
 326                                                            u4 *classrefsize,u4 *descsize);
 327
 328 /* descriptor_debug_print_typedesc *********************************************
 329
 330    Print the given typedesc to the given stream
 331
 332    IN:
 333            file.............stream to print to
 334            d................the parsed descriptor
 335
 336 *******************************************************************************/
 337
 338 void descriptor_debug_print_typedesc(FILE *file,typedesc *d);
 339
 340 /* descriptor_debug_print_methoddesc *******************************************
 341
 342    Print the given methoddesc to the given stream
 343
 344    IN:
 345            file.............stream to print to
 346            d................the parsed descriptor
 347
 348 *******************************************************************************/
 349
 350 void descriptor_debug_print_methoddesc(FILE *file,methoddesc *d);
 351
 352 /* descriptor_pool_debug_dump **************************************************
 353
 354    Print the state of the descriptor_pool to the given stream
 355
 356    IN:
 357        pool.............the descriptor_pool
 358            file.............stream to print to
 359
 360 *******************************************************************************/
 361
 362 void descriptor_pool_debug_dump(descriptor_pool *pool,FILE *file);
 363
 364 #endif /* _DESCRIPTOR_H */
 365
 366
 367 /*
 368  * These are local overrides for various environment variables in Emacs.
 369  * Please do not remove this and leave it at the end of the file, where
 370  * Emacs will automagically detect them.
 371  * ---------------------------------------------------------------------
 372  * Local variables:
 373  * mode: c
 374  * indent-tabs-mode: t
 375  * c-basic-offset: 4
 376  * tab-width: 4
 377  * End:
 378  * vim:noexpandtab:sw=4:ts=4:
 379  */