DiSL

DiSL is a Java bytecode instrumentation framework intended for observation of programs executing in the Java Virtual Machine. It has been mainly used for development of dynamic program analysis instrumentations, but it can be used equally well to develop instrumentations for, e.g. runtime performance monitoring, or other tasks not bent on altering program execution.

DiSL is inspired by AOP, but in contrast to mainstream AOP languages, it features an open join point model where any region of bytecodes can serve as a join point (i.e., code location to be instrumented). DiSL also reconciles high-level language concepts, such as the pointcut/advice programming model found in AOP, with high expressiveness, and efficiency of bytecode manipulation performed using low-level libraries such as ASM. As a result, instrumentations written using DiSL almost as compact as aspects written in AspectJ, but perform about as fast as those written using ASM.

However, in contrast to AspectJ, DiSL does not restrict the code locations that can be instrumented, and the code generated by DiSL avoids expensive operations (such as object allocations that are not visible to the programmer). Furthermore, DiSL supports instrumentations with complete bytecode coverage out-of-the-box and avoids structural modifications of classes that would be visible through reflection and could break the instrumented code.

INSTALL

If you have downloaded a binary distribution of DiSL, this step is not necessary. Simply extract the archive to a preferred location and update your project to use it.

If you have downloaded a source distribution of DiSL, you need to compile it first by running the ant command in the top-level directory.

While most of the DiSL is written in Java, it requires a JVM enhanced with a native agent written in C. Compiling the agent requires JNI header files for your platform. For commonly used platforms, these are part of the DiSL source distribution. Should the compilation fail on your machine, you may need to modify Makefile.local files in the src-disl-agent and src-shvm-agent directories to override the default value of the INCLUDE_DIR variable.

DiSL currently fully supports "Linux" and "OS X" platforms with Java, ant, GCC and make installed and found on the executable path. DiSL has been used on the Windows/Cygwin platform as well, and there is experimental support for cross- compiling the DiSL agent for the Win32/Win64 platforms using MinGW. However, these targets were not extensively tested.

DOCUMENTATION

After building DiSL, you will find the API documentation in the output/jdoc directory, and document containing an introduction to instrumenting applications with DiSL in the output/build/intro directory. However, to build the document, you will need a working LaTeX installation with pdflatex.

EXAMPLES

For a set of simple examples showcasing basic DiSL features, please check the examples directory.

In addition, the src-test directory contains additional examples used for testing other DiSL features -- these can be run using Ant.

USER ERRORS

If you get a Java error during instrumentation or running your application, please consult the USER_ERRORS document describing some of the most common problems.