This package is an update to Vojtech Horky's PAPI for Java bindings. PAPI provides access to the CPU's hardware performance counters, which are special CPU features that allow the CPU to measure low-level events. See the PAPI homepage for more details.
- JDK 9 and later supported out of the box
- PAPI 6 supported (by removing
papi.Wrapper.startCounters()
andpapi.Wrapper.stopCounters()
; use the EventSet API instead.)
This package relies on:
- bash, GNU make, C/C++ build environment
- JDK 8 or later (tested with 8 and 11)
- Pre-existing PAPI installation on your system (PAPI 5 or 6 supported)
- user access to PAPI, e.g. by setting
/proc/sys/kernel/perf_event_paranoid
on Linux
You need to set the JAVA_HOME
variable first, to the directory from which include/jni.h
can be found.
You can build PAPI as follows:
bash:
./configure && make
fish:
./configure && make
The configuration script should auto-detect all relevant settings. Otherwise you override by setting:
PAPI_PATH
: path under which we can find theinclude
directory containing the PAPI headers (e.g.,/usr/
)PAPI_LIBRARY_PATH
: path that containslibpapi.so
JAVAC
: whichjavac
to useJAVAH
: which JNI code generator to use:javah
for JDK8, orjavac
for JDK 9 and later.
Try running the test:
make test
- If
make test
doesn't find thepapi
library, adjustPAPI_LIBRARY_PATH
to point to the directory that containslibpapi.so
. - If you get failures with error code -25, try setting
/proc/sys/kernel/perf_event_paranoid
to a lower value (such as 0). - Migration: if you used an older version of this library and noticed that
papi.Wrapper.startCounters()
andpapi.Wrapper.stopCounters()
are missing: please migrate as follows:
papi.Wrapper.startCounters(COUNTERS);
...
papi.Wrapper.stopCounters(OUT);
should become
// if you were checking return codes before: the EventSet uses exceptions instead
EventSet s = papi.EventSet.create(COUNTERS);
s.start();
...
s.stop();
OUT = s.getCounters();
Papi.init();
EventSet evset = EventSet.create(Constants.PAPI_TOT_CYC, Constants.PAPI_L1_DCM);
evset.start();
// execute the code you want to measure
evset.stop();
long[] data = evset.getCounters();
See also example/Demo.java
for a full demo.
The PAPI performance counter documentation is very helpful to understand what it is that you are measuring.
- Copyright (c) 2014 Charles University in Prague
- Copyright (c) 2014 Vojtech Horky
- Copyright (c) 2018-2021 Christoph Reichenbach
- Expose more of the PAPI API
- JavaDoc
- Turn PAPI events into enum, so we can use
EnumSet.all()
to iterate over all events - Make PAPI events self-documenting
- Use PapiRuntimeExceptions throughout