28 #include "utilities/utf8.hpp"
  29 #include "memory/allocation.hpp"
  30 #include "runtime/atomic.hpp"
  31 
  32 // A Symbol is a canonicalized string.
  33 // All Symbols reside in global SymbolTable and are reference counted.
  34 
  35 // Reference counting
  36 //
  37 // All Symbols are allocated and added to the SymbolTable.
  38 // When a class is unloaded, the reference counts of the Symbol pointers in
  39 // the ConstantPool and in InstanceKlass (see release_C_heap_structures) are
  40 // decremented.  When the reference count for a Symbol goes to 0, the garbage
  41 // collector can free the Symbol and remove it from the SymbolTable.
  42 //
  43 // 0) Symbols need to be reference counted when a pointer to the Symbol is
  44 // saved in persistent storage.  This does not include the pointer
  45 // in the SymbolTable bucket (the _literal field in HashtableEntry)
  46 // that points to the Symbol.  All other stores of a Symbol*
  47 // to a field of a persistent variable (e.g., the _name filed in
  48 // FieldAccessInfo or _ptr in a CPSlot) is reference counted.
  49 //
  50 // 1) The lookup of a "name" in the SymbolTable either creates a Symbol F for
  51 // "name" and returns a pointer to F or finds a pre-existing Symbol F for
  52 // "name" and returns a pointer to it. In both cases the reference count for F
  53 // is incremented under the assumption that a pointer to F will be created from
  54 // the return value. Thus the increment of the reference count is on the lookup
  55 // and not on the assignment to the new Symbol*.  That is
  56 //    Symbol* G = lookup()
  57 //                ^ increment on lookup()
  58 // and not
  59 //    Symbol* G = lookup()
  60 //              ^ increment on assignmnet
  61 // The reference count must be decremented manually when the copy of the
  62 // pointer G is destroyed.
  63 //
  64 // 2) For a local Symbol* A that is a copy of an existing Symbol* B, the
  65 // reference counting is elided when the scope of B is greater than the scope
  66 // of A.  For example, in the code fragment
  67 // below "klass" is passed as a parameter to the method.  Symbol* "kn"
  68 // is a copy of the name in "klass".

  28 #include "utilities/utf8.hpp"
  29 #include "memory/allocation.hpp"
  30 #include "runtime/atomic.hpp"
  31 
  32 // A Symbol is a canonicalized string.
  33 // All Symbols reside in global SymbolTable and are reference counted.
  34 
  35 // Reference counting
  36 //
  37 // All Symbols are allocated and added to the SymbolTable.
  38 // When a class is unloaded, the reference counts of the Symbol pointers in
  39 // the ConstantPool and in InstanceKlass (see release_C_heap_structures) are
  40 // decremented.  When the reference count for a Symbol goes to 0, the garbage
  41 // collector can free the Symbol and remove it from the SymbolTable.
  42 //
  43 // 0) Symbols need to be reference counted when a pointer to the Symbol is
  44 // saved in persistent storage.  This does not include the pointer
  45 // in the SymbolTable bucket (the _literal field in HashtableEntry)
  46 // that points to the Symbol.  All other stores of a Symbol*
  47 // to a field of a persistent variable (e.g., the _name filed in
  48 // fieldDescriptor or _ptr in a CPSlot) is reference counted.
  49 //
  50 // 1) The lookup of a "name" in the SymbolTable either creates a Symbol F for
  51 // "name" and returns a pointer to F or finds a pre-existing Symbol F for
  52 // "name" and returns a pointer to it. In both cases the reference count for F
  53 // is incremented under the assumption that a pointer to F will be created from
  54 // the return value. Thus the increment of the reference count is on the lookup
  55 // and not on the assignment to the new Symbol*.  That is
  56 //    Symbol* G = lookup()
  57 //                ^ increment on lookup()
  58 // and not
  59 //    Symbol* G = lookup()
  60 //              ^ increment on assignmnet
  61 // The reference count must be decremented manually when the copy of the
  62 // pointer G is destroyed.
  63 //
  64 // 2) For a local Symbol* A that is a copy of an existing Symbol* B, the
  65 // reference counting is elided when the scope of B is greater than the scope
  66 // of A.  For example, in the code fragment
  67 // below "klass" is passed as a parameter to the method.  Symbol* "kn"
  68 // is a copy of the name in "klass".