duke@435: /*
simonis@4675:  * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
duke@435:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
duke@435:  *
duke@435:  * This code is free software; you can redistribute it and/or modify it
duke@435:  * under the terms of the GNU General Public License version 2 only, as
duke@435:  * published by the Free Software Foundation.
duke@435:  *
duke@435:  * This code is distributed in the hope that it will be useful, but WITHOUT
duke@435:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@435:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
duke@435:  * version 2 for more details (a copy is included in the LICENSE file that
duke@435:  * accompanied this code).
duke@435:  *
duke@435:  * You should have received a copy of the GNU General Public License version
duke@435:  * 2 along with this work; if not, write to the Free Software Foundation,
duke@435:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@435:  *
trims@1907:  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
trims@1907:  * or visit www.oracle.com if you need additional information or have any
trims@1907:  * questions.
duke@435:  *
duke@435:  */
duke@435: 
coleenp@2497: #ifndef SHARE_VM_OOPS_SYMBOL_HPP
coleenp@2497: #define SHARE_VM_OOPS_SYMBOL_HPP
stefank@2314: 
stefank@2314: #include "utilities/utf8.hpp"
coleenp@2497: #include "memory/allocation.hpp"
stefank@2314: 
coleenp@2497: // A Symbol is a canonicalized string.
coleenp@2497: // All Symbols reside in global SymbolTable and are reference counted.
duke@435: 
coleenp@2497: // Reference counting
coleenp@2497: //
coleenp@2497: // All Symbols are allocated and added to the SymbolTable.
coleenp@2497: // When a class is unloaded, the reference counts of the Symbol pointers in
coleenp@4037: // the ConstantPool and in InstanceKlass (see release_C_heap_structures) are
coleenp@2497: // decremented.  When the reference count for a Symbol goes to 0, the garbage
coleenp@2497: // collector can free the Symbol and remove it from the SymbolTable.
coleenp@2497: //
coleenp@2497: // 0) Symbols need to be reference counted when a pointer to the Symbol is
coleenp@2497: // saved in persistent storage.  This does not include the pointer
coleenp@2497: // in the SymbolTable bucket (the _literal field in HashtableEntry)
coleenp@2497: // that points to the Symbol.  All other stores of a Symbol*
coleenp@2497: // to a field of a persistent variable (e.g., the _name filed in
coleenp@2497: // FieldAccessInfo or _ptr in a CPSlot) is reference counted.
coleenp@2497: //
coleenp@2497: // 1) The lookup of a "name" in the SymbolTable either creates a Symbol F for
coleenp@2497: // "name" and returns a pointer to F or finds a pre-existing Symbol F for
coleenp@2497: // "name" and returns a pointer to it. In both cases the reference count for F
coleenp@2497: // is incremented under the assumption that a pointer to F will be created from
coleenp@2497: // the return value. Thus the increment of the reference count is on the lookup
coleenp@2497: // and not on the assignment to the new Symbol*.  That is
coleenp@2497: //    Symbol* G = lookup()
coleenp@2497: //                ^ increment on lookup()
coleenp@2497: // and not
coleenp@2497: //    Symbol* G = lookup()
coleenp@2497: //              ^ increment on assignmnet
coleenp@2497: // The reference count must be decremented manually when the copy of the
coleenp@2497: // pointer G is destroyed.
coleenp@2497: //
coleenp@2497: // 2) For a local Symbol* A that is a copy of an existing Symbol* B, the
coleenp@2497: // reference counting is elided when the scope of B is greater than the scope
coleenp@2497: // of A.  For example, in the code fragment
coleenp@2497: // below "klass" is passed as a parameter to the method.  Symbol* "kn"
coleenp@2497: // is a copy of the name in "klass".
coleenp@2497: //
coleenp@2497: //   Symbol*  kn = klass->name();
coleenp@2497: //   unsigned int d_hash = dictionary()->compute_hash(kn, class_loader);
coleenp@2497: //
coleenp@2497: // The scope of "klass" is greater than the scope of "kn" so the reference
coleenp@2497: // counting for "kn" is elided.
coleenp@2497: //
coleenp@2497: // Symbol* copied from ConstantPool entries are good candidates for reference
coleenp@2497: // counting elision.  The ConstantPool entries for a class C exist until C is
coleenp@2497: // unloaded.  If a Symbol* is copied out of the ConstantPool into Symbol* X,
coleenp@2497: // the Symbol* in the ConstantPool will in general out live X so the reference
coleenp@2497: // counting on X can be elided.
coleenp@2497: //
coleenp@2497: // For cases where the scope of A is not greater than the scope of B,
coleenp@2497: // the reference counting is explicitly done.  See ciSymbol,
coleenp@2497: // ResolutionErrorEntry and ClassVerifier for examples.
coleenp@2497: //
coleenp@2497: // 3) When a Symbol K is created for temporary use, generally for substrings of
coleenp@2497: // an existing symbol or to create a new symbol, assign it to a
coleenp@2497: // TempNewSymbol. The SymbolTable methods new_symbol(), lookup()
coleenp@2497: // and probe() all potentially return a pointer to a new Symbol.
coleenp@2497: // The allocation (or lookup) of K increments the reference count for K
coleenp@2497: // and the destructor decrements the reference count.
coleenp@2497: //
coleenp@2497: // Another example of TempNewSymbol usage is parsed_name used in
coleenp@2497: // ClassFileParser::parseClassFile() where parsed_name is used in the cleanup
coleenp@2497: // after a failed attempt to load a class.  Here parsed_name is a
coleenp@2497: // TempNewSymbol (passed in as a parameter) so the reference count on its symbol
coleenp@2497: // will be decremented when it goes out of scope.
coleenp@2497: 
coleenp@4037: 
coleenp@4037: // This cannot be inherited from ResourceObj because it cannot have a vtable.
coleenp@4037: // Since sometimes this is allocated from Metadata, pick a base allocation
coleenp@4037: // type without virtual functions.
coleenp@4037: class ClassLoaderData;
coleenp@4037: 
coleenp@4037: class Symbol : public MetaspaceObj {
duke@435:   friend class VMStructs;
coleenp@2497:   friend class SymbolTable;
coleenp@2497:   friend class MoveSymbols;
duke@435:  private:
coleenp@2497:   volatile int   _refcount;
coleenp@2497:   int            _identity_hash;
duke@435:   unsigned short _length; // number of UTF8 characters in the symbol
duke@435:   jbyte _body[1];
duke@435: 
duke@435:   enum {
duke@435:     // max_symbol_length is constrained by type of _length
duke@435:     max_symbol_length = (1 << 16) -1
duke@435:   };
coleenp@2497: 
coleenp@4037:   static int size(int length) {
coleenp@4037:     size_t sz = heap_word_size(sizeof(Symbol) + (length > 0 ? length - 1 : 0));
coleenp@4037:     return align_object_size(sz);
coleenp@2497:   }
coleenp@2497: 
coleenp@2497:   void byte_at_put(int index, int value) {
coleenp@2497:     assert(index >=0 && index < _length, "symbol index overflow");
coleenp@2497:     _body[index] = value;
coleenp@2497:   }
coleenp@2497: 
coleenp@3682:   Symbol(const u1* name, int length, int refcount);
coleenp@3682:   void* operator new(size_t size, int len, TRAPS);
coleenp@3682:   void* operator new(size_t size, int len, Arena* arena, TRAPS);
coleenp@4037:   void* operator new(size_t size, int len, ClassLoaderData* loader_data, TRAPS);
coleenp@4037: 
coleenp@4037:   void  operator delete(void* p);
coleenp@2497: 
duke@435:  public:
coleenp@2497:   // Low-level access (used with care, since not GC-safe)
coleenp@2497:   const jbyte* base() const { return &_body[0]; }
duke@435: 
coleenp@4037:   int size()                { return size(utf8_length()); }
duke@435: 
duke@435:   // Returns the largest size symbol we can safely hold.
coleenp@3682:   static int max_length()   { return max_symbol_length; }
duke@435: 
coleenp@3682:   int identity_hash()       { return _identity_hash; }
duke@435: 
coleenp@4037:   // For symbol table alternate hashing
coleenp@4037:   unsigned int new_hash(jint seed);
coleenp@4037: 
coleenp@2497:   // Reference counting.  See comments above this class for when to use.
coleenp@3682:   int refcount() const      { return _refcount; }
simonis@4675:   void increment_refcount();
simonis@4675:   void decrement_refcount();
duke@435: 
duke@435:   int byte_at(int index) const {
duke@435:     assert(index >=0 && index < _length, "symbol index overflow");
coleenp@2497:     return base()[index];
duke@435:   }
duke@435: 
coleenp@2497:   const jbyte* bytes() const { return base(); }
duke@435: 
duke@435:   int utf8_length() const { return _length; }
duke@435: 
twisti@1573:   // Compares the symbol with a string.
duke@435:   bool equals(const char* str, int len) const;
twisti@1573:   bool equals(const char* str) const { return equals(str, (int) strlen(str)); }
twisti@1573: 
twisti@1573:   // Tests if the symbol starts with the given prefix.
twisti@1573:   bool starts_with(const char* prefix, int len) const;
twisti@1573:   bool starts_with(const char* prefix) const {
twisti@1573:     return starts_with(prefix, (int) strlen(prefix));
twisti@1573:   }
twisti@1573: 
twisti@1573:   // Tests if the symbol starts with the given prefix.
twisti@1573:   int index_of_at(int i, const char* str, int len) const;
twisti@1573:   int index_of_at(int i, const char* str) const {
twisti@1573:     return index_of_at(i, str, (int) strlen(str));
twisti@1573:   }
duke@435: 
duke@435:   // Three-way compare for sorting; returns -1/0/1 if receiver is </==/> than arg
duke@435:   // note that the ordering is not alfabetical
coleenp@2497:   inline int fast_compare(Symbol* other) const;
duke@435: 
duke@435:   // Returns receiver converted to null-terminated UTF-8 string; string is
duke@435:   // allocated in resource area, or in the char buffer provided by caller.
duke@435:   char* as_C_string() const;
duke@435:   char* as_C_string(char* buf, int size) const;
duke@435:   // Use buf if needed buffer length is <= size.
duke@435:   char* as_C_string_flexible_buffer(Thread* t, char* buf, int size) const;
duke@435: 
minqi@4267:   // Returns an escaped form of a Java string.
minqi@4267:   char* as_quoted_ascii() const;
duke@435: 
duke@435:   // Returns a null terminated utf8 string in a resource array
duke@435:   char* as_utf8() const { return as_C_string(); }
duke@435:   char* as_utf8_flexible_buffer(Thread* t, char* buf, int size) const {
duke@435:     return as_C_string_flexible_buffer(t, buf, size);
duke@435:   }
duke@435: 
duke@435:   jchar* as_unicode(int& length) const;
duke@435: 
duke@435:   // Treating this symbol as a class name, returns the Java name for the class.
duke@435:   // String is allocated in resource area if buffer is not provided.
duke@435:   // See Klass::external_name()
duke@435:   const char* as_klass_external_name() const;
duke@435:   const char* as_klass_external_name(char* buf, int size) const;
duke@435: 
coleenp@2497:   // Printing
coleenp@2497:   void print_symbol_on(outputStream* st = NULL) const;
coleenp@2497:   void print_on(outputStream* st) const;         // First level print
coleenp@2497:   void print_value_on(outputStream* st) const;   // Second level print.
duke@435: 
coleenp@2497:   // printing on default output stream
coleenp@2497:   void print()         { print_on(tty);       }
coleenp@2497:   void print_value()   { print_value_on(tty); }
coleenp@2497: 
coleenp@2497: #ifndef PRODUCT
coleenp@2497:   // Empty constructor to create a dummy symbol object on stack
coleenp@2497:   // only for getting its vtable pointer.
coleenp@2497:   Symbol() { }
coleenp@2497: 
coleenp@2497:   static int _total_count;
coleenp@2497: #endif
duke@435: };
duke@435: 
duke@435: // Note: this comparison is used for vtable sorting only; it doesn't matter
duke@435: // what order it defines, as long as it is a total, time-invariant order
coleenp@2497: // Since Symbol*s are in C_HEAP, their relative order in memory never changes,
duke@435: // so use address comparison for speed
coleenp@2497: int Symbol::fast_compare(Symbol* other) const {
duke@435:  return (((uintptr_t)this < (uintptr_t)other) ? -1
duke@435:    : ((uintptr_t)this == (uintptr_t) other) ? 0 : 1);
duke@435: }
coleenp@2497: #endif // SHARE_VM_OOPS_SYMBOL_HPP