+ * 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.
+ *
+ * @author Brian Doherty
+ * @since 1.4.2
+ * @see #getPerf
+ * @see sun.misc.Perf$GetPerfAction
+ * @see java.nio.ByteBuffer
+ */
+public final class Perf {
+
+ private static Perf instance;
+
+ private static final int PERF_MODE_RO = 0;
+ private static final int PERF_MODE_RW = 1;
+
+ private Perf() { } // prevent instantiation
+
+ /**
+ * 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.
+ *
+ * @see java.security.AccessController#doPrivileged(PrivilegedAction)
+ * @see java.lang.RuntimePermission
+ */
+ public static class GetPerfAction implements PrivilegedAction
+ * 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
+ * Access to the returned
+ * Please note that the "sun.misc.Perf.getPerf" permission
+ * is not a JDK specified permission.
+ *
+ * @return A reference to the singleton Perf instance.
+ * @throws AccessControlException if a security manager exists and
+ * its
+ * This method will attach to the instrumentation buffer for the
+ * specified virtual machine. It returns a
+ * If the
+ * If the
+ * The attach mode specifies the access permissions requested for the
+ * instrumentation buffer of the target virtual machine. The permitted
+ * access permissions are:
+ *
+ *
+ * This method behaves just as the
+ * This method calls into the Java virtual machine to perform the platform
+ * specific attach method. Buffers returned from this method are
+ * internally managed as
+ * The implementation of this method may return distinct or identical
+ *
+ * For the Sun HotSpot JVM, two distinct calls to attach to the same
+ * target Java virtual machine will result in two distinct ByteBuffer
+ * objects returned by this method. This may change in a future release.
+ *
+ * @param user A
+ * If this method is passed a
+ * If this method is passed a
+ * Access to the instrument is provided through the returned
+ * The maximum length of the
+ * 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
+ * The maximum length of the
+ * 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
+ * The
+ * 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 Perf.getPerf() method in a privileged context.
+ *
+ * @see #getPerf
+ */
+ public Perf run() {
+ return getPerf();
+ }
+ }
+
+ /**
+ * Return a reference to the singleton Perf instance.
+ * 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.
+ * 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.
+ * checkPermission method doesn't allow
+ * access to the "sun.misc.Perf.getPerf" target.
+ * @see java.lang.RuntimePermission
+ * @see #attach
+ */
+ public static Perf getPerf()
+ {
+ SecurityManager security = System.getSecurityManager();
+ if (security != null) {
+ Permission perm = new RuntimePermission("sun.misc.Perf.getPerf");
+ security.checkPermission(perm);
+ }
+
+ return instance;
+ }
+
+ /**
+ * Attach to the instrumentation buffer for the specified Java virtual
+ * machine.
+ * 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.
+ * 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.
+ * 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.
+ * attach(int lvmid, String mode)
+ * method, except that it only searches for Java virtual machines
+ * owned by the specified user.
+ *
+ * @param user A String object containing the
+ * name of the user that owns the target Java
+ * virtual machine.
+ * @param lvmid an integer that uniquely identifies the
+ * target local Java virtual machine.
+ * @param mode a string indicating the attach mode.
+ * @return ByteBuffer a direct allocated byte buffer
+ * @throws IllegalArgumentException The lvmid or mode was invalid.
+ * @throws IOException An I/O error occurred while trying to acquire
+ * the instrumentation buffer.
+ * @throws OutOfMemoryError The instrumentation buffer could not be mapped
+ * into the virtual machine's address space.
+ * @see java.nio.ByteBuffer
+ */
+ public ByteBuffer attach(String user, int lvmid, String mode)
+ throws IllegalArgumentException, IOException
+ {
+ if (mode.compareTo("r") == 0) {
+ return attachImpl(user, lvmid, PERF_MODE_RO);
+ }
+ else if (mode.compareTo("rw") == 0) {
+ return attachImpl(user, lvmid, PERF_MODE_RW);
+ }
+ else {
+ throw new IllegalArgumentException("unknown mode");
+ }
+ }
+
+ /**
+ * Call the implementation specific attach method.
+ * PhantomRefereces to provide for
+ * guaranteed, secure release of the native resources.
+ *
+ * @param user A String object containing the
+ * name of the user that owns the target Java
+ * virtual machine.
+ * @param lvmid an integer that uniquely identifies the
+ * target local Java virtual machine.
+ * @param mode a string indicating the attach mode.
+ * @return ByteBuffer a direct allocated byte buffer
+ * @throws IllegalArgumentException The lvmid or mode was invalid.
+ * @throws IOException An I/O error occurred while trying to acquire
+ * the instrumentation buffer.
+ * @throws OutOfMemoryError The instrumentation buffer could not be mapped
+ * into the virtual machine's address space.
+ */
+ private ByteBuffer attachImpl(String user, int lvmid, int mode)
+ throws IllegalArgumentException, IOException
+ {
+ final ByteBuffer b = attach(user, lvmid, mode);
+
+ if (lvmid == 0) {
+ // The native instrumentation buffer for this Java virtual
+ // machine is never unmapped.
+ return b;
+ }
+ else {
+ // This is an instrumentation buffer for another Java virtual
+ // machine with native resources that need to be managed. We
+ // create a duplicate of the native ByteBuffer and manage it
+ // with a Cleaner object (PhantomReference). When the duplicate
+ // becomes only phantomly reachable, the native resources will
+ // be released.
+
+ final ByteBuffer dup = b.duplicate();
+ Cleaner.create(dup, new Runnable() {
+ public void run() {
+ try {
+ instance.detach(b);
+ }
+ catch (Throwable th) {
+ // avoid crashing the reference handler thread,
+ // but provide for some diagnosability
+ assert false : th.toString();
+ }
+ }
+ });
+ return dup;
+ }
+ }
+
+ /**
+ * Native method to perform the implementation specific attach mechanism.
+ * ByteBuffer objects for two distinct calls requesting
+ * attachment to the same Java virtual machine.
+ * String object containing the
+ * name of the user that owns the target Java
+ * virtual machine.
+ * @param lvmid an integer that uniquely identifies the
+ * target local Java virtual machine.
+ * @param mode a string indicating the attach mode.
+ * @return ByteBuffer a direct allocated byte buffer
+ * @throws IllegalArgumentException The lvmid or mode was invalid.
+ * @throws IOException An I/O error occurred while trying to acquire
+ * the instrumentation buffer.
+ * @throws OutOfMemoryError The instrumentation buffer could not be mapped
+ * into the virtual machine's address space.
+ */
+ private native ByteBuffer attach(String user, int lvmid, int mode)
+ throws IllegalArgumentException, IOException;
+
+ /**
+ * Native method to perform the implementation specific detach mechanism.
+ * ByteBuffer object that is
+ * not created by the attach method, then the results of
+ * this method are undefined, with unpredictable and potentially damaging
+ * effects to the Java virtual machine. To prevent accidental or malicious
+ * use of this method, all native ByteBuffer created by the
+ * attach method are managed internally as PhantomReferences
+ * and resources are freed by the system.
+ * ByteBuffer object created
+ * by the attach method with a lvmid for the Java virtual
+ * machine running this method (lvmid=0, for example), then the detach
+ * request is silently ignored.
+ *
+ * @param ByteBuffer A direct allocated byte buffer created by the
+ * attach method.
+ * @see java.nio.ByteBuffer
+ * @see #attach
+ */
+ private native void detach(ByteBuffer bb);
+
+ /**
+ * Create a long scalar entry in the instrumentation buffer
+ * with the given variability characteristic, units, and initial value.
+ *
+ * ByteBuffer object. Typically, this object should be wrapped
+ * with LongBuffer view object.
+ *
+ * @param variability the variability characteristic for this entry.
+ * @param units the units for this entry.
+ * @param name the name of this entry.
+ * @param value the initial value for this entry.
+ * @return 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 java.nio.ByteBuffer
+ */
+ public native ByteBuffer createLong(String name, int variability,
+ int units, long value);
+
+ /**
+ * Create a String entry in the instrumentation buffer with
+ * the given variability characteristic, units, and initial value.
+ * 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.
+ *
+ * ByteBuffer object.
+ *
+ * @param variability the variability characteristic for this entry.
+ * @param units the units for this entry.
+ * @param name the name of this entry.
+ * @param value the initial value for this entry.
+ * @param maxLength the maximum string length for this string
+ * instrument.
+ * @return 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 java.nio.ByteBuffer
+ */
+ public ByteBuffer createString(String name, int variability,
+ int units, String value, int maxLength)
+ {
+ byte[] v = getBytes(value);
+ byte[] v1 = new byte[v.length+1];
+ System.arraycopy(v, 0, v1, 0, v.length);
+ v1[v.length] = '\0';
+ return createByteArray(name, variability, units, v1, Math.max(v1.length, maxLength));
+ }
+
+ /**
+ * Create a String entry in the instrumentation buffer with
+ * the given variability characteristic, units, and initial value.
+ * 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.
+ *
+ * ByteBuffer object.
+ *
+ * @param variability the variability characteristic for this entry.
+ * @param units the units for this entry.
+ * @param name the name of this entry.
+ * @param value the initial value for this entry.
+ * @return 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 java.nio.ByteBuffer
+ */
+ public ByteBuffer createString(String name, int variability,
+ int units, String value)
+ {
+ byte[] v = getBytes(value);
+ byte[] v1 = new byte[v.length+1];
+ System.arraycopy(v, 0, v1, 0, v.length);
+ v1[v.length] = '\0';
+ return createByteArray(name, variability, units, v1, v1.length);
+ }
+
+ /**
+ * Create a byte vector entry in the instrumentation buffer
+ * with the given variability characteristic, units, and initial value.
+ * 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.
+ *
+ * ByteBuffer object.
+ *
+ * @param variability the variability characteristic for this entry.
+ * @param units the units for this entry.
+ * @param name the name of this entry.
+ * @param value the initial value for this entry.
+ * @param maxLength the maximum length of this byte array.
+ * @return 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 java.nio.ByteBuffer
+ */
+ public native ByteBuffer createByteArray(String name, int variability,
+ int units, byte[] value,
+ int maxLength);
+
+
+ /**
+ * convert string to an array of UTF-8 bytes
+ */
+ private static byte[] getBytes(String s)
+ {
+ byte[] bytes = null;
+
+ try {
+ bytes = s.getBytes("UTF-8");
+ }
+ catch (UnsupportedEncodingException e) {
+ // ignore, UTF-8 encoding is always known
+ }
+
+ return bytes;
+ }
+
+ /**
+ * 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 {@link #highResFrequency} method.
+ *
+ * @return the number of ticks of machine dependent resolution since
+ * the start of the Java virtual machine.
+ *
+ * @see #highResFrequency
+ * @see java.lang.System#currentTimeMillis()
+ */
+ public native long highResCounter();
+
+ /**
+ * 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 {@link #highResCounter} method,
+ * into the number of seconds since the start of the Java virtual machine.
+ *
+ * @return the frequency of the High Resolution Counter.
+ * @see #highResCounter
+ */
+ public native long highResFrequency();
+
+ private static native void registerNatives();
+
+ static {
+ registerNatives();
+ instance = new Perf();
+ }
+}