Save This Page
Home » openjdk-7 » sun » misc » [javadoc | source]
sun.misc
public final class: Perf [javadoc | source]
java.lang.Object
   sun.misc.Perf
The Perf class provides the ability to attach to an instrumentation buffer maintained by a Java virtual machine. The instrumentation buffer may be for the Java virtual machine running the methods of this class or it may be for another Java virtual machine on the same system.

In addition, this class provides methods to create instrumentation objects in the instrumentation buffer for the Java virtual machine that is running these methods. It also contains methods for acquiring the value of a platform specific high resolution clock for time stamp and interval measurement purposes.

Nested Class Summary:
public static class  Perf.GetPerfAction  The GetPerfAction class is a convenience class for acquiring access to the singleton Perf instance using the AccessController.doPrivileged() method.

An instance of this class can be used as the argument to AccessController.doPrivileged(PrivilegedAction).

Here is a suggested idiom for use of this class:

class MyTrustedClass {
  private static final Perf perf =
      AccessController.doPrivileged(new Perf.GetPerfAction());
  ...
}

In the presence of a security manager, the MyTrustedClass class in the above example will need to be granted the "sun.misc.Perf.getPerf" RuntimePermission permission in order to successfully acquire the singleton Perf instance.

Please note that the "sun.misc.Perf.getPerf" permission is not a JDK specified permission. 

Method from sun.misc.Perf Summary:
attach,   attach,   createByteArray,   createLong,   createString,   createString,   getPerf,   highResCounter,   highResFrequency
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from sun.misc.Perf Detail:
 public ByteBuffer attach(int lvmid,
    String mode) throws IllegalArgumentException, IOException 
    Attach to the instrumentation buffer for the specified Java virtual machine.

    This method will attach to the instrumentation buffer for the specified virtual machine. It returns a ByteBuffer object that is initialized to access the instrumentation buffer for the indicated Java virtual machine. The lvmid parameter is a integer value that uniquely identifies the target local Java virtual machine. It is typically, but not necessarily, the process id of the target Java virtual machine.

    If the lvmid identifies a Java virtual machine different from the one running this method, then the coherency characteristics of the buffer are implementation dependent. Implementations that do not support named, coherent, shared memory may return a ByteBuffer object that contains only a snap shot of the data in the instrumentation buffer. Implementations that support named, coherent, shared memory, may return a ByteBuffer object that will be changing dynamically over time as the target Java virtual machine updates its mapping of this buffer.

    If the lvmid is 0 or equal to the actual lvmid for the Java virtual machine running this method, then the returned ByteBuffer object will always be coherent and dynamically changing.

    The attach mode specifies the access permissions requested for the instrumentation buffer of the target virtual machine. The permitted access permissions are:

  • "r" - Read only access. This Java virtual machine has only read access to the instrumentation buffer for the target Java virtual machine.
  • "rw" - Read/Write access. This Java virtual machine has read and write access to the instrumentation buffer for the target Java virtual machine. This mode is currently not supported and is reserved for future enhancements.
 public ByteBuffer attach(String user,
    int lvmid,
    String mode) throws IllegalArgumentException, IOException 
    Attach to the instrumentation buffer for the specified Java virtual machine owned by the given user.

    This method behaves just as the attach(int lvmid, String mode) method, except that it only searches for Java virtual machines owned by the specified user.

 public native ByteBuffer createByteArray(String name,
    int variability,
    int units,
    byte[] value,
    int maxLength)
    Create a byte vector entry in the instrumentation buffer with the given variability characteristic, units, and initial value.

    The maxLength parameter limits the size of the byte array instrument such that the initial or subsequent updates beyond this length are silently ignored. No special handling of truncated updates is provided.

    The underlying implementation may further limit the length of the length of the initial or subsequent value.

    Access to the instrument is provided through the returned ByteBuffer object.

 public native ByteBuffer createLong(String name,
    int variability,
    int units,
    long value)
    Create a long scalar entry in the instrumentation buffer with the given variability characteristic, units, and initial value.

    Access to the instrument is provided through the returned ByteBuffer object. Typically, this object should be wrapped with LongBuffer view object.

 public ByteBuffer createString(String name,
    int variability,
    int units,
    String value) 
    Create a String entry in the instrumentation buffer with the given variability characteristic, units, and initial value.

    The maximum length of the String stored in this string instrument is implied by the length of the value parameter. Subsequent updates to the value of this instrument will be truncated to this implied maximum length. The truncated value will be terminated by a null character.

    The underlying implementation may further limit the length of the initial or subsequent value, but will continue to preserve the null terminator.

    Access to the instrument is provided through the returned ByteBuffer object.

 public ByteBuffer createString(String name,
    int variability,
    int units,
    String value,
    int maxLength) 
    Create a String entry in the instrumentation buffer with the given variability characteristic, units, and initial value.

    The maximum length of the String stored in this string instrument is given in by maxLength parameter. Updates to this instrument with String values with lengths greater than maxLength will be truncated to maxLength. The truncated value will be terminated by a null character.

    The underlying implementation may further limit the length of the value, but will continue to preserve the null terminator.

    Access to the instrument is provided through the returned ByteBuffer object.

 public static Perf getPerf() 
    Return a reference to the singleton Perf instance.

    The getPerf() method returns the singleton instance of the Perf class. The returned object provides the caller with the capability for accessing the instrumentation buffer for this or another local Java virtual machine.

    If a security manager is installed, its checkPermission method is called with a RuntimePermission with a target of "sun.misc.Perf.getPerf". A security exception will result if the caller has not been granted this permission.

    Access to the returned Perf object should be protected by its caller and not passed on to untrusted code. This object can be used to attach to the instrumentation buffer provided by this Java virtual machine or for those of other Java virtual machines running on the same system. The instrumentation buffer may contain senstitive information. API's built on top of this interface may want to provide finer grained access control to the contents of individual instrumentation objects contained within the buffer.

    Please note that the "sun.misc.Perf.getPerf" permission is not a JDK specified permission.

 public native long highResCounter()
    Return the value of the High Resolution Counter. The High Resolution Counter returns the number of ticks since since the start of the Java virtual machine. The resolution of the counter is machine dependent and can be determined from the value return by the #highResFrequency method.
 public native long highResFrequency()
    Returns the frequency of the High Resolution Counter, in ticks per second. This value can be used to convert the value of the High Resolution Counter, as returned from a call to the #highResCounter method, into the number of seconds since the start of the Java virtual machine.