5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package sun.misc;
26
27 import java.nio.ByteBuffer;
28 import java.security.Permission;
29 import java.security.PrivilegedAction;
30 import java.io.IOException;
31 import java.io.UnsupportedEncodingException;
32
33 /**
34 * The Perf class provides the ability to attach to an instrumentation
35 * buffer maintained by a Java virtual machine. The instrumentation
36 * buffer may be for the Java virtual machine running the methods of
37 * this class or it may be for another Java virtual machine on the
38 * same system.
39 * <p>
40 * In addition, this class provides methods to create instrumentation
41 * objects in the instrumentation buffer for the Java virtual machine
42 * that is running these methods. It also contains methods for acquiring
43 * the value of a platform specific high resolution clock for time
44 * stamp and interval measurement purposes.
45 *
46 * @author Brian Doherty
47 * @since 1.4.2
48 * @see #getPerf
49 * @see sun.misc.Perf$GetPerfAction
50 * @see java.nio.ByteBuffer
51 */
52 public final class Perf {
53
54 private static Perf instance;
55
56 private static final int PERF_MODE_RO = 0;
57 private static final int PERF_MODE_RW = 1;
58
59 private Perf() { } // prevent instantiation
60
61 /**
62 * The GetPerfAction class is a convenience class for acquiring access
63 * to the singleton Perf instance using the
64 * <code>AccessController.doPrivileged()</code> method.
65 * <p>
66 * An instance of this class can be used as the argument to
67 * <code>AccessController.doPrivileged(PrivilegedAction)</code>.
68 * <p> Here is a suggested idiom for use of this class:
69 *
107 * Java virtual machine.
108 * <p>
109 * If a security manager is installed, its <code>checkPermission</code>
110 * method is called with a <code>RuntimePermission</code> with a target
111 * of <em>"sun.misc.Perf.getPerf"</em>. A security exception will result
112 * if the caller has not been granted this permission.
113 * <p>
114 * Access to the returned <code>Perf</code> object should be protected
115 * by its caller and not passed on to untrusted code. This object can
116 * be used to attach to the instrumentation buffer provided by this Java
117 * virtual machine or for those of other Java virtual machines running
118 * on the same system. The instrumentation buffer may contain senstitive
119 * information. API's built on top of this interface may want to provide
120 * finer grained access control to the contents of individual
121 * instrumentation objects contained within the buffer.
122 * <p>
123 * Please note that the <em>"sun.misc.Perf.getPerf"</em> permission
124 * is not a JDK specified permission.
125 *
126 * @return A reference to the singleton Perf instance.
127 * @throws AccessControlException if a security manager exists and
128 * its <code>checkPermission</code> method doesn't allow
129 * access to the <em>"sun.misc.Perf.getPerf"</em> target.
130 * @see java.lang.RuntimePermission
131 * @see #attach
132 */
133 public static Perf getPerf()
134 {
135 SecurityManager security = System.getSecurityManager();
136 if (security != null) {
137 Permission perm = new RuntimePermission("sun.misc.Perf.getPerf");
138 security.checkPermission(perm);
139 }
140
141 return instance;
142 }
143
144 /**
145 * Attach to the instrumentation buffer for the specified Java virtual
146 * machine.
147 * <p>
148 * This method will attach to the instrumentation buffer for the
149 * specified virtual machine. It returns a <code>ByteBuffer</code> object
150 * that is initialized to access the instrumentation buffer for the
151 * indicated Java virtual machine. The <code>lvmid</code> parameter is
152 * a integer value that uniquely identifies the target local Java virtual
153 * machine. It is typically, but not necessarily, the process id of
154 * the target Java virtual machine.
155 * <p>
156 * If the <code>lvmid</code> identifies a Java virtual machine different
157 * from the one running this method, then the coherency characteristics
260 * @throws IllegalArgumentException The lvmid or mode was invalid.
261 * @throws IOException An I/O error occurred while trying to acquire
262 * the instrumentation buffer.
263 * @throws OutOfMemoryError The instrumentation buffer could not be mapped
264 * into the virtual machine's address space.
265 */
266 private ByteBuffer attachImpl(String user, int lvmid, int mode)
267 throws IllegalArgumentException, IOException
268 {
269 final ByteBuffer b = attach(user, lvmid, mode);
270
271 if (lvmid == 0) {
272 // The native instrumentation buffer for this Java virtual
273 // machine is never unmapped.
274 return b;
275 }
276 else {
277 // This is an instrumentation buffer for another Java virtual
278 // machine with native resources that need to be managed. We
279 // create a duplicate of the native ByteBuffer and manage it
280 // with a Cleaner object (PhantomReference). When the duplicate
281 // becomes only phantomly reachable, the native resources will
282 // be released.
283
284 final ByteBuffer dup = b.duplicate();
285 Cleaner.create(dup, new Runnable() {
286 public void run() {
287 try {
288 instance.detach(b);
289 }
290 catch (Throwable th) {
291 // avoid crashing the reference handler thread,
292 // but provide for some diagnosability
293 assert false : th.toString();
294 }
295 }
296 });
297 return dup;
298 }
299 }
300
301 /**
302 * Native method to perform the implementation specific attach mechanism.
303 * <p>
304 * The implementation of this method may return distinct or identical
305 * <code>ByteBuffer</code> objects for two distinct calls requesting
306 * attachment to the same Java virtual machine.
307 * <p>
308 * For the Sun HotSpot JVM, two distinct calls to attach to the same
309 * target Java virtual machine will result in two distinct ByteBuffer
310 * objects returned by this method. This may change in a future release.
311 *
312 * @param user A <code>String</code> object containing the
313 * name of the user that owns the target Java
314 * virtual machine.
315 * @param lvmid an integer that uniquely identifies the
316 * target local Java virtual machine.
317 * @param mode a string indicating the attach mode.
318 * @return ByteBuffer a direct allocated byte buffer
324 */
325 private native ByteBuffer attach(String user, int lvmid, int mode)
326 throws IllegalArgumentException, IOException;
327
328 /**
329 * Native method to perform the implementation specific detach mechanism.
330 * <p>
331 * If this method is passed a <code>ByteBuffer</code> object that is
332 * not created by the <code>attach</code> method, then the results of
333 * this method are undefined, with unpredictable and potentially damaging
334 * effects to the Java virtual machine. To prevent accidental or malicious
335 * use of this method, all native ByteBuffer created by the <code>
336 * attach</code> method are managed internally as PhantomReferences
337 * and resources are freed by the system.
338 * <p>
339 * If this method is passed a <code>ByteBuffer</code> object created
340 * by the <code>attach</code> method with a lvmid for the Java virtual
341 * machine running this method (lvmid=0, for example), then the detach
342 * request is silently ignored.
343 *
344 * @param ByteBuffer A direct allocated byte buffer created by the
345 * <code>attach</code> method.
346 * @see java.nio.ByteBuffer
347 * @see #attach
348 */
349 private native void detach(ByteBuffer bb);
350
351 /**
352 * Create a <code>long</code> scalar entry in the instrumentation buffer
353 * with the given variability characteristic, units, and initial value.
354 * <p>
355 * Access to the instrument is provided through the returned <code>
356 * ByteBuffer</code> object. Typically, this object should be wrapped
357 * with <code>LongBuffer</code> view object.
358 *
359 * @param variability the variability characteristic for this entry.
360 * @param units the units for this entry.
361 * @param name the name of this entry.
362 * @param value the initial value for this entry.
363 * @return ByteBuffer a direct allocated ByteBuffer object that
364 * allows write access to a native memory location
|
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package jdk.internal.perf;
26
27 import java.lang.ref.Cleaner;
28 import java.nio.ByteBuffer;
29 import java.security.Permission;
30 import java.security.PrivilegedAction;
31 import java.io.IOException;
32 import java.io.UnsupportedEncodingException;
33
34 /**
35 * The Perf class provides the ability to attach to an instrumentation
36 * buffer maintained by a Java virtual machine. The instrumentation
37 * buffer may be for the Java virtual machine running the methods of
38 * this class or it may be for another Java virtual machine on the
39 * same system.
40 * <p>
41 * In addition, this class provides methods to create instrumentation
42 * objects in the instrumentation buffer for the Java virtual machine
43 * that is running these methods. It also contains methods for acquiring
44 * the value of a platform specific high resolution clock for time
45 * stamp and interval measurement purposes.
46 *
47 * @author Brian Doherty
48 * @since 1.4.2
49 * @see #getPerf
50 * @see jdk.internal.perf.Perf.GetPerfAction
51 * @see java.nio.ByteBuffer
52 */
53 public final class Perf {
54
55 private static Perf instance;
56
57 private static final int PERF_MODE_RO = 0;
58 private static final int PERF_MODE_RW = 1;
59
60 private Perf() { } // prevent instantiation
61
62 /**
63 * The GetPerfAction class is a convenience class for acquiring access
64 * to the singleton Perf instance using the
65 * <code>AccessController.doPrivileged()</code> method.
66 * <p>
67 * An instance of this class can be used as the argument to
68 * <code>AccessController.doPrivileged(PrivilegedAction)</code>.
69 * <p> Here is a suggested idiom for use of this class:
70 *
108 * Java virtual machine.
109 * <p>
110 * If a security manager is installed, its <code>checkPermission</code>
111 * method is called with a <code>RuntimePermission</code> with a target
112 * of <em>"sun.misc.Perf.getPerf"</em>. A security exception will result
113 * if the caller has not been granted this permission.
114 * <p>
115 * Access to the returned <code>Perf</code> object should be protected
116 * by its caller and not passed on to untrusted code. This object can
117 * be used to attach to the instrumentation buffer provided by this Java
118 * virtual machine or for those of other Java virtual machines running
119 * on the same system. The instrumentation buffer may contain senstitive
120 * information. API's built on top of this interface may want to provide
121 * finer grained access control to the contents of individual
122 * instrumentation objects contained within the buffer.
123 * <p>
124 * Please note that the <em>"sun.misc.Perf.getPerf"</em> permission
125 * is not a JDK specified permission.
126 *
127 * @return A reference to the singleton Perf instance.
128 * @throws SecurityException if a security manager exists and its
129 * <code>checkPermission</code> method doesn't allow access
130 * to the <em>"jdk.internal.perf.Perf.getPerf""</em> target.
131 * @see java.lang.RuntimePermission
132 * @see #attach
133 */
134 public static Perf getPerf()
135 {
136 SecurityManager security = System.getSecurityManager();
137 if (security != null) {
138 Permission perm = new RuntimePermission("jdk.internal.perf.Perf.getPerf");
139 security.checkPermission(perm);
140 }
141
142 return instance;
143 }
144
145 /**
146 * Attach to the instrumentation buffer for the specified Java virtual
147 * machine.
148 * <p>
149 * This method will attach to the instrumentation buffer for the
150 * specified virtual machine. It returns a <code>ByteBuffer</code> object
151 * that is initialized to access the instrumentation buffer for the
152 * indicated Java virtual machine. The <code>lvmid</code> parameter is
153 * a integer value that uniquely identifies the target local Java virtual
154 * machine. It is typically, but not necessarily, the process id of
155 * the target Java virtual machine.
156 * <p>
157 * If the <code>lvmid</code> identifies a Java virtual machine different
158 * from the one running this method, then the coherency characteristics
261 * @throws IllegalArgumentException The lvmid or mode was invalid.
262 * @throws IOException An I/O error occurred while trying to acquire
263 * the instrumentation buffer.
264 * @throws OutOfMemoryError The instrumentation buffer could not be mapped
265 * into the virtual machine's address space.
266 */
267 private ByteBuffer attachImpl(String user, int lvmid, int mode)
268 throws IllegalArgumentException, IOException
269 {
270 final ByteBuffer b = attach(user, lvmid, mode);
271
272 if (lvmid == 0) {
273 // The native instrumentation buffer for this Java virtual
274 // machine is never unmapped.
275 return b;
276 }
277 else {
278 // This is an instrumentation buffer for another Java virtual
279 // machine with native resources that need to be managed. We
280 // create a duplicate of the native ByteBuffer and manage it
281 // with a Cleaner. When the duplicate becomes phantom reachable,
282 // the native resources will be released.
283
284 final ByteBuffer dup = b.duplicate();
285
286 Cleaner cleaner = java.security.AccessController.doPrivileged(
287 new PrivilegedAction<Cleaner>() {
288 public Cleaner run() {
289 return Cleaner.create();
290 }
291 });
292 cleaner.register(dup, new CleanerAction(instance, b));
293 return dup;
294 }
295 }
296
297 private static class CleanerAction implements Runnable {
298 private final ByteBuffer bb;
299 private final Perf perf;
300 CleanerAction(Perf perf, ByteBuffer bb) {
301 this.perf = perf;
302 this.bb = bb;
303 }
304 public void run() {
305 try {
306 perf.detach(bb);
307 } catch (Throwable th) {
308 // avoid crashing the reference handler thread,
309 // but provide for some diagnosability
310 assert false : th.toString();
311 }
312 }
313 }
314
315 /**
316 * Native method to perform the implementation specific attach mechanism.
317 * <p>
318 * The implementation of this method may return distinct or identical
319 * <code>ByteBuffer</code> objects for two distinct calls requesting
320 * attachment to the same Java virtual machine.
321 * <p>
322 * For the Sun HotSpot JVM, two distinct calls to attach to the same
323 * target Java virtual machine will result in two distinct ByteBuffer
324 * objects returned by this method. This may change in a future release.
325 *
326 * @param user A <code>String</code> object containing the
327 * name of the user that owns the target Java
328 * virtual machine.
329 * @param lvmid an integer that uniquely identifies the
330 * target local Java virtual machine.
331 * @param mode a string indicating the attach mode.
332 * @return ByteBuffer a direct allocated byte buffer
338 */
339 private native ByteBuffer attach(String user, int lvmid, int mode)
340 throws IllegalArgumentException, IOException;
341
342 /**
343 * Native method to perform the implementation specific detach mechanism.
344 * <p>
345 * If this method is passed a <code>ByteBuffer</code> object that is
346 * not created by the <code>attach</code> method, then the results of
347 * this method are undefined, with unpredictable and potentially damaging
348 * effects to the Java virtual machine. To prevent accidental or malicious
349 * use of this method, all native ByteBuffer created by the <code>
350 * attach</code> method are managed internally as PhantomReferences
351 * and resources are freed by the system.
352 * <p>
353 * If this method is passed a <code>ByteBuffer</code> object created
354 * by the <code>attach</code> method with a lvmid for the Java virtual
355 * machine running this method (lvmid=0, for example), then the detach
356 * request is silently ignored.
357 *
358 * @param bb A direct allocated byte buffer created by the
359 * <code>attach</code> method.
360 * @see java.nio.ByteBuffer
361 * @see #attach
362 */
363 private native void detach(ByteBuffer bb);
364
365 /**
366 * Create a <code>long</code> scalar entry in the instrumentation buffer
367 * with the given variability characteristic, units, and initial value.
368 * <p>
369 * Access to the instrument is provided through the returned <code>
370 * ByteBuffer</code> object. Typically, this object should be wrapped
371 * with <code>LongBuffer</code> view object.
372 *
373 * @param variability the variability characteristic for this entry.
374 * @param units the units for this entry.
375 * @param name the name of this entry.
376 * @param value the initial value for this entry.
377 * @return ByteBuffer a direct allocated ByteBuffer object that
378 * allows write access to a native memory location
|