src/share/vm/classfile/systemDictionary.hpp

@@ -33,35 +33,38 @@
 #include "runtime/java.hpp"
 #include "runtime/reflectionUtils.hpp"
 #include "utilities/hashtable.hpp"
 #include "utilities/hashtable.inline.hpp"
 
-// The system dictionary stores all loaded classes and maps:
+// The dictionary in each ClassLoaderData stores all loaded classes, either
+// initiatied by its class loader or defined by its class loader:
 //
-//   [class name,class loader] -> class   i.e.  [Symbol*,oop] -> Klass*
+//   class loader -> ClassLoaderData -> [class, protection domain set]
 //
 // Classes are loaded lazily. The default VM class loader is
 // represented as NULL.
 
-// The underlying data structure is an open hash table with a fixed number
-// of buckets. During loading the loader object is locked, (for the VM loader
-// a private lock object is used). Class loading can thus be done concurrently,
-// but only by different loaders.
+// The underlying data structure is an open hash table (Dictionary) per
+// ClassLoaderData with a fixed number of buckets. During loading the
+// class loader object is locked, (for the VM loader a private lock object is used).
+// The global SystemDictionary_lock is held for all additions into the ClassLoaderData
+// dictionaries.  TODO: fix lock granularity so that class loading can
+// be done concurrently, but only by different loaders.
 //
 // During loading a placeholder (name, loader) is temporarily placed in
 // a side data structure, and is used to detect ClassCircularityErrors
 // and to perform verification during GC.  A GC can occur in the midst
 // of class loading, as we call out to Java, have to take locks, etc.
 //
-// When class loading is finished, a new entry is added to the system
-// dictionary and the place holder is removed. Note that the protection
-// domain field of the system dictionary has not yet been filled in when
-// the "real" system dictionary entry is created.
+// When class loading is finished, a new entry is added to the dictionary
+// of the class loader and the placeholder is removed. Note that the protection
+// domain field of the dictionary entry has not yet been filled in when
+// the "real" dictionary entry is created.
 //
 // Clients of this class who are interested in finding if a class has
 // been completely loaded -- not classes in the process of being loaded --
-// can read the SystemDictionary unlocked. This is safe because
+// can read the dictionary unlocked. This is safe because
 //    - entries are only deleted at safepoints
 //    - readers cannot come to a safepoint while actively examining
 //         an entry  (an entry cannot be deleted from under a reader)
 //    - entries must be fully formed before they are available to concurrent
 //         readers (we must ensure write ordering)

@@ -281,11 +284,11 @@
                                       Handle class_loader,
                                       Handle protection_domain,
                                       bool is_superclass,
                                       TRAPS);
 
-  // Parse new stream. This won't update the system dictionary or
+  // Parse new stream. This won't update the dictionary or
   // class hierarchy, simply parse the stream. Used by JVMTI RedefineClasses.
   // Also used by Unsafe_DefineAnonymousClass
   static InstanceKlass* parse_stream(Symbol* class_name,
                                      Handle class_loader,
                                      Handle protection_domain,