JVMTI Demonstration Code

The Java^TM Virtual Machine Tools Interface (JVMTI) is a native tool interface provided in v1.5. Native libraries that use JVMTI and are loaded into the Java^TM Virtual Machine via the -agentlib, -agentpath, or -Xrun (deprecated) interfaces, are called Agents.

JVMTI was designed to work with the Java^TM Native Interface (JNI), and eventually displace the Java^TM Virtual Machine Debugging Interface (JVMDI) and the Java^TM Virtual Machine Profiling Interface (JVMPI).

We have tried to create a set of demonstration agents that should help demonstrate many of the features and abilities of the interface. This list of demonstration agents will change over time. They are provided as educational tools and as starting points for Java^TM tool development.

Agents

• versionCheck
  This is a extremely small agent that does nothing but check the version string supplied in the jvmti.h file, with the version number supplied by the VM at runtime.
• mtrace
  This is a small agent that does method tracing. It uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
• gctest
  This is a small agent that does garbage collection counting.
• heapViewer
  This is a small agent that does some basic heap inspections.
• heapTracker
  This is a small agent that does BCI to capture object creation and track them. It uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
• waiters
  This is a small agent that gets information about threads waiting on monitors.
• hprof
  This is a large agent that does heap and cpu profiling. This demo agent is actually built into the Java^TM Runtime Environment (JRE). It uses Bytecode Instrumentation (BCI) via the java_crw_demo library.
  Note: hprof is NOT a small or simple agent, the other smaller demos should be looked at first.

Agent Support

• java_crw_demo
  This is a demo C library that does class file to class file transformations or BCI (Bytecode Instrumentation). It is used by several of the above agents.

Native Library Build Hints

All libraries loaded into java are assumed to be MT-safe (Multi-thread safe). This means that multiple threads could be executing the code at the same time, and static or global data may need to be placed in critical sections. See the Raw Monitor interfaces for more information.

All native libraries loaded into the Java^TM Virtual Machine, including Agent libraries, need to be compiled and built in a compatible way. Certain native compilation options or optimizations should be avoided, and some are required. More information on this options is available in the man pages for the various compilers.

• On Solaris and using the Sun C/C++ Compilers 5.5 (Studio 8 Compiler Collection):
  • Required: On SPARC, -xarch=v8 or -xarch=v9
    This is to be specific as to the sparc architecture. Be careful when using -xarch and some of the other compiler optimization options that target specific processors, you can easily limit the types of machines the library will run on, e.g. using -xarch=v9b will limit you to UltraSPARC III capable processor.
  • Required: -mt
    This should be used for compiles and links, it makes sure the library is built properly to be a MT-safe library.
  • Required: On SPARC, -xregs=no%appl.
    Certain registers should not be used by system libraries.
  • Recommended: No higher than -xO2 on optimization.
    It is important that these libraries have frame pointer register usage. Optimizations above -xO2 can remove the use of frame pointer registers and cause problems when doing stack frame walking.
  • Recommended: ldd -r LibraryName
    After the shared library has been built, the utility 'ldd' (or 'ldd -r') can be used to verify that all dependent libraries have been satisfied, and all externs can be found. If 'ldd' says anything is missing, it is very likely that the JVM will be unable to load this library.
• On Linux (Using the gcc version 3.2):
  • Required: -fno-omit-frame-pointer
    It is important that these libraries have frame pointer register usage.
  • Recommended: -fno-strict-aliasing
    Avoid this pointer optimization.
  • Required: -Wl,-soname=LibraryName
    When building the shared library (-shared option), this option makes sure the library name is stored inside the library.
  • Required: -static-libgcc
    When building the shared library (-shared option), this option allows for maximum portability of the library between different flavors of Linux.
  • Recommended: ldd -r LibraryName
    Provides the same checking as Solaris (see above).
• On Windows and using the Microsoft C++ Compiler:
  • Recommended: -Op.
    Avoid optimizations that change floating point precision.
  • Required: -Gy.
    Allow for function level linking.
  • Recommended: VC++ dumpbin/exports and VC++ "Dependency Walker"
    Provides dependency information similar to ldd.

For More Information

For more detailed information on JVMTI, refer to http://java.sun.com/j2se/1.5.0/docs/guide/jvmti.

More information on using JNI and building native libraries refer to: http://java.sun.com/j2se/1.5.0/docs/guide/jni.

Additional information can also be found by doing a search on "JVMTI" at http://java.sun.com/j2se. Various technical articles are also available through this website. And don't forget the Java^TM Tutorials at http://java.sun.com/docs/books/tutorial for getting a quick start on all the various interfaces.

Comments and Feedback

Comments regarding JVMTI or on any of these demonstrations should be sent through http://java.sun.com/mail/