https://openjdk.java.net/ 
/*
 * Copyright (c) 2002, 2006, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package sun.misc;

import java.nio.ByteBuffer;
import java.security.Permission;
import java.security.PrivilegedAction;
import java.io.IOException;
import java.io.UnsupportedEncodingException;


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.

Author:  Brian Doherty
See Also:
Since:   1.4.2
/**
 * 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.
 * <p>
 * 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 Also:
/**
     * The GetPerfAction class is a convenience class for acquiring access
     * to the singleton Perf instance using the
     * <code>AccessController.doPrivileged()</code> method.
     * <p>
     * An instance of this class can be used as the argument to
     * <code>AccessController.doPrivileged(PrivilegedAction)</code>.
     * <p> Here is a suggested idiom for use of this class:
     *
     * <blockquote><pre>
     * class MyTrustedClass {
     *   private static final Perf perf =
     *       AccessController.doPrivileged(new Perf.GetPerfAction<Perf>());
     *   ...
     * }
     * </pre></blockquote>
     * <p>
     * In the presence of a security manager, the <code>MyTrustedClass</code>
     * class in the above example will need to be granted the
     * <em>"sun.misc.Perf.getPerf"</em> <code>RuntimePermission</code>
     * permission in order to successfully acquire the singleton Perf instance.
     * <p>
     * Please note that the <em>"sun.misc.Perf.getPerf"</em> permission
     * is not a JDK specified permission.
     *
     * @see  java.security.AccessController#doPrivileged(PrivilegedAction)
     * @see  java.lang.RuntimePermission
     */
    public static class GetPerfAction implements PrivilegedAction<Perf>
    {
        
Run the Perf.getPerf() method in a privileged context.

See Also:
  • getPerf
/**
         * Run the <code>Perf.getPerf()</code> method in a privileged context.
         *
         * @see #getPerf
         */
        public Perf run() {
            return 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.

Throws:
  • AccessControlException –  if a security manager exists and
              its checkPermission method doesn't allow
              access to the "sun.misc.Perf.getPerf" target.
See Also:
Returns:      A reference to the singleton Perf instance.
/**
     * Return a reference to the singleton Perf instance.
     * <p>
     * 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.
     * <p>
     * If a security manager is installed, its <code>checkPermission</code>
     * method is called with a <code>RuntimePermission</code> with a target
     * of <em>"sun.misc.Perf.getPerf"</em>. A security exception will result
     * if the caller has not been granted this permission.
     * <p>
     * Access to the returned <code>Perf</code> 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.
     * <p>
     * Please note that the <em>"sun.misc.Perf.getPerf"</em> permission
     * is not a JDK specified permission.
     *
     * @return       A reference to the singleton Perf instance.
     * @throws AccessControlException  if a security manager exists and
     *               its <code>checkPermission</code> method doesn't allow
     *               access to the <em>"sun.misc.Perf.getPerf"</em> 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.


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.


    • Params:
    • lvmid –            an integer that uniquely identifies the
                          target local Java virtual machine.
    • mode –             a string indicating the attach mode.
    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:
    Returns: ByteBuffer       a direct allocated byte buffer
    /**
     * Attach to the instrumentation buffer for the specified Java virtual
     * machine.
     * <p>
     * This method will attach to the instrumentation buffer for the
     * specified virtual machine. It returns a <code>ByteBuffer</code> object
     * that is initialized to access the instrumentation buffer for the
     * indicated Java virtual machine. The <code>lvmid</code> 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.
     * <p>
     * If the <code>lvmid</code> 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
     * <code>ByteBuffer</code> object that contains only a snap shot of the
     * data in the instrumentation buffer. Implementations that support named,
     * coherent, shared memory, may return a <code>ByteBuffer</code> object
     * that will be changing dynamically over time as the target Java virtual
     * machine updates its mapping of this buffer.
     * <p>
     * If the <code>lvmid</code> is 0 or equal to the actual <code>lvmid</code>
     * for the Java virtual machine running this method, then the returned
     * <code>ByteBuffer</code> object will always be coherent and dynamically
     * changing.
     * <p>
     * The attach mode specifies the access permissions requested for the
     * instrumentation buffer of the target virtual machine. The permitted
     * access permissions are:
     * <p>
     * <bl>
     * <li>"r"  - Read only access. This Java virtual machine has only
     * read access to the instrumentation buffer for the target Java
     * virtual machine.
     * <li>"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.
     * </bl>
     *
     * @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(int lvmid, String mode)
           throws IllegalArgumentException, IOException
    {
        if (mode.compareTo("r") == 0) {
            return attachImpl(null, lvmid, PERF_MODE_RO);
        }
        else if (mode.compareTo("rw") == 0) {
            return attachImpl(null, lvmid, PERF_MODE_RW);
        }
        else {
            throw new IllegalArgumentException("unknown 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.

    Params:
    • 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.
    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:
    Returns: ByteBuffer       a direct allocated byte buffer
    /**
     * Attach to the instrumentation buffer for the specified Java virtual
     * machine owned by the given user.
     * <p>
     * This method behaves just as the <code>attach(int lvmid, String mode)
     * </code> method, except that it only searches for Java virtual machines
     * owned by the specified user.
     *
     * @param   user             A <code>String</code> 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.

    
This method calls into the Java virtual machine to perform the platform
specific attach method. Buffers returned from this method are
internally managed as PhantomRefereces to provide for
guaranteed, secure release of the native resources.

    Params:
    • 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.
    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.
    Returns: ByteBuffer       a direct allocated byte buffer
    /**
     * Call the implementation specific attach method.
     * <p>
     * This method calls into the Java virtual machine to perform the platform
     * specific attach method. Buffers returned from this method are
     * internally managed as <code>PhantomRefereces</code> to provide for
     * guaranteed, secure release of the native resources.
     *
     * @param   user             A <code>String</code> 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.

    
The implementation of this method may return distinct or identical
ByteBuffer objects for two distinct calls requesting
attachment to the same Java virtual machine.

    
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.

    Params:
    • 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.
    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.
    Returns: ByteBuffer       a direct allocated byte buffer
    /**
     * Native method to perform the implementation specific attach mechanism.
     * <p>
     * The implementation of this method may return distinct or identical
     * <code>ByteBuffer</code> objects for two distinct calls requesting
     * attachment to the same Java virtual machine.
     * <p>
     * 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 <code>String</code> 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.

    
If this method is passed a 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.

    
If this method is passed a 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.

    Params:
    • ByteBuffer –  A direct allocated byte buffer created by the
                   attach method.
    See Also:
    /**
     * Native method to perform the implementation specific detach mechanism.
     * <p>
     * If this method is passed a <code>ByteBuffer</code> object that is
     * not created by the <code>attach</code> 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 <code>
     * attach</code> method are managed internally as PhantomReferences
     * and resources are freed by the system.
     * <p>
     * If this method is passed a <code>ByteBuffer</code> object created
     * by the <code>attach</code> 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
     *                    <code>attach</code> 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.

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

    Params:
    • variability – the variability characteristic for this entry.
    • units –       the units for this entry.
    • name –        the name of this entry.
    • value –       the initial value for this entry.
    See Also:
    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
    /**
     * Create a <code>long</code> scalar entry in the instrumentation buffer
     * with the given variability characteristic, units, and initial value.
     * <p>
     * Access to the instrument is provided through the returned <code>
     * ByteBuffer</code> object. Typically, this object should be wrapped
     * with <code>LongBuffer</code> 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 <code>long</code> 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.

    
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.

    Params:
    • variability – the variability characteristic for this entry.
    • units –       the units for this entry.
    • name –        the name of this entry.
    • value –       the initial value for this entry.
    • maxLength –   the maximum string length for this string
                     instrument.
    See Also:
    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
    /**
     * Create a <code>String</code> entry in the instrumentation buffer with
     * the given variability characteristic, units, and initial value.
     * <p>
     * The maximum length of the <code>String</code> stored in this string
     * instrument is given in by <code>maxLength</code> parameter. Updates
     * to this instrument with <code>String</code> values with lengths greater
     * than <code>maxLength</code> will be truncated to <code>maxLength</code>.
     * The truncated value will be terminated by a null character.
     * <p>
     * The underlying implementation may further limit the length of the
     * value, but will continue to preserve the null terminator.
     * <p>
     * Access to the instrument is provided through the returned <code>
     * ByteBuffer</code> 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 <code>long</code> 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.

    
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.

    Params:
    • variability – the variability characteristic for this entry.
    • units –       the units for this entry.
    • name –        the name of this entry.
    • value –       the initial value for this entry.
    See Also:
    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
    /**
     * Create a <code>String</code> entry in the instrumentation buffer with
     * the given variability characteristic, units, and initial value.
     * <p>
     * The maximum length of the <code>String</code> stored in this string
     * instrument is implied by the length of the <code>value</code> 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.
     * <p>
     * The underlying implementation may further limit the length of the
     * initial or subsequent value, but will continue to preserve the null
     * terminator.
     * <p>
     * Access to the instrument is provided through the returned <code>
     * ByteBuffer</code> 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 <code>long</code> 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.

    
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.

    Params:
    • variability – the variability characteristic for this entry.
    • units –       the units for this entry.
    • name –        the name of this entry.
    • value –       the initial value for this entry.
    • maxLength –   the maximum length of this byte array.
    See Also:
    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
    /**
     * Create a <code>byte</code> vector entry in the instrumentation buffer
     * with the given variability characteristic, units, and initial value.
     * <p>
     * The <code>maxLength</code> 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.
     * <p>
     * The underlying implementation may further limit the length of the
     * length of the initial or subsequent value.
     * <p>
     * Access to the instrument is provided through the returned <code>
     * ByteBuffer</code> 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 <code>long</code> 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

    /**
     * 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 highResFrequency method. 
    See Also:
    Returns: the number of ticks of machine dependent resolution since
         the start of the Java virtual machine.
    /**
     * 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 highResCounter method, into the number of seconds since the start of the Java virtual machine. 
    See Also:
    Returns: the frequency of the High Resolution Counter.
    /**
     * 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();
    }
}