public final class

Perf

extends Object
java.lang.Object
   ↳ sun.misc.Perf

Class Overview

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.

See Also

Summary

Nested Classes
class Perf.GetPerfAction The GetPerfAction class is a convenience class for acquiring access to the singleton Perf instance using the AccessController.doPrivileged() method. 
Public Methods
ByteBuffer attach(String user, int lvmid, String mode)
Attach to the instrumentation buffer for the specified Java virtual machine owned by the given user.
ByteBuffer attach(int lvmid, String mode)
Attach to the instrumentation buffer for the specified Java virtual machine.
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.
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.
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.
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.
static Perf getPerf()
Return a reference to the singleton Perf instance.
long highResCounter()
Return the value of the High Resolution Counter.
long highResFrequency()
Returns the frequency of the High Resolution Counter, in ticks per second.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public ByteBuffer attach (String user, int lvmid, String mode)

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.

Parameters
user A String object containing the name of the user that owns the target Java virtual machine.
lvmid an integer that uniquely identifies the target local Java virtual machine.
mode a string indicating the attach mode.
Returns
  • ByteBuffer a direct allocated byte buffer
Throws
IllegalArgumentException The lvmid or mode was invalid.
IOException An I/O error occurred while trying to acquire the instrumentation buffer.
OutOfMemoryError The instrumentation buffer could not be mapped into the virtual machine's address space.
See Also
  • java.nio.ByteBuffer

public ByteBuffer attach (int lvmid, String mode)

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.

    • Parameters
    lvmid an integer that uniquely identifies the target local Java virtual machine.
    mode a string indicating the attach mode.
    Returns
    • ByteBuffer a direct allocated byte buffer
    Throws
    IllegalArgumentException The lvmid or mode was invalid.
    IOException An I/O error occurred while trying to acquire the instrumentation buffer.
    OutOfMemoryError The instrumentation buffer could not be mapped into the virtual machine's address space.
    See Also
    • java.nio.ByteBuffer

    public 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.

    Parameters
    name the name of this entry.
    variability the variability characteristic for this entry.
    units the units for this entry.
    value the initial value for this entry.
    maxLength the maximum length of this byte array.
    Returns
    • ByteBuffer a direct allocated byte buffer that allows write access to a native memory location containing a long value. see sun.misc.perf.Variability see sun.misc.perf.Units
    See Also
    • java.nio.ByteBuffer

    public 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.

    Parameters
    name the name of this entry.
    variability the variability characteristic for this entry.
    units the units for this entry.
    value the initial value for this entry.
    Returns
    • ByteBuffer a direct allocated ByteBuffer object that allows write access to a native memory location containing a long value. see sun.misc.perf.Variability see sun.misc.perf.Units
    See Also
    • java.nio.ByteBuffer

    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.

    Parameters
    name the name of this entry.
    variability the variability characteristic for this entry.
    units the units for this entry.
    value the initial value for this entry.
    Returns
    • ByteBuffer a direct allocated ByteBuffer that allows write access to a native memory location containing a long value. see sun.misc.perf.Variability see sun.misc.perf.Units
    See Also
    • java.nio.ByteBuffer

    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.

    Parameters
    name the name of this entry.
    variability the variability characteristic for this entry.
    units the units for this entry.
    value the initial value for this entry.
    maxLength the maximum string length for this string instrument.
    Returns
    • ByteBuffer a direct allocated ByteBuffer that allows write access to a native memory location containing a long value. see sun.misc.perf.Variability see sun.misc.perf.Units
    See Also
    • java.nio.ByteBuffer

    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.

    Returns
    • A reference to the singleton Perf instance.
    Throws
    if a security manager exists and its checkPermission method doesn't allow access to the "sun.misc.Perf.getPerf" target.
    See Also

    public 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.

    Returns
    • the number of ticks of machine dependent resolution since the start of the Java virtual machine.
    See Also

    public 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.

    Returns
    • the frequency of the High Resolution Counter.
    See Also