1================================
2'hotspot_jni' PROBES DESCRIPTION
3================================
4
5This directory contains D scripts which demonstrate usage of 'hotspot_jni'
6provider probes.
7
8In order to call from native code to Java code, due to embedding of the VM
9in an application or execution of native code within a Java application, the
10native code must make a call through the JNI interface. The JNI interface
11provides a number of methods for invoking Java code and examining the state
12of the VM. DTrace probes are provided at the entry point and return point
13for each of these methods. The probes are provided by the hotspot_jni
14provider. The name of the probe is the name of the JNI method, appended with
15"-entry" for entry probes, and "-return" for return probes. The arguments
16available at each entry probe are the arguments that were provided to the
17function (with the exception of the Invoke* methods, which omit the
18arguments that are passed to the Java method). The return probes have the
19return value of the method as an argument (if available).
20
21You can find more information about HotSpot probes here:
22http://java.sun.com/javase/6/docs/technotes/guides/vm/dtrace.html
23
24===========
25THE SCRIPTS
26===========
27
28The following scripts/samples which demonstrate hotspot_jni probes usage are
29available:
30
31- CriticalSection.d
32  Inspect a JNI application for Critical Section violations.
33
34- CriticalSection_slow.d
35  Do the same as CriticalSection.d but provide more debugging info.
36
37- hotspot_jni_calls_stat.d
38  This script collects statistics about how many times particular JNI method
39  has been called.
40
41- hotspot_jni_calls_tree.d
42  The script prints tree of JNI method calls.
43
44See more details in the scripts.
45
46
47==========
48HOW TO RUN
49==========
50To run any dscript from hotspot directory you can do either:
51
52 # dscript.d -c "java ..."
53
54 or if you don't have Solaris 10 patch which allows to specify probes that
55 don't yet exist ( Hotspot DTrace probes are defined in libjvm.so and as
56 result they could be not been yet loaded when you try to attach dscript to
57 the Java process) do:
58
59 # ../helpers/dtrace_helper.d -c "java ..." dscript.d
60
61 or if your application is already running you can just simply attach
62 the D script like:
63
64 # dscript.d -p JAVA_PID
65