1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/vm/oops/symbol.hpp Thu Jan 27 16:11:27 2011 -0800
1.3 @@ -0,0 +1,223 @@
1.4 +/*
1.5 + * Copyright (c) 1997, 2009, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation.
1.11 + *
1.12 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.13 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.14 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.15 + * version 2 for more details (a copy is included in the LICENSE file that
1.16 + * accompanied this code).
1.17 + *
1.18 + * You should have received a copy of the GNU General Public License version
1.19 + * 2 along with this work; if not, write to the Free Software Foundation,
1.20 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.21 + *
1.22 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.23 + * or visit www.oracle.com if you need additional information or have any
1.24 + * questions.
1.25 + *
1.26 + */
1.27 +
1.28 +#ifndef SHARE_VM_OOPS_SYMBOL_HPP
1.29 +#define SHARE_VM_OOPS_SYMBOL_HPP
1.30 +
1.31 +#include "utilities/utf8.hpp"
1.32 +#include "memory/allocation.hpp"
1.33 +
1.34 +// A Symbol is a canonicalized string.
1.35 +// All Symbols reside in global SymbolTable and are reference counted.
1.36 +
1.37 +// Reference counting
1.38 +//
1.39 +// All Symbols are allocated and added to the SymbolTable.
1.40 +// When a class is unloaded, the reference counts of the Symbol pointers in
1.41 +// the ConstantPool and in instanceKlass (see release_C_heap_structures) are
1.42 +// decremented. When the reference count for a Symbol goes to 0, the garbage
1.43 +// collector can free the Symbol and remove it from the SymbolTable.
1.44 +//
1.45 +// 0) Symbols need to be reference counted when a pointer to the Symbol is
1.46 +// saved in persistent storage. This does not include the pointer
1.47 +// in the SymbolTable bucket (the _literal field in HashtableEntry)
1.48 +// that points to the Symbol. All other stores of a Symbol*
1.49 +// to a field of a persistent variable (e.g., the _name filed in
1.50 +// FieldAccessInfo or _ptr in a CPSlot) is reference counted.
1.51 +//
1.52 +// 1) The lookup of a "name" in the SymbolTable either creates a Symbol F for
1.53 +// "name" and returns a pointer to F or finds a pre-existing Symbol F for
1.54 +// "name" and returns a pointer to it. In both cases the reference count for F
1.55 +// is incremented under the assumption that a pointer to F will be created from
1.56 +// the return value. Thus the increment of the reference count is on the lookup
1.57 +// and not on the assignment to the new Symbol*. That is
1.58 +// Symbol* G = lookup()
1.59 +// ^ increment on lookup()
1.60 +// and not
1.61 +// Symbol* G = lookup()
1.62 +// ^ increment on assignmnet
1.63 +// The reference count must be decremented manually when the copy of the
1.64 +// pointer G is destroyed.
1.65 +//
1.66 +// 2) For a local Symbol* A that is a copy of an existing Symbol* B, the
1.67 +// reference counting is elided when the scope of B is greater than the scope
1.68 +// of A. For example, in the code fragment
1.69 +// below "klass" is passed as a parameter to the method. Symbol* "kn"
1.70 +// is a copy of the name in "klass".
1.71 +//
1.72 +// Symbol* kn = klass->name();
1.73 +// unsigned int d_hash = dictionary()->compute_hash(kn, class_loader);
1.74 +//
1.75 +// The scope of "klass" is greater than the scope of "kn" so the reference
1.76 +// counting for "kn" is elided.
1.77 +//
1.78 +// Symbol* copied from ConstantPool entries are good candidates for reference
1.79 +// counting elision. The ConstantPool entries for a class C exist until C is
1.80 +// unloaded. If a Symbol* is copied out of the ConstantPool into Symbol* X,
1.81 +// the Symbol* in the ConstantPool will in general out live X so the reference
1.82 +// counting on X can be elided.
1.83 +//
1.84 +// For cases where the scope of A is not greater than the scope of B,
1.85 +// the reference counting is explicitly done. See ciSymbol,
1.86 +// ResolutionErrorEntry and ClassVerifier for examples.
1.87 +//
1.88 +// 3) When a Symbol K is created for temporary use, generally for substrings of
1.89 +// an existing symbol or to create a new symbol, assign it to a
1.90 +// TempNewSymbol. The SymbolTable methods new_symbol(), lookup()
1.91 +// and probe() all potentially return a pointer to a new Symbol.
1.92 +// The allocation (or lookup) of K increments the reference count for K
1.93 +// and the destructor decrements the reference count.
1.94 +//
1.95 +// Another example of TempNewSymbol usage is parsed_name used in
1.96 +// ClassFileParser::parseClassFile() where parsed_name is used in the cleanup
1.97 +// after a failed attempt to load a class. Here parsed_name is a
1.98 +// TempNewSymbol (passed in as a parameter) so the reference count on its symbol
1.99 +// will be decremented when it goes out of scope.
1.100 +
1.101 +class Symbol : public CHeapObj {
1.102 + friend class VMStructs;
1.103 + friend class SymbolTable;
1.104 + friend class MoveSymbols;
1.105 + private:
1.106 + volatile int _refcount;
1.107 + int _identity_hash;
1.108 + unsigned short _length; // number of UTF8 characters in the symbol
1.109 + jbyte _body[1];
1.110 +
1.111 + enum {
1.112 + // max_symbol_length is constrained by type of _length
1.113 + max_symbol_length = (1 << 16) -1
1.114 + };
1.115 +
1.116 + static int object_size(int length) {
1.117 + size_t size = heap_word_size(sizeof(Symbol) + length);
1.118 + return align_object_size(size);
1.119 + }
1.120 +
1.121 + void byte_at_put(int index, int value) {
1.122 + assert(index >=0 && index < _length, "symbol index overflow");
1.123 + _body[index] = value;
1.124 + }
1.125 +
1.126 + Symbol(const u1* name, int length);
1.127 + void* operator new(size_t size, int len);
1.128 +
1.129 + public:
1.130 + // Low-level access (used with care, since not GC-safe)
1.131 + const jbyte* base() const { return &_body[0]; }
1.132 +
1.133 + int object_size() { return object_size(utf8_length()); }
1.134 +
1.135 + // Returns the largest size symbol we can safely hold.
1.136 + static int max_length() {
1.137 + return max_symbol_length;
1.138 + }
1.139 +
1.140 + int identity_hash() {
1.141 + return _identity_hash;
1.142 + }
1.143 +
1.144 + // Reference counting. See comments above this class for when to use.
1.145 + int refcount() const { return _refcount; }
1.146 + void increment_refcount();
1.147 + void decrement_refcount();
1.148 +
1.149 + int byte_at(int index) const {
1.150 + assert(index >=0 && index < _length, "symbol index overflow");
1.151 + return base()[index];
1.152 + }
1.153 +
1.154 + const jbyte* bytes() const { return base(); }
1.155 +
1.156 + int utf8_length() const { return _length; }
1.157 +
1.158 + // Compares the symbol with a string.
1.159 + bool equals(const char* str, int len) const;
1.160 + bool equals(const char* str) const { return equals(str, (int) strlen(str)); }
1.161 +
1.162 + // Tests if the symbol starts with the given prefix.
1.163 + bool starts_with(const char* prefix, int len) const;
1.164 + bool starts_with(const char* prefix) const {
1.165 + return starts_with(prefix, (int) strlen(prefix));
1.166 + }
1.167 +
1.168 + // Tests if the symbol starts with the given prefix.
1.169 + int index_of_at(int i, const char* str, int len) const;
1.170 + int index_of_at(int i, const char* str) const {
1.171 + return index_of_at(i, str, (int) strlen(str));
1.172 + }
1.173 +
1.174 + // Three-way compare for sorting; returns -1/0/1 if receiver is </==/> than arg
1.175 + // note that the ordering is not alfabetical
1.176 + inline int fast_compare(Symbol* other) const;
1.177 +
1.178 + // Returns receiver converted to null-terminated UTF-8 string; string is
1.179 + // allocated in resource area, or in the char buffer provided by caller.
1.180 + char* as_C_string() const;
1.181 + char* as_C_string(char* buf, int size) const;
1.182 + // Use buf if needed buffer length is <= size.
1.183 + char* as_C_string_flexible_buffer(Thread* t, char* buf, int size) const;
1.184 +
1.185 +
1.186 + // Returns a null terminated utf8 string in a resource array
1.187 + char* as_utf8() const { return as_C_string(); }
1.188 + char* as_utf8_flexible_buffer(Thread* t, char* buf, int size) const {
1.189 + return as_C_string_flexible_buffer(t, buf, size);
1.190 + }
1.191 +
1.192 + jchar* as_unicode(int& length) const;
1.193 +
1.194 + // Treating this symbol as a class name, returns the Java name for the class.
1.195 + // String is allocated in resource area if buffer is not provided.
1.196 + // See Klass::external_name()
1.197 + const char* as_klass_external_name() const;
1.198 + const char* as_klass_external_name(char* buf, int size) const;
1.199 +
1.200 + // Printing
1.201 + void print_symbol_on(outputStream* st = NULL) const;
1.202 + void print_on(outputStream* st) const; // First level print
1.203 + void print_value_on(outputStream* st) const; // Second level print.
1.204 +
1.205 + // printing on default output stream
1.206 + void print() { print_on(tty); }
1.207 + void print_value() { print_value_on(tty); }
1.208 +
1.209 +#ifndef PRODUCT
1.210 + // Empty constructor to create a dummy symbol object on stack
1.211 + // only for getting its vtable pointer.
1.212 + Symbol() { }
1.213 +
1.214 + static int _total_count;
1.215 +#endif
1.216 +};
1.217 +
1.218 +// Note: this comparison is used for vtable sorting only; it doesn't matter
1.219 +// what order it defines, as long as it is a total, time-invariant order
1.220 +// Since Symbol*s are in C_HEAP, their relative order in memory never changes,
1.221 +// so use address comparison for speed
1.222 +int Symbol::fast_compare(Symbol* other) const {
1.223 + return (((uintptr_t)this < (uintptr_t)other) ? -1
1.224 + : ((uintptr_t)this == (uintptr_t) other) ? 0 : 1);
1.225 +}
1.226 +#endif // SHARE_VM_OOPS_SYMBOL_HPP
