Mercurial > hg > graal-compiler
comparison src/share/vm/classfile/classFileParser.hpp @ 8719:c8b31b461e1a
8003419: NPG: Clean up metadata created during class loading if failure
Summary: Store metadata on ClassFileParser instance to be cleaned up by destructor. This enabled some refactoring of the enormous parseClassFile function.
Reviewed-by: jmasa, acorn
author | coleenp |
---|---|
date | Wed, 13 Mar 2013 17:34:29 -0400 |
parents | 927a311d00f9 |
children | 16885e702c88 |
comparison
equal
deleted
inserted
replaced
8718:0ede345ec7c9 | 8719:c8b31b461e1a |
---|---|
32 #include "runtime/handles.inline.hpp" | 32 #include "runtime/handles.inline.hpp" |
33 #include "utilities/accessFlags.hpp" | 33 #include "utilities/accessFlags.hpp" |
34 #include "classfile/symbolTable.hpp" | 34 #include "classfile/symbolTable.hpp" |
35 | 35 |
36 class FieldAllocationCount; | 36 class FieldAllocationCount; |
37 class FieldLayoutInfo; | |
37 | 38 |
38 | 39 |
39 // Parser for for .class files | 40 // Parser for for .class files |
40 // | 41 // |
41 // The bytes describing the class file structure is read from a Stream object | 42 // The bytes describing the class file structure is read from a Stream object |
45 bool _need_verify; | 46 bool _need_verify; |
46 bool _relax_verify; | 47 bool _relax_verify; |
47 u2 _major_version; | 48 u2 _major_version; |
48 u2 _minor_version; | 49 u2 _minor_version; |
49 Symbol* _class_name; | 50 Symbol* _class_name; |
51 ClassLoaderData* _loader_data; | |
50 KlassHandle _host_klass; | 52 KlassHandle _host_klass; |
51 GrowableArray<Handle>* _cp_patches; // overrides for CP entries | 53 GrowableArray<Handle>* _cp_patches; // overrides for CP entries |
52 | 54 |
53 // precomputed flags | 55 // precomputed flags |
54 bool _has_finalizer; | 56 bool _has_finalizer; |
56 bool _has_vanilla_constructor; | 58 bool _has_vanilla_constructor; |
57 int _max_bootstrap_specifier_index; // detects BSS values | 59 int _max_bootstrap_specifier_index; // detects BSS values |
58 | 60 |
59 // class attributes parsed before the instance klass is created: | 61 // class attributes parsed before the instance klass is created: |
60 bool _synthetic_flag; | 62 bool _synthetic_flag; |
63 int _sde_length; | |
64 char* _sde_buffer; | |
61 Symbol* _sourcefile; | 65 Symbol* _sourcefile; |
62 Symbol* _generic_signature; | 66 Symbol* _generic_signature; |
63 char* _sde_buffer; | 67 |
64 int _sde_length; | 68 // Metadata created before the instance klass is created. Must be deallocated |
65 Array<u2>* _inner_classes; | 69 // if not transferred to the InstanceKlass upon successful class loading |
70 // in which case these pointers have been set to NULL. | |
71 instanceKlassHandle _super_klass; | |
72 ConstantPool* _cp; | |
73 Array<u2>* _fields; | |
74 Array<Method*>* _methods; | |
75 Array<u2>* _inner_classes; | |
76 Array<Klass*>* _local_interfaces; | |
77 Array<Klass*>* _transitive_interfaces; | |
66 AnnotationArray* _annotations; | 78 AnnotationArray* _annotations; |
67 AnnotationArray* _type_annotations; | 79 AnnotationArray* _type_annotations; |
80 Array<AnnotationArray*>* _fields_annotations; | |
81 Array<AnnotationArray*>* _fields_type_annotations; | |
82 InstanceKlass* _klass; // InstanceKlass once created. | |
68 | 83 |
69 void set_class_synthetic_flag(bool x) { _synthetic_flag = x; } | 84 void set_class_synthetic_flag(bool x) { _synthetic_flag = x; } |
70 void set_class_sourcefile(Symbol* x) { _sourcefile = x; } | 85 void set_class_sourcefile(Symbol* x) { _sourcefile = x; } |
71 void set_class_generic_signature(Symbol* x) { _generic_signature = x; } | 86 void set_class_generic_signature(Symbol* x) { _generic_signature = x; } |
72 void set_class_sde_buffer(char* x, int len) { _sde_buffer = x; _sde_length = len; } | 87 void set_class_sde_buffer(char* x, int len) { _sde_buffer = x; _sde_length = len; } |
73 void set_class_inner_classes(Array<u2>* x) { _inner_classes = x; } | 88 |
74 void set_class_annotations(AnnotationArray* x) { _annotations = x; } | 89 void init_parsed_class_attributes(ClassLoaderData* loader_data) { |
75 void set_class_type_annotations(AnnotationArray* x) { _type_annotations = x; } | 90 _loader_data = loader_data; |
76 void init_parsed_class_attributes() { | |
77 _synthetic_flag = false; | 91 _synthetic_flag = false; |
78 _sourcefile = NULL; | 92 _sourcefile = NULL; |
79 _generic_signature = NULL; | 93 _generic_signature = NULL; |
80 _sde_buffer = NULL; | 94 _sde_buffer = NULL; |
81 _sde_length = 0; | 95 _sde_length = 0; |
82 _annotations = _type_annotations = NULL; | |
83 // initialize the other flags too: | 96 // initialize the other flags too: |
84 _has_finalizer = _has_empty_finalizer = _has_vanilla_constructor = false; | 97 _has_finalizer = _has_empty_finalizer = _has_vanilla_constructor = false; |
85 _max_bootstrap_specifier_index = -1; | 98 _max_bootstrap_specifier_index = -1; |
99 clear_class_metadata(); | |
100 _klass = NULL; | |
86 } | 101 } |
87 void apply_parsed_class_attributes(instanceKlassHandle k); // update k | 102 void apply_parsed_class_attributes(instanceKlassHandle k); // update k |
103 void apply_parsed_class_metadata(instanceKlassHandle k, int fields_count, TRAPS); | |
104 void clear_class_metadata() { | |
105 // metadata created before the instance klass is created. Must be | |
106 // deallocated if classfile parsing returns an error. | |
107 _cp = NULL; | |
108 _fields = NULL; | |
109 _methods = NULL; | |
110 _inner_classes = NULL; | |
111 _local_interfaces = NULL; | |
112 _transitive_interfaces = NULL; | |
113 _annotations = _type_annotations = NULL; | |
114 _fields_annotations = _fields_type_annotations = NULL; | |
115 } | |
88 | 116 |
89 class AnnotationCollector { | 117 class AnnotationCollector { |
90 public: | 118 public: |
91 enum Location { _in_field, _in_method, _in_class }; | 119 enum Location { _in_field, _in_method, _in_class }; |
92 enum ID { | 120 enum ID { |
122 u2 contended_group() { return _contended_group; } | 150 u2 contended_group() { return _contended_group; } |
123 | 151 |
124 void set_contended(bool contended) { set_annotation(_sun_misc_Contended); } | 152 void set_contended(bool contended) { set_annotation(_sun_misc_Contended); } |
125 bool is_contended() { return has_annotation(_sun_misc_Contended); } | 153 bool is_contended() { return has_annotation(_sun_misc_Contended); } |
126 }; | 154 }; |
155 | |
156 // This class also doubles as a holder for metadata cleanup. | |
127 class FieldAnnotationCollector: public AnnotationCollector { | 157 class FieldAnnotationCollector: public AnnotationCollector { |
158 ClassLoaderData* _loader_data; | |
159 AnnotationArray* _field_annotations; | |
160 AnnotationArray* _field_type_annotations; | |
128 public: | 161 public: |
129 FieldAnnotationCollector() : AnnotationCollector(_in_field) { } | 162 FieldAnnotationCollector(ClassLoaderData* loader_data) : |
163 AnnotationCollector(_in_field), | |
164 _loader_data(loader_data), | |
165 _field_annotations(NULL), | |
166 _field_type_annotations(NULL) {} | |
130 void apply_to(FieldInfo* f); | 167 void apply_to(FieldInfo* f); |
168 ~FieldAnnotationCollector(); | |
169 AnnotationArray* field_annotations() { return _field_annotations; } | |
170 AnnotationArray* field_type_annotations() { return _field_type_annotations; } | |
171 | |
172 void set_field_annotations(AnnotationArray* a) { _field_annotations = a; } | |
173 void set_field_type_annotations(AnnotationArray* a) { _field_type_annotations = a; } | |
131 }; | 174 }; |
175 | |
132 class MethodAnnotationCollector: public AnnotationCollector { | 176 class MethodAnnotationCollector: public AnnotationCollector { |
133 public: | 177 public: |
134 MethodAnnotationCollector() : AnnotationCollector(_in_method) { } | 178 MethodAnnotationCollector() : AnnotationCollector(_in_method) { } |
135 void apply_to(methodHandle m); | 179 void apply_to(methodHandle m); |
136 }; | 180 }; |
150 // Accessors | 194 // Accessors |
151 ClassFileStream* stream() { return _stream; } | 195 ClassFileStream* stream() { return _stream; } |
152 void set_stream(ClassFileStream* st) { _stream = st; } | 196 void set_stream(ClassFileStream* st) { _stream = st; } |
153 | 197 |
154 // Constant pool parsing | 198 // Constant pool parsing |
155 void parse_constant_pool_entries(ClassLoaderData* loader_data, | 199 void parse_constant_pool_entries(int length, TRAPS); |
156 constantPoolHandle cp, int length, TRAPS); | 200 |
157 | 201 constantPoolHandle parse_constant_pool(TRAPS); |
158 constantPoolHandle parse_constant_pool(ClassLoaderData* loader_data, TRAPS); | |
159 | 202 |
160 // Interface parsing | 203 // Interface parsing |
161 Array<Klass*>* parse_interfaces(constantPoolHandle cp, | 204 Array<Klass*>* parse_interfaces(int length, |
162 int length, | |
163 ClassLoaderData* loader_data, | |
164 Handle protection_domain, | 205 Handle protection_domain, |
165 Symbol* class_name, | 206 Symbol* class_name, |
166 bool* has_default_methods, | 207 bool* has_default_methods, |
167 TRAPS); | 208 TRAPS); |
168 void record_defined_class_dependencies(instanceKlassHandle defined_klass, TRAPS); | 209 void record_defined_class_dependencies(instanceKlassHandle defined_klass, TRAPS); |
169 | 210 |
211 instanceKlassHandle parse_super_class(int super_class_index, TRAPS); | |
170 // Field parsing | 212 // Field parsing |
171 void parse_field_attributes(ClassLoaderData* loader_data, | 213 void parse_field_attributes(u2 attributes_count, |
172 constantPoolHandle cp, u2 attributes_count, | |
173 bool is_static, u2 signature_index, | 214 bool is_static, u2 signature_index, |
174 u2* constantvalue_index_addr, | 215 u2* constantvalue_index_addr, |
175 bool* is_synthetic_addr, | 216 bool* is_synthetic_addr, |
176 u2* generic_signature_index_addr, | 217 u2* generic_signature_index_addr, |
177 AnnotationArray** field_annotations, | |
178 AnnotationArray** field_type_annotations, | |
179 FieldAnnotationCollector* parsed_annotations, | 218 FieldAnnotationCollector* parsed_annotations, |
180 TRAPS); | 219 TRAPS); |
181 Array<u2>* parse_fields(ClassLoaderData* loader_data, | 220 Array<u2>* parse_fields(Symbol* class_name, |
182 Symbol* class_name, | 221 bool is_interface, |
183 constantPoolHandle cp, bool is_interface, | |
184 FieldAllocationCount *fac, | 222 FieldAllocationCount *fac, |
185 Array<AnnotationArray*>** fields_annotations, | |
186 Array<AnnotationArray*>** fields_type_annotations, | |
187 u2* java_fields_count_ptr, TRAPS); | 223 u2* java_fields_count_ptr, TRAPS); |
188 | 224 |
189 void print_field_layout(Symbol* name, | 225 void print_field_layout(Symbol* name, |
190 Array<u2>* fields, | 226 Array<u2>* fields, |
191 constantPoolHandle cp, | 227 constantPoolHandle cp, |
193 int instance_fields_start, | 229 int instance_fields_start, |
194 int instance_fields_end, | 230 int instance_fields_end, |
195 int static_fields_end); | 231 int static_fields_end); |
196 | 232 |
197 // Method parsing | 233 // Method parsing |
198 methodHandle parse_method(ClassLoaderData* loader_data, | 234 methodHandle parse_method(bool is_interface, |
199 constantPoolHandle cp, | |
200 bool is_interface, | |
201 AccessFlags* promoted_flags, | 235 AccessFlags* promoted_flags, |
202 TRAPS); | 236 TRAPS); |
203 Array<Method*>* parse_methods(ClassLoaderData* loader_data, | 237 Array<Method*>* parse_methods(bool is_interface, |
204 constantPoolHandle cp, | |
205 bool is_interface, | |
206 AccessFlags* promoted_flags, | 238 AccessFlags* promoted_flags, |
207 bool* has_final_method, | 239 bool* has_final_method, |
208 bool* has_default_method, | 240 bool* has_default_method, |
209 TRAPS); | 241 TRAPS); |
210 Array<int>* sort_methods(ClassLoaderData* loader_data, | 242 intArray* sort_methods(Array<Method*>* methods); |
211 Array<Method*>* methods, | 243 |
212 TRAPS); | 244 u2* parse_exception_table(u4 code_length, u4 exception_table_length, |
213 u2* parse_exception_table(ClassLoaderData* loader_data, | 245 TRAPS); |
214 u4 code_length, u4 exception_table_length, | |
215 constantPoolHandle cp, TRAPS); | |
216 void parse_linenumber_table( | 246 void parse_linenumber_table( |
217 u4 code_attribute_length, u4 code_length, | 247 u4 code_attribute_length, u4 code_length, |
218 CompressedLineNumberWriteStream** write_stream, TRAPS); | 248 CompressedLineNumberWriteStream** write_stream, TRAPS); |
219 u2* parse_localvariable_table(u4 code_length, u2 max_locals, u4 code_attribute_length, | 249 u2* parse_localvariable_table(u4 code_length, u2 max_locals, u4 code_attribute_length, |
220 constantPoolHandle cp, u2* localvariable_table_length, | 250 u2* localvariable_table_length, |
221 bool isLVTT, TRAPS); | 251 bool isLVTT, TRAPS); |
222 u2* parse_checked_exceptions(u2* checked_exceptions_length, u4 method_attribute_length, | 252 u2* parse_checked_exceptions(u2* checked_exceptions_length, u4 method_attribute_length, |
223 constantPoolHandle cp, TRAPS); | 253 TRAPS); |
224 void parse_type_array(u2 array_length, u4 code_length, u4* u1_index, u4* u2_index, | 254 void parse_type_array(u2 array_length, u4 code_length, u4* u1_index, u4* u2_index, |
225 u1* u1_array, u2* u2_array, constantPoolHandle cp, TRAPS); | 255 u1* u1_array, u2* u2_array, TRAPS); |
226 Array<u1>* parse_stackmap_table(ClassLoaderData* loader_data, u4 code_attribute_length, TRAPS); | 256 u1* parse_stackmap_table(u4 code_attribute_length, TRAPS); |
227 | 257 |
228 // Classfile attribute parsing | 258 // Classfile attribute parsing |
229 void parse_classfile_sourcefile_attribute(constantPoolHandle cp, TRAPS); | 259 void parse_classfile_sourcefile_attribute(TRAPS); |
230 void parse_classfile_source_debug_extension_attribute(constantPoolHandle cp, | 260 void parse_classfile_source_debug_extension_attribute(int length, TRAPS); |
231 int length, TRAPS); | 261 u2 parse_classfile_inner_classes_attribute(u1* inner_classes_attribute_start, |
232 u2 parse_classfile_inner_classes_attribute(ClassLoaderData* loader_data, | |
233 u1* inner_classes_attribute_start, | |
234 bool parsed_enclosingmethod_attribute, | 262 bool parsed_enclosingmethod_attribute, |
235 u2 enclosing_method_class_index, | 263 u2 enclosing_method_class_index, |
236 u2 enclosing_method_method_index, | 264 u2 enclosing_method_method_index, |
237 constantPoolHandle cp, | |
238 TRAPS); | 265 TRAPS); |
239 void parse_classfile_attributes(ClassLoaderData* loader_data, | 266 void parse_classfile_attributes(ClassAnnotationCollector* parsed_annotations, |
240 constantPoolHandle cp, | |
241 ClassAnnotationCollector* parsed_annotations, | |
242 TRAPS); | 267 TRAPS); |
243 void parse_classfile_synthetic_attribute(constantPoolHandle cp, TRAPS); | 268 void parse_classfile_synthetic_attribute(TRAPS); |
244 void parse_classfile_signature_attribute(constantPoolHandle cp, TRAPS); | 269 void parse_classfile_signature_attribute(TRAPS); |
245 void parse_classfile_bootstrap_methods_attribute(ClassLoaderData* loader_data, constantPoolHandle cp, u4 attribute_length, TRAPS); | 270 void parse_classfile_bootstrap_methods_attribute(u4 attribute_length, TRAPS); |
246 | 271 |
247 // Annotations handling | 272 // Annotations handling |
248 AnnotationArray* assemble_annotations(ClassLoaderData* loader_data, | 273 AnnotationArray* assemble_annotations(u1* runtime_visible_annotations, |
249 u1* runtime_visible_annotations, | |
250 int runtime_visible_annotations_length, | 274 int runtime_visible_annotations_length, |
251 u1* runtime_invisible_annotations, | 275 u1* runtime_invisible_annotations, |
252 int runtime_invisible_annotations_length, TRAPS); | 276 int runtime_invisible_annotations_length, TRAPS); |
253 int skip_annotation(u1* buffer, int limit, int index); | 277 int skip_annotation(u1* buffer, int limit, int index); |
254 int skip_annotation_value(u1* buffer, int limit, int index); | 278 int skip_annotation_value(u1* buffer, int limit, int index); |
255 void parse_annotations(ClassLoaderData* loader_data, | 279 void parse_annotations(u1* buffer, int limit, |
256 u1* buffer, int limit, constantPoolHandle cp, | |
257 /* Results (currently, only one result is supported): */ | 280 /* Results (currently, only one result is supported): */ |
258 AnnotationCollector* result, | 281 AnnotationCollector* result, |
259 TRAPS); | 282 TRAPS); |
260 | 283 |
261 // Final setup | 284 // Final setup |
265 void fill_oop_maps(instanceKlassHandle k, | 288 void fill_oop_maps(instanceKlassHandle k, |
266 unsigned int nonstatic_oop_map_count, | 289 unsigned int nonstatic_oop_map_count, |
267 int* nonstatic_oop_offsets, | 290 int* nonstatic_oop_offsets, |
268 unsigned int* nonstatic_oop_counts); | 291 unsigned int* nonstatic_oop_counts); |
269 void set_precomputed_flags(instanceKlassHandle k); | 292 void set_precomputed_flags(instanceKlassHandle k); |
270 Array<Klass*>* compute_transitive_interfaces(ClassLoaderData* loader_data, | 293 Array<Klass*>* compute_transitive_interfaces(instanceKlassHandle super, |
271 instanceKlassHandle super, | |
272 Array<Klass*>* local_ifs, TRAPS); | 294 Array<Klass*>* local_ifs, TRAPS); |
273 | 295 |
274 // Format checker methods | 296 // Format checker methods |
275 void classfile_parse_error(const char* msg, TRAPS); | 297 void classfile_parse_error(const char* msg, TRAPS); |
276 void classfile_parse_error(const char* msg, int index, TRAPS); | 298 void classfile_parse_error(const char* msg, int index, TRAPS); |
316 const char* type, Symbol* name, Symbol* sig, TRAPS); | 338 const char* type, Symbol* name, Symbol* sig, TRAPS); |
317 | 339 |
318 bool is_supported_version(u2 major, u2 minor); | 340 bool is_supported_version(u2 major, u2 minor); |
319 bool has_illegal_visibility(jint flags); | 341 bool has_illegal_visibility(jint flags); |
320 | 342 |
321 void verify_constantvalue(int constantvalue_index, int signature_index, constantPoolHandle cp, TRAPS); | 343 void verify_constantvalue(int constantvalue_index, int signature_index, TRAPS); |
322 void verify_legal_utf8(const unsigned char* buffer, int length, TRAPS); | 344 void verify_legal_utf8(const unsigned char* buffer, int length, TRAPS); |
323 void verify_legal_class_name(Symbol* name, TRAPS); | 345 void verify_legal_class_name(Symbol* name, TRAPS); |
324 void verify_legal_field_name(Symbol* name, TRAPS); | 346 void verify_legal_field_name(Symbol* name, TRAPS); |
325 void verify_legal_method_name(Symbol* name, TRAPS); | 347 void verify_legal_method_name(Symbol* name, TRAPS); |
326 void verify_legal_field_signature(Symbol* fieldname, Symbol* signature, TRAPS); | 348 void verify_legal_field_signature(Symbol* fieldname, Symbol* signature, TRAPS); |
357 | 379 |
358 // Wrapper for constantTag.is_klass_[or_]reference. | 380 // Wrapper for constantTag.is_klass_[or_]reference. |
359 // In older versions of the VM, Klass*s cannot sneak into early phases of | 381 // In older versions of the VM, Klass*s cannot sneak into early phases of |
360 // constant pool construction, but in later versions they can. | 382 // constant pool construction, but in later versions they can. |
361 // %%% Let's phase out the old is_klass_reference. | 383 // %%% Let's phase out the old is_klass_reference. |
362 bool is_klass_reference(constantPoolHandle cp, int index) { | 384 bool valid_klass_reference_at(int index) { |
363 return (EnableInvokeDynamic | 385 return _cp->is_within_bounds(index) && |
364 ? cp->tag_at(index).is_klass_or_reference() | 386 (EnableInvokeDynamic |
365 : cp->tag_at(index).is_klass_reference()); | 387 ? _cp->tag_at(index).is_klass_or_reference() |
388 : _cp->tag_at(index).is_klass_reference()); | |
389 } | |
390 | |
391 // Checks that the cpool index is in range and is a utf8 | |
392 bool valid_symbol_at(int cpool_index) { | |
393 return (_cp->is_within_bounds(cpool_index) && | |
394 _cp->tag_at(cpool_index).is_utf8()); | |
366 } | 395 } |
367 | 396 |
368 void copy_localvariable_table(ConstMethod* cm, int lvt_cnt, | 397 void copy_localvariable_table(ConstMethod* cm, int lvt_cnt, |
369 u2* localvariable_table_length, | 398 u2* localvariable_table_length, |
370 u2** localvariable_table_start, | 399 u2** localvariable_table_start, |
371 int lvtt_cnt, | 400 int lvtt_cnt, |
372 u2* localvariable_type_table_length, | 401 u2* localvariable_type_table_length, |
373 u2** localvariable_type_table_start, | 402 u2** localvariable_type_table_start, |
374 TRAPS); | 403 TRAPS); |
375 | 404 |
376 void copy_method_annotations(ClassLoaderData* loader_data, | 405 void copy_method_annotations(ConstMethod* cm, |
377 ConstMethod* cm, | |
378 u1* runtime_visible_annotations, | 406 u1* runtime_visible_annotations, |
379 int runtime_visible_annotations_length, | 407 int runtime_visible_annotations_length, |
380 u1* runtime_invisible_annotations, | 408 u1* runtime_invisible_annotations, |
381 int runtime_invisible_annotations_length, | 409 int runtime_invisible_annotations_length, |
382 u1* runtime_visible_parameter_annotations, | 410 u1* runtime_visible_parameter_annotations, |
389 int runtime_invisible_type_annotations_length, | 417 int runtime_invisible_type_annotations_length, |
390 u1* annotation_default, | 418 u1* annotation_default, |
391 int annotation_default_length, | 419 int annotation_default_length, |
392 TRAPS); | 420 TRAPS); |
393 | 421 |
422 // lays out fields in class and returns the total oopmap count | |
423 void layout_fields(Handle class_loader, FieldAllocationCount* fac, | |
424 ClassAnnotationCollector* parsed_annotations, | |
425 FieldLayoutInfo* info, TRAPS); | |
426 | |
394 public: | 427 public: |
395 // Constructor | 428 // Constructor |
396 ClassFileParser(ClassFileStream* st) { set_stream(st); } | 429 ClassFileParser(ClassFileStream* st) { set_stream(st); } |
430 ~ClassFileParser(); | |
397 | 431 |
398 // Parse .class file and return new Klass*. The Klass* is not hooked up | 432 // Parse .class file and return new Klass*. The Klass* is not hooked up |
399 // to the system dictionary or any other structures, so a .class file can | 433 // to the system dictionary or any other structures, so a .class file can |
400 // be loaded several times if desired. | 434 // be loaded several times if desired. |
401 // The system dictionary hookup is done by the caller. | 435 // The system dictionary hookup is done by the caller. |