diff options
Diffstat (limited to 'bindings/java')
29 files changed, 1782 insertions, 0 deletions
diff --git a/bindings/java/.gitignore b/bindings/java/.gitignore new file mode 100644 index 0000000..32690c1 --- /dev/null +++ b/bindings/java/.gitignore @@ -0,0 +1,7 @@ +# .gitignore for ppamltracer-java -*- conf -*- + +build/ +dist/ + +# Examples +examples/dist diff --git a/bindings/java/README b/bindings/java/README new file mode 100644 index 0000000..b5d4bfb --- /dev/null +++ b/bindings/java/README @@ -0,0 +1,12 @@ + ppamltracer-java, v0.1.0 + +This package contains Java bindings to ppamltracer. They require Java SE 5 or +later. + +This package uses the Java Native Interface. Therefore, building it produces +two artifacts: a jar, which you should install in your CLASSPATH, and a shared +library, which you should install in your LD_LIBRARY_PATH. If you have both +Ant and autotools installed, simply typing `ant' will build both artifacts and +install them in the `dist' directory. + +For examples of use, see the examples directory. diff --git a/bindings/java/build.xml b/bindings/java/build.xml new file mode 100644 index 0000000..d4e57f6 --- /dev/null +++ b/bindings/java/build.xml @@ -0,0 +1,165 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- build.xml: Ant build file for ppamltracer +Copyright (C) 2014 Galois, Inc. + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any later +version. + +This program is distributed in the hope that it will be useful, but WITHOUT +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +details. + +You should have received a copy of the GNU General Public License along with +this program. If not, see <http://www.gnu.org/licenses/>. + +To contact Galois, complete the Web form at <http://corp.galois.com/contact/> +or write to Galois, Inc., 421 Southwest 6th Avenue, Suite 300, Portland, +Oregon, 97204-1622. --> + +<project name="ppamltracer-java" basedir="." default="link-and-package"> + + <property name="project.shortname" value="ppamltracer" /> + <property name="project.version" value="0.1.0" /> + <property name="package" value="com.galois.ppaml.tracer" /> + + <property name="src" location="src" /> + <property name="src.java" location="${src}/java" /> + <property name="src.c" location="${src}/c" /> + + <property name="build" location="build" /> + <property name="build.classes" location="${build}/classes" /> + <property name="build.native" location="${build}/native" /> + + <property name="dist" location="dist" /> + <property name="doc" location="${dist}/doc" /> + + <target name="java.compile"> + <mkdir dir="${build.classes}" /> + <javac srcdir="${src}" + destdir="${build.classes}" + includeantruntime="false" /> + </target> + + <target name="java.package" depends="java.compile"> + <mkdir dir="${dist}" /> + <jar destfile="${dist}/${project.shortname}-${project.version}.jar" + basedir="${build.classes}" /> + </target> + + <!-- Assemble the native sources with their JNI-generated headers. --> + <target name="native.prepare" depends="java.compile"> + <copy todir="${build.native}"> + <fileset dir="${src.c}" /> + </copy> + <javah classpath="${build.classes}" + class="${package}.Tracer,${package}.Phase" + destdir="${build.native}" + verbose="yes" /> + </target> + + <!-- Do the autotools dance. --> + <target name="native.autotools" depends="native.prepare"> + <mkdir dir="${build.native}/m4" /> + <exec executable="autoreconf" + dir="${build.native}" + failonerror="true"> + <arg value="--install" /> + <arg value="-Wall" /> + </exec> + </target> + + <target name="native.compile" depends="native.autotools"> + <exec executable="./configure" + dir="${build.native}" + failonerror="true"> + <arg value="--prefix=${dist}" /> + </exec> + <exec executable="make" dir="${build.native}" failonerror="true" /> + </target> + + <target name="native.install" depends="native.compile"> + <mkdir dir="${dist}" /> + <exec executable="make" dir="${build.native}" failonerror="true"> + <arg value="install" /> + </exec> + </target> + + <target name="compile" depends="java.compile,native.compile" /> + + <target name="link-and-package" depends="java.package,native.install" /> + + <target name="doc"> + <javadoc sourcepath="${src}" + destdir="${doc}" + packagenames="${package}" + access="public"> + <fileset dir="${src.java}"> + <include name="**" /> + </fileset> + </javadoc> + <!-- Work around CVE-2013-1571 (frame injection vulnerability in generated + docs.) Hopefully, you're running a new enough JDK that this isn't + necessary, but one can never assume. --> + <patch-javadoc dir="${doc}" /> + </target> + + <target name="clean"> + <delete dir="${build}"/> + <delete dir="${dist}"/> + </target> + + <!-- Task to work around CVE-2013-1571. See Ant #55132 + <https://issues.apache.org/bugzilla/show_bug.cgi?id=55132>. --> + <macrodef name="patch-javadoc"> + <attribute name="dir"/> + <attribute name="docencoding" default="${file.encoding}"/> + <sequential> + <replace encoding="@{docencoding}" summary="true" taskname="patch-javadoc"> + <fileset dir="@{dir}" casesensitive="false" includes="**/index.html,**/index.htm,**/toc.html,**/toc.htm"> + <not><contains text="function validURL(url) {" casesensitive="true" /></not> + </fileset> + <replacetoken><![CDATA[function loadFrames() {]]></replacetoken> + <replacevalue expandProperties="false"><![CDATA[if (targetPage != "" && !validURL(targetPage)) + function validURL(url) { // FIXED FIXED FIXED + var pos = url.indexOf(".html"); + if (pos == -1 || pos != url.length - 5) + return false; + var allowNumber = false; + var allowSep = false; + var seenDot = false; + for (var i = 0; i < url.length - 5; i++) { + var ch = url.charAt(i); + if ('a' <= ch && ch <= 'z' || + 'A' <= ch && ch <= 'Z' || + ch == '$' || + ch == '_') { + allowNumber = true; + allowSep = true; + } else if ('0' <= ch && ch <= '9' + || ch == '-') { + if (!allowNumber) + return false; + } else if (ch == '/' || ch == '.') { + if (!allowSep) + return false; + allowNumber = false; + allowSep = false; + if (ch == '.') + seenDot = true; + if (ch == '/' && seenDot) + return false; + } else { + return false; + } + } + return true; + } + function loadFrames() {]]></replacevalue> + </replace> + </sequential> + </macrodef> + +</project> diff --git a/bindings/java/examples/build.xml b/bindings/java/examples/build.xml new file mode 100644 index 0000000..e7f6f4d --- /dev/null +++ b/bindings/java/examples/build.xml @@ -0,0 +1,41 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- build.xml: Ant build file for ppamltracer Java examples +Copyright (C) 2014 Galois, Inc. + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any later +version. + +This program is distributed in the hope that it will be useful, but WITHOUT +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +details. + +You should have received a copy of the GNU General Public License along with +this program. If not, see <http://www.gnu.org/licenses/>. + +To contact Galois, complete the Web form at <http://corp.galois.com/contact/> +or write to Galois, Inc., 421 Southwest 6th Avenue, Suite 300, Portland, +Oregon, 97204-1622. --> + +<project name="ppamltracer-java-examples" basedir="." default="compile"> + + <property name="src" location="src" /> + + <property name="dist" location="dist" /> + <property name="dist.classes" location="${dist}/classes" /> + + + <target name="compile"> + <mkdir dir="${dist.classes}" /> + <javac srcdir="${src}" + destdir="${dist.classes}" + includeantruntime="true" /> + </target> + + <target name="clean"> + <delete dir="${dist}"/> + </target> + +</project> diff --git a/bindings/java/examples/src/com/galois/ppaml/tracer/examples/Simple.java b/bindings/java/examples/src/com/galois/ppaml/tracer/examples/Simple.java new file mode 100644 index 0000000..a698573 --- /dev/null +++ b/bindings/java/examples/src/com/galois/ppaml/tracer/examples/Simple.java @@ -0,0 +1,84 @@ +/* Simple -- basic ppamltracer example + * This file is in the public domain. */ + +package com.galois.ppaml.tracer.examples; + +import com.galois.ppaml.tracer.Phase; +import com.galois.ppaml.tracer.Tracer; + +public class Simple { + + protected Phase factPhase; + + protected Phase fibPhase; + + protected void go(Tracer tracer) { + // Register the phases. + factPhase = tracer.createPhase("fact"); + fibPhase = tracer.createPhase("fib"); + + // Print factorials. + System.out.print("Factorials:"); + for (int i = 0; i < 21; i++) { + System.out.print(" " + fact(i)); + } + System.out.println(); + + // Print Fibonacci numbers. + System.out.print("Fibonacci numbers:"); + for (int i = 0; i < 30; i++) { + System.out.print(" " + fib(i)); + } + System.out.println(); + + // Finalize phases and exit. + factPhase.close(); + fibPhase.close(); + } + + protected long fact(int n) { + // Record that we're running inside the factorial phase. + factPhase.start(); + // Compute the factorial. + long result; + if (n == 0) { + result = 1; + } else { + result = n * fact(n - 1); + } + // Return the result. + factPhase.stop(); + return result; + } + + protected int fib(int n) { + // Record that we're running inside the Fibonacci phase. + fibPhase.start(); + // Compute the nth Fibonacci number. + int result; + switch (n) { + case 0: + case 1: + result = n; + break; + default: + result = fib(n - 1) + fib(n - 2); + break; + } + // Return the result. + fibPhase.stop(); + return result; + } + + public static void main(String[] args) { + // Start ppamltracer. + Tracer tracer = new Tracer("/tmp/simple_report"); + + // Run the app. + (new Simple()).go(tracer); + + // Finalize ppamltracer and exit. + tracer.close(); + } + +} diff --git a/bindings/java/src/c/Makefile.am b/bindings/java/src/c/Makefile.am new file mode 100644 index 0000000..c30a4cf --- /dev/null +++ b/bindings/java/src/c/Makefile.am @@ -0,0 +1,39 @@ +# Makefile.am -- automake script for ppamltracer-java (JNI wrapper) +# Copyright (C) 2013, 2014 Galois, Inc. +# +# This program is free software: you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free Software +# Foundation, either version 3 of the License, or (at your option) any later +# version. +# +# This program is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +# details. +# +# You should have received a copy of the GNU General Public License along with +# this program. If not, see <http://www.gnu.org/licenses/>. +# +# To contact Galois, complete the Web form at <http://corp.galois.com/contact/> +# or write to Galois, Inc., 421 Southwest 6th Avenue, Suite 300, Portland, +# Oregon, 97204-1622. + +ACLOCAL_AMFLAGS = -I m4 + +lib_LTLIBRARIES = libppamltracer_java.la +libppamltracer_java_la_SOURCES = \ + $(srcdir)/com_galois_ppaml_tracer_Phase.c \ + $(srcdir)/com_galois_ppaml_tracer_Phase.h \ + $(srcdir)/com_galois_ppaml_tracer_Tracer.c \ + $(srcdir)/com_galois_ppaml_tracer_Tracer.h \ + $(srcdir)/pointer.h +libppamltracer_java_la_CFLAGS = \ + -std=c99 \ + -Wall \ + -Wextra \ + -Wno-unused-parameter \ + -pedantic \ + -I@JAVA_HOME@/include +libppamltracer_java_la_LDFLAGS = \ + $(AM_LDFLAGS) \ + -export-symbols-regex '^Java_' diff --git a/bindings/java/src/c/com_galois_ppaml_tracer_Phase.c b/bindings/java/src/c/com_galois_ppaml_tracer_Phase.c new file mode 100644 index 0000000..76f346b --- /dev/null +++ b/bindings/java/src/c/com_galois_ppaml_tracer_Phase.c @@ -0,0 +1,97 @@ +/* com_galois_ppaml_tracer_Phase.c -- JNI wrapper for com.galois.ppaml.tracer.Phase + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +#include <stdlib.h> + +#include <ppaml/tracer.h> + +#include <jni.h> +#include <com_galois_ppaml_tracer_Phase.h> + +#include "pointer.h" + +JNIEXPORT +jlong JNICALL Java_com_galois_ppaml_tracer_Phase_mallocPhase( + JNIEnv *const env, + jclass Phase) +{ + return jlong_of_pointer(malloc(sizeof(ppaml_phase_t))); +} + +JNIEXPORT +jint JNICALL Java_com_galois_ppaml_tracer_Phase_ppaml_1phase_1init( + JNIEnv *const env, + jclass Phase, + jlong tracer, + jlong phase, + jstring name) +{ + jint r; + // Allocate memory. + const char *const cName = (*env)->GetStringUTFChars(env, name, NULL); + if (cName == NULL) { + r = -1; + goto done; + } + // Perform the operation. + r = ppaml_phase_init( + pointer_of_jlong(tracer), + pointer_of_jlong(phase), + cName); + // Clean up. +done: (*env)->ReleaseStringUTFChars(env, name, cName); + return r; +} + +JNIEXPORT +jint JNICALL Java_com_galois_ppaml_tracer_Phase_ppaml_1phase_1done( + JNIEnv *const env, + jclass Phase, + jlong phase) +{ + return ppaml_phase_done(pointer_of_jlong(phase)); +} + +JNIEXPORT +void JNICALL Java_com_galois_ppaml_tracer_Phase_freePhase( + JNIEnv *const env, + jclass Phase, + jlong phase) +{ + free(pointer_of_jlong(phase)); +} + +JNIEXPORT +jint JNICALL Java_com_galois_ppaml_tracer_Phase_ppaml_1phase_1start( + JNIEnv *const env, + jclass Phase, + jlong phase) +{ + return ppaml_phase_start(pointer_of_jlong(phase)); +} + +JNIEXPORT +jint JNICALL Java_com_galois_ppaml_tracer_Phase_ppaml_1phase_1stop( + JNIEnv *const env, + jclass Phase, + jlong phase) +{ + return ppaml_phase_stop(pointer_of_jlong(phase)); +} diff --git a/bindings/java/src/c/com_galois_ppaml_tracer_Tracer.c b/bindings/java/src/c/com_galois_ppaml_tracer_Tracer.c new file mode 100644 index 0000000..2c23966 --- /dev/null +++ b/bindings/java/src/c/com_galois_ppaml_tracer_Tracer.c @@ -0,0 +1,76 @@ +/* com_galois_ppaml_tracer_Tracer.c -- JNI wrapper for com.galois.ppaml.tracer.Tracer + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +#include <stdlib.h> + +#include <ppaml/tracer.h> + +#include <jni.h> +#include <com_galois_ppaml_tracer_Tracer.h> + +#include "pointer.h" + +JNIEXPORT +jlong JNICALL Java_com_galois_ppaml_tracer_Tracer_mallocTracer( + JNIEnv *const env, + jclass Tracer) +{ + return jlong_of_pointer(malloc(sizeof(ppaml_tracer_t))); +} + +JNIEXPORT +jint JNICALL Java_com_galois_ppaml_tracer_Tracer_ppaml_1tracer_1init( + JNIEnv *const env, + jclass Tracer, + jlong tracer, + jstring reportNameBase) +{ + jint r; + // Allocate memory. + const char *const cReportNameBase = + (*env)->GetStringUTFChars(env, reportNameBase, NULL); + if (cReportNameBase == NULL) { + r = -1; + goto done; + } + // Perform the operation. + r = ppaml_tracer_init(pointer_of_jlong(tracer), cReportNameBase); + // Clean up. +done: (*env)->ReleaseStringUTFChars(env, reportNameBase, cReportNameBase); + return r; +} + +JNIEXPORT +jint JNICALL Java_com_galois_ppaml_tracer_Tracer_ppaml_1tracer_1done( + JNIEnv *const env, + jclass Tracer, + jlong tracer) +{ + return ppaml_tracer_done(pointer_of_jlong(tracer)); +} + +JNIEXPORT +void JNICALL Java_com_galois_ppaml_tracer_Tracer_freeTracer( + JNIEnv *const env, + jclass Tracer, + jlong tracer) +{ + free(pointer_of_jlong(tracer)); +} diff --git a/bindings/java/src/c/configure.ac b/bindings/java/src/c/configure.ac new file mode 100644 index 0000000..0d1556b --- /dev/null +++ b/bindings/java/src/c/configure.ac @@ -0,0 +1,58 @@ +# configure.ac -- autoconf script for ppamltracer-java (JNI wrapper) +# Copyright (C) 2013, 2014 Galois, Inc. +# +# This program is free software: you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free Software +# Foundation, either version 3 of the License, or (at your option) any later +# version. +# +# This program is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +# details. +# +# You should have received a copy of the GNU General Public License along with +# this program. If not, see <http://www.gnu.org/licenses/>. +# +# To contact Galois, complete the Web form at <http://corp.galois.com/contact/> +# or write to Galois, Inc., 421 Southwest 6th Avenue, Suite 300, Portland, +# Oregon, 97204-1622. + +# Fire up Autoconf. +AC_PREREQ([2.69]) +AC_INIT([ppamltracer-java], [0.1.0], [bbarenblat@galois.com]) + +# Fire up Automake. +AM_INIT_AUTOMAKE([-Wall -Wno-gnu -Werror foreign no-dist-gzip dist-bzip2]) +AC_CONFIG_MACRO_DIR([m4]) + +# Build quietly. +m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])]) + +# Build a C library. +AC_PROG_CC +AC_PROG_CC_C99 +# Automake 1.12 seems to require this, but automake 1.11 doesn't recognize it. +m4_ifdef([AM_PROG_AR], [AM_PROG_AR]) +LT_INIT + +# JNI +AC_ARG_VAR([JAVA_HOME], [path to JDK installation]) +if test -z "$JAVA_HOME"; then + AC_MSG_ERROR([empty JAVA_HOME environment variable; please set it to the path to your JDK installation]) +fi +AC_SUBST([JAVA_HOME]) + +# ppamltracer +AC_CHECK_HEADER([ppaml/tracer.h], + [], + [AC_MSG_ERROR([ppamltracer development headers are required (are they in C_INCLUDE_PATH?)])]) +AC_CHECK_LIB([ppamltracer], [ppaml_tracer_init], + [], + [AC_MSG_ERROR([libppamltracer is required (is it in LIBRARY_PATH?)])]) + +# Generate Makefile. +AC_CONFIG_FILES([Makefile]) + +# All done. +AC_OUTPUT diff --git a/bindings/java/src/c/pointer.h b/bindings/java/src/c/pointer.h new file mode 100644 index 0000000..123025d --- /dev/null +++ b/bindings/java/src/c/pointer.h @@ -0,0 +1,38 @@ +/* pointer.h -- pointer <-> jlong casts + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +#ifndef PPAML_TRACER_JAVA_POINTER_H +#define PPAML_TRACER_JAVA_POINTER_H + +#include <stdint.h> + +#include <jni.h> + +inline void *pointer_of_jlong(const jlong value) +{ + return (void *)(intptr_t)value; +} + +inline jlong jlong_of_pointer(void *const pointer) +{ + return (jlong)(intptr_t)pointer; +} + +#endif diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/CWrapper.java b/bindings/java/src/java/com/galois/ppaml/tracer/CWrapper.java new file mode 100644 index 0000000..5a7887a --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/CWrapper.java @@ -0,0 +1,184 @@ +/* CWrapper -- wrapping C structures + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * A class which wraps a C structure and associated functions. + * + * <p> This class is intended to work hand-in-hand with Java Native Interface + * code that follows a four-stage lifecycle: + * + * <dl> + * <dt>Allocation</dt><dd>The system reserves memory and resources needed by + * the structure.</dd> + * <dt>Initialization</dt><dd>The system installs data into the structure to + * make it ready for use.</dd> + * <dt>Finalization</dt><dd>The system cleans up the data structure under the + * assumption that it will not be used anymore.</dd> + * <dt>Freeing</dt><dd>The system releases memory and resources needed by the + * structure.</dd> + * </dl> + * + * This class defines abstract methods associated with each of these phases; by + * defining contracts on them, it can then consolidate the phases into two + * concretely-implemented operations: + * + * <dl> + * <dt>Open</dt><dd>The system allocates and initializes the underlying + * structure.</dd> + * <dt>Close</dt><dd>The system finalizes and frees the underlying + * structure.</dd> + * </dl> + * + * <p> <b>This class is not intended to be instantiated directly. Only + * instantiate its concrete subclasses. + */ +abstract class CWrapper { + + /** + * C pointer to the underlying data structure. + */ + protected long cPointer; + + + /////////////////////////// Low-level life cycle /////////////////////////// + + /** + * Reserves memory and resources needed by the structure. + * + * <p> <b>Precondition:</b> <code>cPointer</code> is <code>0</code>. + * + * <p> <b>Postcondition:</b> If allocation was successful, + * <code>cPointer</code> is not <code>0</code>. + */ + abstract protected void allocateCPointer(); + + /** + * Installs data into the structure to make it ready for use. + * + * <p> <b>Precondition:</b> Allocation succeeded. + */ + abstract protected void initializeCPointer(); + + /** + * Cleans up the structure under the assumption that it will not be used + * anymore. + * + * <p> <b>Precondition:</b> Initialization succeeded. + */ + abstract protected void finalizeCPointer(); + + /** + * Releases memory and resources needed by the structure. + * + * <p> <b>Precondition:</b> <code>cPointer</code> is not <code>0</code>. <br> + * <b>Precondition:</b> Finalization succeeded. + * + * <p> <b>Postcondition:</b> <code>cPointer</code> is <code>0</code>. + */ + abstract protected void freeCPointer(); + + + ////////////////////////// High-level life cycle ////////////////////////// + + /** + * Allocates and initializes the underlying structure. + * + * @throws OpenedException the underlying structure has already been opened. + * + * @throws NativeOutOfMemoryError allocation failed. + */ + protected synchronized void open() { + if (cPointer != 0) { + throw new OpenedException(); + } + allocateCPointer(); + if (cPointer == 0) { + throw new NativeOutOfMemoryError(); + } + initializeCPointer(); + } + + /** + * Finalizes and frees the underlying structure. + * + * @throws ClosedException the underlying structure has already been closed. + */ + public synchronized void close() { + if (cPointer == 0) { + throw new ClosedException(); + } + finalizeCPointer(); + freeCPointer(); + cPointer = 0; + } + + + ////////////////////////// Associated exceptions ////////////////////////// + + /** + * Signals that the underlying structure is already open. + */ + public class OpenedException extends java.lang.IllegalStateException { + + static final long serialVersionUID = -7226578680647930527L; + + /** + * Constructs a <code>CWrapper.OpenedException</code> with no detail + * message. + */ + protected OpenedException() { + super(); + } + + } + + /** + * Signals that the underlying structure is already closed. + */ + public class ClosedException extends java.lang.IllegalStateException { + + static final long serialVersionUID = -2471059099211958977L; + + /** + * Constructs a <code>CWrapper.ClosedException</code> with no detail + * message. + */ + protected ClosedException() { + super(); + } + + } + + + ////////////////////////////// Miscellaneous ////////////////////////////// + + @Override + protected void finalize() { + close(); + } + + @Override + protected Object clone() throws java.lang.CloneNotSupportedException { + throw new java.lang.CloneNotSupportedException(); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/ClockAcquisitionException.java b/bindings/java/src/java/com/galois/ppaml/tracer/ClockAcquisitionException.java new file mode 100644 index 0000000..68b212d --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/ClockAcquisitionException.java @@ -0,0 +1,35 @@ +/* ClockAcquisitionException -- failure to get the time + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure to get the current time. This could be due to any number + * of operating-system dependent factors. + */ +public class ClockAcquisitionException extends TimingException { + + static final long serialVersionUID = -5730008048750495655L; + + protected ClockAcquisitionException() { + super("could not get current time"); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/NativeOutOfMemoryError.java b/bindings/java/src/java/com/galois/ppaml/tracer/NativeOutOfMemoryError.java new file mode 100644 index 0000000..7c5ca3e --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/NativeOutOfMemoryError.java @@ -0,0 +1,38 @@ +/* NativeOutOfMemoryError -- failure to allocate with malloc + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure to allocate on the native heap. + */ +public class NativeOutOfMemoryError extends java.lang.Error { + + static final long serialVersionUID = 1826582972785125106L; + + protected NativeOutOfMemoryError() { + super(); + } + + protected NativeOutOfMemoryError(String s) { + super(s); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/OTFException.java b/bindings/java/src/java/com/galois/ppaml/tracer/OTFException.java new file mode 100644 index 0000000..a639c69 --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/OTFException.java @@ -0,0 +1,34 @@ +/* OTFException -- signals an OTF-related failure + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure related to the Open Trace Format API. + */ +public class OTFException extends java.lang.RuntimeException { + + static final long serialVersionUID = 29573934735841980L; + + protected OTFException(String s) { + super(s); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/OTFManagerException.java b/bindings/java/src/java/com/galois/ppaml/tracer/OTFManagerException.java new file mode 100644 index 0000000..b41d528 --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/OTFManagerException.java @@ -0,0 +1,34 @@ +/* OTFManagerException -- signals a failure related to the OTF manager + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure related to the Open Trace Format file manager. + */ +public class OTFManagerException extends OTFException { + + static final long serialVersionUID = 9158227932426782179L; + + protected OTFManagerException(String s) { + super(s); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/OTFManagerInitializationException.java b/bindings/java/src/java/com/galois/ppaml/tracer/OTFManagerInitializationException.java new file mode 100644 index 0000000..e4f61a0 --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/OTFManagerInitializationException.java @@ -0,0 +1,34 @@ +/* OTFManagerInitializationException -- failure to start the OTF manager + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure to initialize the Open Trace Format file manager. + */ +public class OTFManagerInitializationException extends OTFManagerException { + + static final long serialVersionUID = 8357422459731580151L; + + protected OTFManagerInitializationException() { + super("could not initialize Open Trace Format file manager"); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterCloseException.java b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterCloseException.java new file mode 100644 index 0000000..6b08d7d --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterCloseException.java @@ -0,0 +1,34 @@ +/* OTFWriterCloseException -- failure to close the OTF writer + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure to close the Open Trace Format writer. + */ +public class OTFWriterCloseException extends OTFWriterException { + + static final long serialVersionUID = -3744439236064694516L; + + protected OTFWriterCloseException() { + super("could not close Open Trace Format writer"); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterEntryException.java b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterEntryException.java new file mode 100644 index 0000000..e330941 --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterEntryException.java @@ -0,0 +1,34 @@ +/* OTFWriterEntryException -- failure to record phase entry + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure to record {@link Phase} entry. + */ +public class OTFWriterEntryException extends OTFWriterException { + + static final long serialVersionUID = -3863070199086068755L; + + protected OTFWriterEntryException() { + super("could not record phase start"); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterException.java b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterException.java new file mode 100644 index 0000000..f1d0e3c --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterException.java @@ -0,0 +1,34 @@ +/* OTFWriterException -- failure related to the OTF writer + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure related to the Open Trace Format writer. + */ +public class OTFWriterException extends OTFException { + + static final long serialVersionUID = -8501407892120456005L; + + protected OTFWriterException(String s) { + super(s); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterExitException.java b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterExitException.java new file mode 100644 index 0000000..502e4bf --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterExitException.java @@ -0,0 +1,34 @@ +/* OTFWriterExitException -- failure to record phase exit + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure to record {@link Phase} entry. + */ +public class OTFWriterExitException extends OTFWriterException { + + static final long serialVersionUID = 2672929667606300155L; + + protected OTFWriterExitException() { + super("could not record phase end"); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterInitializationException.java b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterInitializationException.java new file mode 100644 index 0000000..315ceb2 --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterInitializationException.java @@ -0,0 +1,34 @@ +/* OTFWriterInitializationException -- failure to start the OTF writer + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure to initialize the Open Trace Format writer. + */ +public class OTFWriterInitializationException extends OTFWriterException { + + static final long serialVersionUID = -160590670499907090L; + + protected OTFWriterInitializationException() { + super("could not open Open Trace Format writer"); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterPhaseDefinitionException.java b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterPhaseDefinitionException.java new file mode 100644 index 0000000..225b32b --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterPhaseDefinitionException.java @@ -0,0 +1,34 @@ +/* OTFWriterPhaseDefinitionException -- failure to define an OTF phase + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure to define a {@link Phase}. + */ +public class OTFWriterPhaseDefinitionException extends OTFWriterException { + + static final long serialVersionUID = -5221693771344940262L; + + protected OTFWriterPhaseDefinitionException() { + super("could not define phase"); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterProcessDefinitionException.java b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterProcessDefinitionException.java new file mode 100644 index 0000000..dc95859 --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterProcessDefinitionException.java @@ -0,0 +1,34 @@ +/* OTFWriterProcessDefinitionException -- failure to define an OTF process + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure to define an Open Trace Format process (thread). + */ +public class OTFWriterProcessDefinitionException extends OTFWriterException { + + static final long serialVersionUID = -2403392867513685061L; + + protected OTFWriterProcessDefinitionException(String processName) { + super("could not define Open Trace Format Process " + processName); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterResolutionException.java b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterResolutionException.java new file mode 100644 index 0000000..bccacc1 --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterResolutionException.java @@ -0,0 +1,34 @@ +/* OTFWriterResolutionException -- failure to set the trace resolution + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure to set the time resolution of a {@link Tracer}. + */ +public class OTFWriterResolutionException extends OTFWriterException { + + static final long serialVersionUID = 7655059683403795873L; + + protected OTFWriterResolutionException() { + super("could not set trace resolution"); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/Phase.java b/bindings/java/src/java/com/galois/ppaml/tracer/Phase.java new file mode 100644 index 0000000..23ed2f4 --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/Phase.java @@ -0,0 +1,220 @@ +/* Phase -- wrapped ppaml_phase_t + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * A phase of execution to trace. This class exports no public constructors; + * to instantiate it, use <code>Tracer.createPhase</code>. + */ +public final class Phase extends CWrapper { + + /** + * The <code>Tracer</code> this phase is associated with. + */ + private final Tracer tracer; + + /** + * The name of the phase. + */ + private final String name; + + /** + * Creates and initializes a <code>Phase</code>. You should not call this; + * call {@link Tracer.createPhase} instead. + * + * @param tracer the {@link Tracer} to associate the <code>Phase</code> + * with. + * + * @param name the name of the phase. + */ + protected Phase(Tracer tracer, final String name) { + this.tracer = tracer; + this.name = name; + super.open(); + } + + + ////////////////////////// Low-level life cycle ////////////////////////// + + ///// JNI shared library ///// + + static { + System.loadLibrary("ppamltracer_java"); + } + + /** + * Wraps <code>malloc</code> to allocate a <code>ppaml_phase_t</code>. + * + * @return Same as <code>malloc</code>. + */ + private static native long mallocPhase(); + + /** + * Wraps <code>ppaml_phase_init</code>. + * + * @return -1 if converting <code>name</code> from a <code>String</code> to + * a <code>char *</code> failed; all other return codes are the same as + * <code>ppaml_phase_init</code>. + */ + private static native int ppaml_phase_init( + long tracer, + long phase, + final String reportNameBase); + + /** + * Wraps <code>ppaml_phase_done</code>. + * + * @return Same as <code>ppaml_phase_done</code>. + */ + private static native int ppaml_phase_done(long phase); + + /** + * Wraps <code>free</code>. + */ + private static native void freePhase(long phase); + + + ///// JNI adapter code ///// + + @Override + protected void allocateCPointer() { + this.cPointer = mallocPhase(); + } + + /** + * Installs data into the structure to make it ready for use. + * + * <p> <b>Precondition:</b> Initialization succeeded. + * + * @throws OutOfMemoryError converting <code>name</code> from a + * <code>String</code> to a <code>char *</code> failed. + * + * @throws OTFWriterPhaseDefinitionException defining the OTF phase failed. + */ + @Override + protected void initializeCPointer() { + assert this.cPointer != 0; + assert tracer != null; + assert name != null; + final int r = ppaml_phase_init(tracer.cPointer, this.cPointer, name); + switch (r) { + case 0: + break; + case -1: + throw new java.lang.OutOfMemoryError( + "failed to convert Java string to C string"); + case 1: + throw new OTFWriterPhaseDefinitionException(); + default: + throw new UnexpectedReturnValueError(r); + } + } + + @Override + protected void finalizeCPointer() { + assert this.cPointer != 0; + final int r = ppaml_phase_done(this.cPointer); + if (r != 0) { + throw new UnexpectedReturnValueError(r); + } + } + + @Override + protected void freeCPointer() { + assert this.cPointer != 0; + freePhase(this.cPointer); + } + + + ////////////////////////// Starting and stopping ////////////////////////// + + ///// JNI shared library ///// + + /** + * Wraps <code>ppaml_phase_start</code>. + * + * @return Same as <code>ppaml_phase_start</code>. + */ + private static native int ppaml_phase_start(long phase); + + /** + * Wraps <code>ppaml_phase_stop</code>. + * + * @return Same as <code>ppaml_phase_stop</code>. + */ + private static native int ppaml_phase_stop(long phase); + + + ///// JNI adapter code ///// + + /** + * Records the start of a <code>Phase</code>. + * + * @throws ClosedException the <code>Phase</code> has been closed. + * + * @throws ClockAcquisitionException getting the time failed. + * + * @throws OTFWriterEntryException recording the phase start failed. + */ + public void start() { + if (this.cPointer == 0) { + throw new ClosedException(); + } + final int r = ppaml_phase_start(this.cPointer); + switch (r) { + case 0: + break; + case 1: + throw new ClockAcquisitionException(); + case 2: + throw new OTFWriterEntryException(); + default: + throw new UnexpectedReturnValueError(r); + } + } + + /** + * Records the end of a <code>Phase</code>. + * + * @throws ClosedException the <code>Phase</code> has been closed. + * + * @throws ClockAcquisitionException getting the time failed. + * + * @throws OTFWriterExitException recording the phase stop failed. + */ + public void stop() { + if (this.cPointer == 0) { + throw new ClosedException(); + } + final int r = ppaml_phase_stop(this.cPointer); + switch (r) { + case 0: + break; + case 1: + throw new ClockAcquisitionException(); + case 2: + throw new OTFWriterExitException(); + default: + throw new UnexpectedReturnValueError(r); + } + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/TimingException.java b/bindings/java/src/java/com/galois/ppaml/tracer/TimingException.java new file mode 100644 index 0000000..da1afad --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/TimingException.java @@ -0,0 +1,34 @@ +/* TimingException -- signals a timing failure + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals a failure related to timing. + */ +public class TimingException extends java.lang.RuntimeException { + + static final long serialVersionUID = -1441057354704045107L; + + protected TimingException(String s) { + super(s); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/Tracer.java b/bindings/java/src/java/com/galois/ppaml/tracer/Tracer.java new file mode 100644 index 0000000..fe0a180 --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/Tracer.java @@ -0,0 +1,163 @@ +/* Tracer -- wrapped ppaml_tracer_t + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * State class for ppamltracer. + * + * <p> ppamltracer is fundamentally a set of stateful operations; a + * <code>Tracer</code> object holds the state ppamltracer needs to operate + * properly. + */ +public final class Tracer extends CWrapper { + + /** + * Base file path for trace report output. + */ + private final String reportNameBase; + + /** + * Creates and initializes a <code>Tracer</code>. The trace report will be + * stored in Open Trace Format. + * + * @param reportNameBase all trace file paths will begin with this path. + */ + public Tracer(final String reportNameBase) { + this.reportNameBase = reportNameBase; + super.open(); + } + + /** + * Creates and initializes a {@link Phase} associated with this + * <code>Tracer</code>. + * + * @param name the name of the phase. + */ + public Phase createPhase(final String name) { + return new Phase(this, name); + } + + + ////////////////////////// Low-level life cycle ////////////////////////// + + ///// JNI shared library ///// + + static { + System.loadLibrary("ppamltracer_java"); + } + + /** + * Wraps <code>malloc</code> to allocate a <code>ppaml_tracer_t</code>. + * + * @return Same as <code>malloc</code>. + */ + private static native long mallocTracer(); + + /** + * Wraps <code>ppaml_tracer_init</code>. + * + * @return -1 if converting <code>reportNameBase</code> from a + * <code>String</code> to a <code>char *</code> failed; all other return + * codes are the same as <code>ppaml_tracer_init</code>. + */ + private static native int ppaml_tracer_init( + long tracer, + final String reportNameBase); + + /** + * Wraps <code>ppaml_tracer_done</code>. + * + * @return Same as <code>ppaml_tracer_done</code>. + */ + private static native int ppaml_tracer_done(long tracer); + + /** + * Wraps <code>free</code>. + */ + private static native void freeTracer(long tracer); + + + ///// JNI adapter code ///// + + @Override + protected void allocateCPointer() { + this.cPointer = mallocTracer(); + } + + /** + * Installs data into the structure to make it ready for use. + * + * <p> <b>Precondition:</b> Initialization succeeded. + * + * @throws OutOfMemoryError converting <code>reportNameBase</code> from a + * <code>String</code> to a <code>char *</code> failed. + * + * @throws OTFManagerInitializationException the Open Trace Format file + * manager could not be initialized. + * + * @throws OTFWriterInitializationException the Open Trace Format writer + * could not be initialized. + * + * @throws OTFWriterResolutionException setting the trace resolution failed. + * + * @throws OTFWriterProcessDefinitionException defining the main OTF process + * failed. + */ + @Override + protected void initializeCPointer() { + assert this.cPointer != 0; + assert reportNameBase != null; + final int r = ppaml_tracer_init(this.cPointer, reportNameBase); + switch (r) { + case 0: + break; + case -1: + throw new java.lang.OutOfMemoryError( + "failed to convert Java string to C string"); + case 1: + throw new OTFManagerInitializationException(); + case 2: + throw new OTFWriterInitializationException(); + case 3: + throw new OTFWriterResolutionException(); + case 4: + throw new OTFWriterProcessDefinitionException("main"); + default: + throw new UnexpectedReturnValueError(r); + } + } + + @Override + protected void finalizeCPointer() { + assert this.cPointer != 0; + final int r = ppaml_tracer_done(this.cPointer); + if (r != 0) { + throw new UnexpectedReturnValueError(r); + } + } + + @Override + protected void freeCPointer() { + assert this.cPointer != 0; + freeTracer(this.cPointer); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/UnexpectedReturnValueError.java b/bindings/java/src/java/com/galois/ppaml/tracer/UnexpectedReturnValueError.java new file mode 100644 index 0000000..e536073 --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/UnexpectedReturnValueError.java @@ -0,0 +1,37 @@ +/* UnexpectedReturnValueError -- unexpected return value from C API + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +package com.galois.ppaml.tracer; + +/** + * Signals an unexpected return value from libppamltracer. If this error is + * thrown, it indicates a bug in ppamltracer, and you should report it to the + * developers. + */ +public class UnexpectedReturnValueError extends java.lang.Error { + + static final long serialVersionUID = -2476858873119724922L; + + protected UnexpectedReturnValueError(int r) { + super("unexpected return value " + r + "\n" + + "This is a bug in ppamltracer! Report it to the maintainers."); + } + +} diff --git a/bindings/java/src/java/com/galois/ppaml/tracer/package-info.java b/bindings/java/src/java/com/galois/ppaml/tracer/package-info.java new file mode 100644 index 0000000..f922274 --- /dev/null +++ b/bindings/java/src/java/com/galois/ppaml/tracer/package-info.java @@ -0,0 +1,80 @@ +/* package-info.java -- package information + * Copyright (C) 2014 Galois, Inc. + * + * This library is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) + * any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this library. If not, see <http://www.gnu.org/licenses/>. + * + * To contact Galois, complete the Web form at + * <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +/** + * A lightweight, portable tracing library for instrumenting generated code. + * + * <p> ppamltracer is a lightweight, portable tracing library designed for + * explicit instrumention of generated code. If you're writing a compiler and + * need hard data on your optimizer's efficacy, ppamltracer is the library for + * you. This Java package provides bindings to the libppamltracer C API. + * + * <p> This package's usage can be summed up in a few lines: + * + * <pre> + * // Create report. + * Tracer tracer = new Tracer("/tmp/my_report"); + * + * // Register phase 1 and do stuff. + * Phase phase = tracer.createPhase("phase 1"); + * phase.start(); + * doStuff(); + * phase.stop(); + * phase.close(); + * + * // Register phase 2 and do different stuff. + * phase = tracer.createPhase("phase 2"); + * // Other stuff + * phase.start(); + * doOtherStuff(); + * phase.stop(); + * // Yet more stuff + * phase.start(); + * doYetMoreStuff(); + * phase.stop(); + * + * // Clean up. + * phase.close(); + * tracer.close(); + * </pre> + * + * <p> This creates a report with the total runtime of <code>doStuff</code> + * recorded as "phase 1" and the total runtime of <code>doOtherStuff</code> and + * <code>doYetMoreStuff</code> combined as "phase 2". + * + * <p> <code>com.galois.ppaml.tracer.examples.Simple</code>, included in the + * distribution, contains a more lengthy example. + * + * <p> ppamltracer writes trace logs in the + * <a href="http://tu-dresden.de/zih/otf/">Open Trace Format</a>, a free and + * open standard developed by the Zentrum für Informationsdienste und + * Hochleistungsrechnen (Center for Information Services and High-Performance + * Computing) at the Technical University of Dresden. + * + * <p> We developed ppamltracer as part of DARPA's + * <a href="http://darpa.mil/Our_Work/I2O/Programs/Probabilistic_Programming_for_Advanced_Machine_Learning_(PPAML).aspx">Probabilistic + * Programming for Advancing Machine Learning</a> (PPAML) project. + * + * @author Galois, Inc. + * + * @version 0.1.0 + */ + +package com.galois.ppaml.tracer; |