1879N/A * Copyright (c) 2001, 2010, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1472N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A/* jvmstat global and subsystem counter name space - enumeration value 0N/A * serve as an index into the PerfDataManager::_name_space[] array 0N/A * containing the corresponding name space string. Only the top level 0N/A * subsystem name spaces are represented here. 0N/A // top level name spaces 0N/A // subsystem name spaces 0N/A * Classes to support access to production performance data 0N/A * The PerfData class structure is provided for creation, access, and update 0N/A * of performance data (a.k.a. instrumentation) in a specific memory region 0N/A * which is possibly accessible as shared memory. Although not explicitly 0N/A * prevented from doing so, developers should not use the values returned 0N/A * by accessor methods to make algorithmic decisions as they are potentially 0N/A * extracted from a shared memory region. Although any shared memory region 0N/A * created is with appropriate access restrictions, allowing read-write access 0N/A * only to the principal that created the JVM, it is believed that a the 0N/A * shared memory region facilitates an easier attack path than attacks 0N/A * launched through mechanisms such as /proc. For this reason, it is 0N/A * recommended that data returned by PerfData accessor methods be used 0N/A * There are three variability classifications of performance data 0N/A * Constants - value is written to the PerfData memory once, on creation 0N/A * Variables - value is modifiable, with no particular restrictions 0N/A * Counters - value is monotonically changing (increasing or decreasing) 0N/A * The performance data items can also have various types. The class 0N/A * hierarchy and the structure of the memory region are designed to 0N/A * accommodate new types as they are needed. Types are specified in 0N/A * terms of Java basic types, which accommodates client applications 0N/A * written in the Java programming language. The class hierarchy is: 0N/A * - PerfData (Abstract) 0N/A * - PerfLong (Abstract) 0N/A * - PerfLongConstant (alias: PerfConstant) 0N/A * - PerfLongVariant (Abstract) 0N/A * - PerfLongVariable (alias: PerfVariable) 0N/A * - PerfLongCounter (alias: PerfCounter) 0N/A * - PerfByteArray (Abstract) 0N/A * - PerfString (Abstract) 0N/A * - PerfStringVariable 0N/A * - PerfStringConstant 0N/A * As seen in the class hierarchy, the initially supported types are: 0N/A * Long - performance data holds a Java long type 0N/A * ByteArray - performance data holds an array of Java bytes 0N/A * used for holding C++ char arrays. 0N/A * The String type is derived from the ByteArray type. 0N/A * A PerfData subtype is not required to provide an implementation for 0N/A * each variability classification. For example, the String type provides 0N/A * Variable and Constant variablility classifications in the PerfStringVariable 0N/A * and PerfStringConstant classes, but does not provide a counter type. 0N/A * Performance data are also described by a unit of measure. Units allow 0N/A * client applications to make reasonable decisions on how to treat 0N/A * performance data generically, preventing the need to hard-code the 0N/A * specifics of a particular data item in client applications. The current 0N/A * None - the data has no units of measure 0N/A * Bytes - data is measured in bytes 0N/A * Ticks - data is measured in clock ticks 0N/A * Events - data is measured in events. For example, 0N/A * the number of garbage collection events or the 0N/A * number of methods compiled. 0N/A * String - data is not numerical. For example, 0N/A * the java command line options 0N/A * Hertz - data is a frequency 0N/A * The performance counters also provide a support attribute, indicating 0N/A * the stability of the counter as a programmatic interface. The support 0N/A * level is also implied by the name space in which the counter is created. 0N/A * The counter name space support conventions follow the Java package, class, 0N/A * and property support conventions: 0N/A * java.* - stable, supported interface 0N/A * com.sun.* - unstable, supported interface 0N/A * sun.* - unstable, unsupported interface 0N/A * In the above context, unstable is a measure of the interface support 0N/A * level, not the implementation stability level. 0N/A * Currently, instances of PerfData subtypes are considered to have 0N/A * a life time equal to that of the VM and are managed by the 0N/A * PerfDataManager class. All constructors for the PerfData class and 0N/A * its subtypes have protected constructors. Creation of PerfData 0N/A * instances is performed by invoking various create methods on the 0N/A * PerfDataManager class. Users should not attempt to delete these 0N/A * instances as the PerfDataManager class expects to perform deletion 0N/A * operations on exit of the VM. 0N/A * Creating performance counter that holds a monotonically increasing 0N/A * long data value with units specified in U_Bytes in the "java.gc.*" 0N/A * PerfLongCounter* foo_counter; 0N/A * foo_counter = PerfDataManager::create_long_counter(JAVA_GC, "foo", 0N/A * PerfData::U_Bytes, 0N/A * optionalInitialValue, 0N/A * foo_counter->inc(); 0N/A * Creating a performance counter that holds a variably change long 0N/A * data value with untis specified in U_Bytes in the "com.sun.ci 0N/A * PerfLongVariable* bar_varible; 0N/A * bar_variable = PerfDataManager::create_long_variable(COM_CI, "bar", 0N/A.* PerfData::U_Bytes, 0N/A * optionalInitialValue, 0N/A * bar_variable->inc(); 0N/A * bar_variable->set_value(0); 0N/A * Creating a performance counter that holds a constant string value in 0N/A * PerfDataManager::create_string_constant(SUN_CLS, "foo", string, CHECK); 0N/A * Although the create_string_constant() factory method returns a pointer 0N/A * to the PerfStringConstant object, it can safely be ignored. Developers 0N/A * are not encouraged to access the string constant's value via this 0N/A * pointer at this time due to security concerns. 0N/A * Creating a performance counter in an arbitrary name space that holds a 0N/A * value that is sampled by the StatSampler periodic task. 0N/A * PerfDataManager::create_counter("foo.sampled", PerfData::U_Events, 0N/A * &my_jlong, CHECK); 0N/A * In this example, the PerfData pointer can be ignored as the caller 0N/A * is relying on the StatSampler PeriodicTask to sample the given 0N/A * address at a regular interval. The interval is defined by the 0N/A * PerfDataSamplingInterval global variable, and is applyied on 0N/A * a system wide basis, not on an per-counter basis. 0N/A * Creating a performance counter in an arbitrary name space that utilizes 0N/A * a helper object to return a value to the StatSampler via the take_sample() 0N/A * class MyTimeSampler : public PerfLongSampleHelper { 0N/A * jlong take_sample() { return os::elapsed_counter(); } 0N/A * PerfDataManager::create_counter(SUN_RT, "helped", 0N/A * PerfData::U_Ticks, 0N/A * new MyTimeSampler(), CHECK); 0N/A * In this example, a subtype of PerfLongSampleHelper is instantiated 0N/A * and its take_sample() method is overridden to perform whatever 0N/A * operation is necessary to generate the data sample. This method 0N/A * will be called by the StatSampler at a regular interval, defined 0N/A * by the PerfDataSamplingInterval global variable. 0N/A * As before, PerfSampleHelper is an alias for PerfLongSampleHelper. 0N/A * For additional uses of PerfData subtypes, see the utility classes 0N/A * PerfTraceTime and PerfTraceTimedEvent below. 0N/A * Always-on non-sampled counters can be created independent of 0N/A * the UsePerfData flag. Counters will be created on the c-heap 0N/A * if UsePerfData is false. 0N/A * Until further noice, all PerfData objects should be created and 0N/A * manipulated within a guarded block. The guard variable is 0N/A * UsePerfData, a product flag set to true by default. This flag may 0N/A * be removed from the product in the future. 0N/A // the Variability enum must be kept in synchronization with the 0N/A // the Units enum must be kept in synchronization with the 0N/A // Miscellaneous flags 0N/A // create the entry for the PerfData item in the PerfData memory region. 0N/A // this region is maintained separately from the PerfData objects to 0N/A // facilitate its use by external processes. 0N/A // sample the data item given at creation time and write its value 0N/A // into the its corresponding PerfMemory location. 0N/A // returns a boolean indicating the validity of this object. 0N/A // the object is valid if and only if memory in PerfMemory 0N/A // region was successfully allocated. 0N/A // returns a boolean indicating whether the underlying object 0N/A // was allocated in the PerfMemory region or on the C heap. 0N/A // returns a pointer to a char* containing the name of the item. 0N/A // The pointer returned is the pointer to a copy of the name 0N/A // passed to the constructor, not the pointer to the name in the 0N/A // PerfData memory region. This redundancy is maintained for 0N/A // security reasons as the PerfMemory region may be in shared 0N/A // returns the variability classification associated with this item 0N/A // returns the units associated with this item. 0N/A // returns the flags associated with this item. 0N/A // returns the address of the data portion of the item in the 0N/A // PerfData memory region. 0N/A // returns the value of the data portion of the item in the 0N/A // PerfData memory region formatted as a string. 0N/A * PerfLongSampleHelper, and its alias PerfSamplerHelper, is a base class 0N/A * for helper classes that rely upon the StatSampler periodic task to 0N/A * invoke the take_sample() method and write the value returned to its 0N/A * appropriate location in the PerfData memory region. 0N/A * PerfLong is the base class for the various Long PerfData subtypes. 0N/A * it contains implementation details that are common among its derived 0N/A // returns the value of the data portion of the item in the 0N/A // PerfData memory region. 0N/A * The PerfLongConstant class, and its alias PerfConstant, implement 0N/A * a PerfData subtype that holds a jlong data value that is set upon 0N/A * creation of an instance of this class. This class provides no 0N/A * methods for changing the data value stored in PerfData memory region. 0N/A // hide sample() - no need to sample constants 0N/A * The PerfLongVariant class, and its alias PerfVariant, implement 0N/A * a PerfData subtype that holds a jlong data value that can be modified 0N/A * in an unrestricted manner. This class provides the implementation details 0N/A * for common functionality among its derived types. 0N/A * The PerfLongCounter class, and its alias PerfCounter, implement 0N/A * a PerfData subtype that holds a jlong data value that can (should) 0N/A * be modified in a monotonic manner. The inc(jlong) and add(jlong) 0N/A * methods can be passed negative values to implement a monotonically 0N/A * decreasing value. However, we rely upon the programmer to honor 0N/A * the notion that this counter always moves in the same direction - 0N/A * either increasing or decreasing. 0N/A * The PerfLongVariable class, and its alias PerfVariable, implement 0N/A * a PerfData subtype that holds a jlong data value that can 0N/A * be modified in an unrestricted manner. 0N/A * The PerfByteArray provides a PerfData subtype that allows the creation 0N/A * of a contiguous region of the PerfData memory region for storing a vector 0N/A * of bytes. This class is currently intended to be a base class for 0N/A * the PerfString class, and cannot be instantiated directly. 0N/A * The PerfStringConstant class provides a PerfData sub class that 0N/A * allows a null terminated string of single byte characters to be 0N/A * stored in the PerfData memory region. 0N/A // hide sample() - no need to sample constants 0N/A // Restrict string constant lengths to be <= PerfMaxStringConstLength. 0N/A // This prevents long string constants, as can occur with very 0N/A // long classpaths or java command lines, from consuming too much 0N/A * The PerfStringVariable class provides a PerfData sub class that 0N/A * allows a null terminated string of single byte character data 0N/A * to be stored in PerfData memory region. The string value can be reset 0N/A * after initialization. If the string value is >= max_length, then 0N/A * it will be truncated to max_length characters. The copied string 0N/A * is always null terminated. 0N/A // sampling of string variables are not yet supported 0N/A * The PerfDataList class is a container class for managing lists 0N/A * of PerfData items. The intention of this class is to allow for 0N/A * alternative implementations for management of list of PerfData 0N/A * items without impacting the code that uses the lists. 0N/A * The initial implementation is based upon GrowableArray. Searches 0N/A * on GrowableArray types is linear in nature and this may become 0N/A * a performance issue for creation of PerfData items, particularly 0N/A * from Java code where a test for existence is implemented as a 0N/A * search over all existing PerfData items. 0N/A * The abstraction is not complete. A more general container class 0N/A * would provide an Iterator abstraction that could be used to 0N/A * traverse the lists. This implementation still relys upon integer 0N/A * iterators and the at(int index) method. However, the GrowableArray 0N/A * is not directly visible outside this class and can be replaced by 0N/A * some other implementation, as long as that implementation provides 0N/A * a mechanism to iterate over the container by index. 0N/A // GrowableArray implementation 0N/A // method to search for a instrumentation object by name 0N/A // we expose the implementation here to facilitate the clone 0N/A // create a PerfDataList with the given initial length 0N/A // create a PerfDataList as a shallow copy of the given PerfDataList 0N/A // return the PerfData item indicated by name, 0N/A // or NULL if it doesn't exist. 0N/A // return true if a PerfData item with the name specified in the 0N/A // argument exists, otherwise return false. 0N/A // return the number of PerfData items in this list 0N/A // add a PerfData item to this list 0N/A // remove the given PerfData item from this list. When called 0N/A // while iterating over the list, this method will result in a 0N/A // change in the length of the container. The at(int index) 0N/A // method is also impacted by this method as elements with an 0N/A // index greater than the index of the element removed by this 0N/A // method will be shifted down by one. 0N/A // create a new PerfDataList from this list. The new list is 0N/A // a shallow copy of the original list and care should be taken 0N/A // with respect to delete operations on the elements of the list 0N/A // as the are likely in use by another copy of the list. 0N/A // for backward compatibility with GrowableArray - need to implement 0N/A // some form of iterator to provide a cleaner abstraction for 0N/A // iteration over the container. 0N/A * The PerfDataManager class is responsible for creating PerfData 0N/A * subtypes via a set a factory methods and for managing lists 0N/A * of the various PerfData types. 0N/A friend class StatSampler;
// for access to protected PerfDataList methods 0N/A // add a PerfData item to the list(s) of know PerfData objects 0N/A // return the list of all known PerfData items 0N/A // return the list of all known PerfData items that are to be 0N/A // sampled by the StatSampler. 0N/A // return the list of all known PerfData items that have a 0N/A // variability classification of type Constant 0N/A // method to check for the existence of a PerfData item with 4238N/A // method to search for a instrumentation object by name 0N/A // method to map a CounterNS enumeration to a namespace string 0N/A // methods to test the interface stability of a given counter namespace 0N/A // methods to test the interface stability of a given counter name 0N/A // method to construct counter name strings in a given name space. 0N/A // The string object is allocated from the Resource Area and calls 0N/A // to this method must be made within a ResourceMark. 0N/A // method to construct name space strings in a given name space. 0N/A // The string object is allocated from the Resource Area and calls 0N/A // to this method must be made within a ResourceMark. 0N/A // same as above, but appends the instance number to the name space 0N/A // these methods provide the general interface for creating 0N/A // performance data resources. The types of performance data 0N/A // resources can be extended by adding additional create<type> 0N/A // these creation methods are provided for ease of use. These allow 0N/A // Long performance data types to be created with a shorthand syntax. 0N/A// Useful macros to create the performance counters 0N/A * this class will administer a PerfCounter used as a time accumulator 0N/A * for a basic block much like the TraceTime class. 0N/A * static PerfCounter* my_time_counter = PerfDataManager::create_counter("my.time.counter", PerfData::U_Ticks, 0LL, CHECK); 0N/A * PerfTraceTime ptt(my_time_counter); 0N/A * // perform the operation you want to measure 0N/A * Note: use of this class does not need to occur within a guarded 0N/A * block. The UsePerfData guard is used with the implementation 0N/A // pointer to thread-local or global recursion counter variable 0N/A/* The PerfTraceTimedEvent class is responsible for counting the 0N/A * occurrence of some event and measuring the the elapsed time of 0N/A * the event in two separate PerfCounter instances. 0N/A * static PerfCounter* my_time_counter = PerfDataManager::create_counter("my.time.counter", PerfData::U_Ticks, CHECK); 0N/A * static PerfCounter* my_event_counter = PerfDataManager::create_counter("my.event.counter", PerfData::U_Events, CHECK); 0N/A * PerfTraceTimedEvent ptte(my_time_counter, my_event_counter); 0N/A * // perform the operation you want to count and measure 0N/A * Note: use of this class does not need to occur within a guarded 0N/A * block. The UsePerfData guard is used with the implementation 1879N/A#
endif // SHARE_VM_RUNTIME_PERFDATA_HPP