Initial commit

46 files changed, 3365 insertions, 0 deletions

diff --git a/bindings/haskell/.gitignore b/bindings/haskell/.gitignore
new file mode 100644
index 0000000..805d057
--- /dev/null
+++ b/bindings/haskell/.gitignore
@@ -0,0 +1,7 @@
+# .gitignore for ppamltracer-haskell                               -*- conf -*-
+
+*.hi
+*.o
+dist*/
+
+examples/simple
diff --git a/bindings/haskell/README b/bindings/haskell/README
new file mode 100644
index 0000000..3d9cf39
--- /dev/null
+++ b/bindings/haskell/README
@@ -0,0 +1,8 @@
+			  ppamltracer-haskell, v0.1.0
+
+This package contains Haskell bindings to ppamltracer.  They require GHC 7.6 or
+later.
+
+This package uses the Cabal build system; normal Cabal build procedure applies.
+
+For examples of use, see the examples directory.
diff --git a/bindings/haskell/Setup.hs b/bindings/haskell/Setup.hs
new file mode 100644
index 0000000..fa38bd0
--- /dev/null
+++ b/bindings/haskell/Setup.hs
@@ -0,0 +1,22 @@
+{- Setup -- Cabal setup 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. -}
+
+import Distribution.Simple
+
+main = defaultMain
diff --git a/bindings/haskell/examples/simple.hs b/bindings/haskell/examples/simple.hs
new file mode 100644
index 0000000..478f25b
--- /dev/null
+++ b/bindings/haskell/examples/simple.hs
@@ -0,0 +1,46 @@
+{- simple.hs -- basic ppamltracer example
+This file is in the public domain.
+
+Compile this with
+    ghc --make simple.hs
+-}
+
+{-# LANGUAGE LambdaCase #-}
+module Main where
+
+import Control.Applicative ((<$>), (<*>))
+import Control.Monad (liftM)
+
+import PPAML.Tracer
+
+main :: IO ()
+main = do
+  -- Start ppamltracer.
+  withTracer "/tmp/simple_report" $ \tracer -> do
+    -- Register the factorial phase.
+    withPhase tracer "fact" $ \phase -> do
+      -- Print factorials.
+      putStr "Factorials:"
+      mapM_ (putStr . (' ':) . show) =<< mapM (fact phase) [0 .. 40]
+      putStrLn ""
+    -- Register the Fibonacci phase.
+    withPhase tracer "fib" $ \phase -> do
+      -- Print Fibonacci numbers.
+      putStr "Fibonacci numbers:"
+      mapM_ (putStr . (' ':) . show) =<< mapM (fib phase) [0 .. 25]
+      putStrLn ""
+
+{- Records that we're running inside the provided phase and computes a
+factorial. -}
+fact :: PhaseHandle -> Integer -> IO Integer
+fact phase = withPhaseRunning phase . \case
+               0 -> return 1
+               n -> liftM (n*) $ fact phase (n - 1)
+
+{- Records that we're running inside the provided phase and computes a Fibonacci
+number. -}
+fib :: PhaseHandle -> Integer -> IO Integer
+fib phase = withPhaseRunning phase . \case
+              0 -> return 0
+              1 -> return 1
+              n -> (+) <$> fib phase (n - 1) <*> fib phase (n - 2)
diff --git a/bindings/haskell/ppamltracer.cabal b/bindings/haskell/ppamltracer.cabal
new file mode 100644
index 0000000..5b6918e
--- /dev/null
+++ b/bindings/haskell/ppamltracer.cabal
@@ -0,0 +1,62 @@
+-- ppamltracer.cabal -- Cabal 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.
+
+cabal-version:       >=1.10
+name:                ppamltracer
+version:             0.1.0
+synopsis:            A lightweight tracing library
+description: ppamltracer is a lightweight 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
+ package uses Haskell’s foreign function interface to wrap the C libppamltracer
+ API.
+ .
+ ppamltracer writes trace logs in the
+ <http://tu-dresden.de/zih/otf/ Open Trace Format>, 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.
+ .
+ We developed ppamltracer as part of DARPA’s
+ <http://darpa.mil/Our_Work/I2O/Programs/Probabilistic_Programming_for_Advanced_Machine_Learning_(PPAML%29.aspx Probabilistic Programming for Advancing Machine Learning>
+ (PPAML) project.
+copyright:           © 2014 Galois, Inc.
+license:             GPL-3
+author:              Benjamin Barenblat
+maintainer:          bbarenblat@galois.com
+category:            Language
+build-type:          Simple
+extra-source-files:  examples/simple.hs
+tested-with:         GHC==7.6.3
+
+library
+  hs-source-dirs:      src
+  default-language:    Haskell2010
+  other-extensions:    DeriveDataTypeable
+                     , EmptyDataDecls
+                     , ExistentialQuantification
+                     , TemplateHaskell
+  build-depends:       base
+                     , deepseq >=1.2.0.0 && <2
+                     , hierarchical-exceptions <2
+  extra-libraries:     ppamltracer
+  exposed-modules:     PPAML.Tracer
+  other-modules:       PPAML.Tracer.Exception
+  ghc-options:         -Wall -O2
diff --git a/bindings/haskell/src/PPAML/Tracer.hs b/bindings/haskell/src/PPAML/Tracer.hs
new file mode 100644
index 0000000..ddff15c
--- /dev/null
+++ b/bindings/haskell/src/PPAML/Tracer.hs
@@ -0,0 +1,268 @@
+{- PPAML.Tracer -- PPAML timing instrumentation system (Haskell bindings)
+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. -}
+
+{-| Getting started with ppamltracer is easy.  Because of Haskell’s intrinsic
+laziness, though, getting meaningful results out of ppamltracer is slightly more
+difficult.  For instance, consider the following (correctly written) example:
+
+> import PPAML.Tracer
+>
+> main =
+>   withTracer "/tmp/my_report" $ \tracer ->
+>     withPhase tracer "phase 1" $ \phase ->
+>       withPhaseRunning phase doStuff
+>     withPhase tracer "phase 2" $ \phase -> do
+>       withPhaseRunning phase doOtherStuff
+>       withPhaseRunning phase doYetMoreStuff
+
+This creates a report which appears to record the total runtime of 'doStuff'
+recorded as \"phase 1\" and the total runtime of 'doOtherStuff' and
+'doYetMoreStuff' combined as \"phase 2\".  In actuality, however, the report
+does not record the total runtime – instead,
+
+> withPhaseRunning phase f
+
+records the time required to evaluate 'f'’s result to normal form.  Thus, 'f'
+can leverage infinite data as intermediate values; only 'f'’s final result need
+be finite. -}
+
+{-# LANGUAGE EmptyDataDecls #-}
+{-# LANGUAGE LambdaCase #-}
+module PPAML.Tracer
+       ( -- * Tracers
+         Tracer, TracerHandle
+       , withTracer
+         -- * Phases
+       , Phase, PhaseHandle
+       , withPhase
+         -- * Timing
+       , withPhaseRunning, withPhaseRunning_
+         -- * Exceptions
+         {-| ppamltracer defines a fairly detailed exception hierarchy; however,
+         all exceptions are truly exceptional cases, and they likely will not
+         occur in normal use.  For reference, the hierarchy looks like this:
+
+         @
+'Control.Exception.SomeException'
+└─ 'TracerException'
+   ├─ 'OTFException'
+   │  ├─ 'OTFManagerException'
+   │  │  └─ 'OTFManagerInitializationFailure'
+   │  └─ 'OTFWriterException'
+   │     ├─ 'OTFWriterInitializationFailure'
+   │     ├─ 'OTFPhaseDefinitionFailure'
+   │     ├─ 'OTFPhaseEntryFailure'
+   │     ├─ 'OTFPhaseExitFailure'
+   │     ├─ 'OTFWriterCloseFailure'
+   │     ├─ 'OTFTraceResolutionFailure'
+   │     └─ 'OTFProcessDefinitionFailure'
+   └─ 'TimingException'
+      └─ 'ClockAcquisitionFailure'
+         @ -}
+       , TracerException
+         -- ** Open Trace Format exceptions
+       , OTFException
+       , OTFManagerException, OTFManagerInitializationFailure
+       , OTFWriterException, OTFWriterInitializationFailure,
+         OTFPhaseDefinitionFailure, OTFPhaseEntryFailure, OTFPhaseExitFailure,
+         OTFWriterCloseFailure, OTFTraceResolutionFailure,
+         OTFProcessDefinitionFailure
+         -- ** Timing exceptions
+       , TimingException, ClockAcquisitionFailure
+       ) where
+
+import Control.DeepSeq (NFData, ($!!))
+import Control.Exception (bracket_, throw)
+import Foreign (Storable, Ptr, allocaBytes, peek)
+import Foreign.C (CInt(CInt), CSize(CSize), CString, withCString)
+import System.IO.Unsafe (unsafeDupablePerformIO)
+
+import PPAML.Tracer.Exception
+
+
+-------------------------------- High-level API --------------------------------
+
+{-| Constructs a 'Tracer' and executes the specified computation.  The trace
+report will be stored in Open Trace Format; all trace file paths will begin with
+the specified path.
+
+Throws:
+
+  * 'OTFManagerInitializationFailure' if the Open Trace Format manager could not
+    be initialized.
+
+  * 'OTFWriterInitializationFailure' if the Open Trace Format writer could not
+    be initialized.
+
+  * 'OTFTraceResolutionFailure' if setting the trace resolution failed.
+
+  * 'OTFProcessDefinitionFailure' if defining the main OTF process failed.
+
+  * 'OTFWriterCloseFailure' if the Open Trace Format writer could not be closed
+    after the computation ran. -}
+
+withTracer :: FilePath -> (TracerHandle -> IO a) -> IO a
+withTracer reportBaseName f =
+  allocaBytes tracerSize $ \tracerHandle ->
+    bracket_ (tracerInit tracerHandle reportBaseName)
+             (tracerDone tracerHandle)
+             (f tracerHandle)
+
+{-| Constructs a 'Phase' and executes the specified computation.
+
+Throws 'OTFPhaseDefinitionFailure' if the phase could not be defined. -}
+withPhase :: TracerHandle       -- ^ the associated 'Tracer'
+             -> String          -- ^ the name of the 'Phase'
+             -> (PhaseHandle -> IO a)
+             -> IO a
+withPhase tracer name f =
+  allocaBytes phaseSize $ \phaseHandle ->
+    bracket_ (phaseInit tracer phaseHandle name)
+             (phaseDone phaseHandle)
+             (f phaseHandle)
+
+{-| Executes an IO action and evaluates its result to normal form, recording the
+time required to do so in the provided 'Phase'. -}
+withPhaseRunning :: NFData a => PhaseHandle -> IO a -> IO a
+withPhaseRunning phase f = withPhaseRunning_ phase ((return $!!) =<< f)
+
+{-| Executes an IO action, recording the time required to do so in the provided
+'Phase'.  Unlinke 'withPhaseRunning', this function does /not/ evaluate the
+action’s result.  Use this function when you need finer-grained control over the
+precise degree of evaluation than 'withPhaseRunning' offers.
+-}
+withPhaseRunning_ :: PhaseHandle -> IO a -> IO a
+withPhaseRunning_ phase = bracket_ (phaseStart phase) (phaseStop phase)
+
+
+----------------------------------- Tracers ------------------------------------
+
+----- Data type -----
+
+{-| Tracer state bundle.  ppamltracer is fundamentally a set of stateful
+operations; this data type dsecribes the state ppamltracer needs to operate
+properly.  A one-to-one mapping exists between 'Tracer's and trace reports, so
+you will likely only need one 'Tracer' per program. -}
+data Tracer
+
+foreign import ccall unsafe "ppaml/tracer/internal.h & ppaml_tracer_t_size"
+  ppaml_tracer_t_size :: Ptr CSize
+
+tracerSize :: Int
+tracerSize = fromIntegral $ unsafeReadLibraryConstant ppaml_tracer_t_size
+
+
+----- Initialization and finalization -----
+
+type TracerHandle = Ptr Tracer
+
+foreign import ccall unsafe "ppaml/tracer.h ppaml_tracer_init"
+  ppaml_tracer_init :: TracerHandle -> CString -> IO CInt
+
+tracerInit :: TracerHandle -> FilePath -> IO ()
+tracerInit tracer reportNameBase =
+  withCString reportNameBase $ \cReportNameBase ->
+    ppaml_tracer_init tracer cReportNameBase >>= \case
+      0 -> return ()
+      1 -> throw OTFManagerInitializationFailure
+      2 -> throw OTFWriterInitializationFailure
+      3 -> throw OTFTraceResolutionFailure
+      4 -> throw OTFProcessDefinitionFailure
+      r -> unexpectedReturnCode r
+
+foreign import ccall unsafe "ppaml/tracer.h ppaml_tracer_done"
+  ppaml_tracer_done :: TracerHandle -> IO CInt
+
+tracerDone :: TracerHandle -> IO ()
+tracerDone tracer =
+  ppaml_tracer_done tracer >>= \case 0 -> return ()
+                                     1 -> throw OTFWriterCloseFailure
+                                     r -> unexpectedReturnCode r
+
+
+------------------------------------ Phases ------------------------------------
+
+----- Data type -----
+
+-- | A phase of execution to trace and to gather timing statistics about.
+data Phase
+
+foreign import ccall unsafe "ppaml/tracer/internal.h & ppaml_phase_t_size"
+  ppaml_phase_t_size :: Ptr CSize
+
+phaseSize :: Int
+phaseSize = fromIntegral $ unsafeReadLibraryConstant ppaml_phase_t_size
+
+
+----- Initialization and finalization -----
+
+type PhaseHandle = Ptr Phase
+
+foreign import ccall unsafe "ppaml/tracer.h ppaml_phase_init"
+  ppaml_phase_init :: TracerHandle -> PhaseHandle -> CString -> IO CInt
+
+phaseInit :: TracerHandle -> PhaseHandle -> String -> IO ()
+phaseInit tracer phase name =
+  withCString name $ \cName ->
+    ppaml_phase_init tracer phase cName >>= \case
+      0 -> return ()
+      1 -> throw OTFPhaseDefinitionFailure
+      r -> unexpectedReturnCode r
+
+foreign import ccall unsafe "ppaml/tracer.h ppaml_phase_done"
+  ppaml_phase_done :: PhaseHandle -> IO CInt
+
+phaseDone :: PhaseHandle -> IO ()
+phaseDone phase =
+  ppaml_phase_done phase >>= \case 0 -> return ()
+                                   r -> unexpectedReturnCode r
+
+
+----- Timing -----
+
+foreign import ccall unsafe "ppaml/tracer.h ppaml_phase_start"
+  ppaml_phase_start :: PhaseHandle -> IO CInt
+
+phaseStart :: PhaseHandle -> IO ()
+phaseStart phase =
+  ppaml_phase_start phase >>= \case 0 -> return ()
+                                    1 -> throw ClockAcquisitionFailure
+                                    2 -> throw OTFPhaseEntryFailure
+                                    r -> unexpectedReturnCode r
+
+foreign import ccall unsafe "ppaml/tracer.h ppaml_phase_stop"
+  ppaml_phase_stop :: PhaseHandle -> IO CInt
+
+phaseStop :: PhaseHandle -> IO ()
+phaseStop phase =
+  ppaml_phase_stop phase >>= \case 0 -> return ()
+                                   1 -> throw ClockAcquisitionFailure
+                                   2 -> throw OTFPhaseExitFailure
+                                   r -> unexpectedReturnCode r
+
+
+----------------------------------- Utility ------------------------------------
+
+unsafeReadLibraryConstant :: Storable a => Ptr a -> a
+unsafeReadLibraryConstant = unsafeDupablePerformIO . peek
+
+unexpectedReturnCode :: CInt -> a
+unexpectedReturnCode code =
+  error $ "unexpected return code " ++ show code ++ "\n\
+          \This is a bug in ppamltracer!  Report it to the maintainers."
diff --git a/bindings/haskell/src/PPAML/Tracer/Exception.hs b/bindings/haskell/src/PPAML/Tracer/Exception.hs
new file mode 100644
index 0000000..ba77c84
--- /dev/null
+++ b/bindings/haskell/src/PPAML/Tracer/Exception.hs
@@ -0,0 +1,78 @@
+{- PPAML.Tracer.Exception -- exceptions used by ppamltracer
+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. -}
+
+{-# LANGUAGE DeriveDataTypeable #-}
+{-# LANGUAGE ExistentialQuantification #-}
+{-# LANGUAGE TemplateHaskell #-}
+module PPAML.Tracer.Exception where
+
+import Control.Exception (SomeException(SomeException))
+import Control.Exception.Hierarchical (mkAbstractException, mkException)
+
+-- | A generic ppamltracer error.  Extends 'SomeException'.
+mkAbstractException 'SomeException "TracerException"
+
+
+-------------------------------- OTF exceptions --------------------------------
+
+{-| An error related to Open Trace Format input and output.  Extends
+'TracerException'. -}
+mkAbstractException 'TracerException "OTFException"
+
+-- | An error caused by the Open Trace Fromat manager.  Extends 'OTFException'.
+mkAbstractException 'OTFException "OTFManagerException"
+
+{-| Failure to initialize the Open Trace Format manager.  Extends
+'OTFManagerException'. -}
+mkException 'OTFManagerException "OTFManagerInitializationFailure"
+
+-- | An error caused by the Open Trace Format writer.  Extends 'OTFException'.
+mkAbstractException 'OTFException "OTFWriterException"
+
+{-| Failure to initialize the Open Trace Format writer.  Extends
+'OTFWriterException'. -}
+mkException 'OTFWriterException "OTFWriterInitializationFailure"
+
+-- | Failure to define a phase.  Extends 'OTFWriterException'.
+mkException 'OTFWriterException "OTFPhaseDefinitionFailure"
+
+-- | Failure to record entry into a phase.  Extends 'OTFWriterException'.
+mkException 'OTFWriterException "OTFPhaseEntryFailure"
+
+-- | Failure to record exit from a phase.  Extends 'OTFWriterException'.
+mkException 'OTFWriterException "OTFPhaseExitFailure"
+
+{-| Failure to close the Open Trace Format writer.  Extends
+'OTFWriterException'. -}
+mkException 'OTFWriterException "OTFWriterCloseFailure"
+
+-- | Failure to set the tracer resolution.  Extends 'OTFWriterException'.
+mkException 'OTFWriterException "OTFTraceResolutionFailure"
+
+-- | Failure to define a process (i.e., a thread).  Extends 'OTFWriterException'.
+mkException 'OTFWriterException "OTFProcessDefinitionFailure"
+
+
+------------------------------ Timing exceptions -------------------------------
+
+-- | An error related to system timers.  Extends 'TracerException'.
+mkAbstractException 'TracerException "TimingException"
+
+-- | A failure to get the current clock time.  Extends 'TimingException'.
+mkException 'TimingException "ClockAcquisitionFailure"
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;
diff --git a/bindings/python/.gitignore b/bindings/python/.gitignore
new file mode 100644
index 0000000..4ac65cb
--- /dev/null
+++ b/bindings/python/.gitignore
@@ -0,0 +1,8 @@
+# .gitignore for ppamltracer-python                                 -*- conf -*-
+
+# Python
+*.pyc
+
+# distutils
+MANIFEST
+dist/
diff --git a/bindings/python/MANIFEST.in b/bindings/python/MANIFEST.in
new file mode 100644
index 0000000..6ec6c9b
--- /dev/null
+++ b/bindings/python/MANIFEST.in
@@ -0,0 +1,21 @@
+# MANIFEST.in -- manifest template for source distributions
+# Copyright (C) 2013  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.
+
+recursive-include examples *.py
diff --git a/bindings/python/README b/bindings/python/README
new file mode 100644
index 0000000..35a6bbd
--- /dev/null
+++ b/bindings/python/README
@@ -0,0 +1,11 @@
+			  ppamltracer-python, v0.1.0
+
+This package provides Python bindings to ppamltracer.  They require Python 2.7.
+
+This package uses distutils for installation; you can run
+
+    python setup.py install
+
+to install the package.
+
+For examples of use, see the examples directory.
diff --git a/bindings/python/examples/simple.py b/bindings/python/examples/simple.py
new file mode 100755
index 0000000..350c85a
--- /dev/null
+++ b/bindings/python/examples/simple.py
@@ -0,0 +1,49 @@
+#!/usr/bin/env python
+# simple.py -- basic ppamltracer-python example
+# This file is in the public domain.
+
+import os
+import sys
+
+from ppamltracer import Tracer
+
+def main():
+    # Disable buffering on stdout so we can see the numbers as they are printed.
+    sys.stdout = os.fdopen(sys.stdout.fileno(), 'w', 0)
+    # Start ppamltracer.
+    with Tracer("/tmp/simple_report") as tracer:
+        # Register the factorial phase.
+        with tracer.create_phase("fact") as phase:
+            # Print factorials.
+            print "Factorials:",
+            for i in range(21):
+                print fact(phase, i),
+            print
+        # Register the Fibonacci phase.
+        with tracer.create_phase("fib") as phase:
+            # Print Fibonacci numbers.
+            print "Fibonacci numbers: ",
+            for i in range(24):
+                print fib(phase, i),
+            print
+
+def fact(phase, n):
+    # Record that we're running inside the factorial phase.
+    with phase.running():
+        # Compute the factorial.
+        if n == 0:
+            return 1
+        else:
+            return n * fact(phase, n - 1)
+
+def fib(phase, n):
+    # Record that we're running inside the Fibonacci phase.
+    with phase.running():
+        # Compute the nth Fibonacci number.
+        if n == 0 or n == 1:
+            return n
+        else:
+            return fib(phase, n - 1) + fib(phase, n - 2)
+
+if __name__ == '__main__':
+    main()
diff --git a/bindings/python/ppamltracer.py b/bindings/python/ppamltracer.py
new file mode 100644
index 0000000..dde85a3
--- /dev/null
+++ b/bindings/python/ppamltracer.py
@@ -0,0 +1,365 @@
+# ppamltracer -- Python bindings to ppamltracer
+# Copyright (C) 2013  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 tracing library for explicit instrumentation of generated code.
+
+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.  ppamltracer-python provides a high-level Python API on
+top of the libppamltracer C API.
+
+ppamltracer-python's usage can be summed up in a couple lines:
+
+    from ppamltracer import Tracer
+    with Tracer("/tmp/my_report") as tracer:
+        with tracer.create_phase("phase 1") as phase:
+            with phase.running():
+                do_stuff()
+        with tracer.create_phase("phase 2") as phase:
+            with phase.running():
+                do_other_stuff()
+            with phase.running():
+                do_yet_more_stuff()
+
+This creates a report with the total runtime of do_stuff recorded as
+"phase 1", and the total runtime of do_other_stuff and do_yet_more_stuff
+combined as "phase 2".
+
+The ppamltracer-python distribution also contains a more lengthy example
+in the "examples" directory.
+
+ppamltracer writes trace logs in the Open Trace Format [1], a free and
+open standard developed by the Zentrum fuer Informationsdienste und
+Hochleistungsrechnen (Center for Information Services and
+High-Performance Computing) at the Technical University of Dresden.
+
+We developed ppamltracer and ppamltracer-python as part of DARPA's
+Probabilistic Programming for Advancing Machine Learning (PPAML)
+project [2].
+
+References:
+    [1] http://tu-dresden.de/zih/otf/
+    [2] http://darpa.mil/Our_Work/I2O/Programs/Probabilistic_Programming_for_Advanced_Machine_Learning_(PPAML).aspx
+"""
+# TODO: Replace "ue" in "fuer" with Unicode u-with-diaresis (blocking on
+# deployment of fix to Python #1065986, "Fix pydoc crashing on unicode
+# strings").
+
+import ctypes
+import ctypes.util
+import warnings
+
+
+################################ Low-level API ################################
+
+_lib = ctypes.cdll.LoadLibrary(ctypes.util.find_library("ppamltracer"))
+"""ctypes binding to the ppamltracer C library."""
+
+# The code in this section binds the C API using ctypes, translating
+# return codes into the exception hierarchy defined below.  Since these
+# functions are not intended to be used externally, they're not
+# documented using pydoc; see the ppamltracer C API documentation for
+# information on their behavior.
+
+_sizeof_ppaml_tracer_t = \
+    ctypes.c_size_t.in_dll(_lib, "ppaml_tracer_t_size").value
+
+_sizeof_ppaml_phase_t = ctypes.c_size_t.in_dll(_lib, "ppaml_phase_t_size").value
+
+def _ppaml_tracer_init(tracer, report_name_base):
+    result = _lib.ppaml_tracer_init(tracer, report_name_base)
+    if result == 0:
+        return None
+    elif result == 1:
+        raise OTFManagerInitializationError()
+    elif result == 2:
+        raise OTFWriterInitializationError()
+    elif result == 3:
+        raise OTFWriterResolutionError()
+    elif result == 4:
+        raise OTFWriterProcessDefinitionError("main")
+    else:
+        _warn_unexpected_return_code()
+        raise TracerError()
+
+def _ppaml_tracer_done(tracer):
+    result = _lib.ppaml_tracer_done(tracer)
+    if result == 0:
+        return None
+    elif result == 1:
+        raise OTFWriterCloseError()
+    else:
+        _warn_unexpected_return_code()
+        raise TracerError()
+
+def _ppaml_phase_init(tracer, phase, name):
+    result = _lib.ppaml_phase_init(tracer, phase, name)
+    if result == 0:
+        return None
+    elif result == 1:
+        raise OTFWriterPhaseDefinitionError()
+    else:
+        _warn_unexpected_return_code()
+        raise TracerError()
+
+def _ppaml_phase_start(phase):
+    result = _lib.ppaml_phase_start(phase)
+    if result == 0:
+        return None
+    elif result == 1:
+        raise ClockAcquisitionError()
+    elif result == 2:
+        raise OTFWriterEntryError()
+    else:
+        _warn_unexpected_return_code()
+        raise TracerError()
+
+def _ppaml_phase_stop(phase):
+    result = _lib.ppaml_phase_stop(phase)
+    if result == 0:
+        return None
+    elif result == 1:
+        raise ClockAcquisitionError()
+    elif result == 2:
+        raise OTFWriterExitError()
+    else:
+        _warn_unexpected_return_code()
+        raise TracerError()
+
+def _ppaml_phase_done(phase):
+    result = _lib.ppaml_phase_done(phase)
+    if result == 0:
+        return None
+    else:
+        _warn_unexpected_return_code()
+        raise TracerError()
+
+
+############################# Resource-based API ##############################
+
+class Tracer(object):
+    """A tracer for programs, which records execution timing information.
+
+    This class is designed to be used with Python's "with" statement-- e.g.,
+
+        with Tracer("/tmp/my_report") as tracer:
+            main(tracer)
+
+    """
+
+    def __init__(self, report_name_base):
+        """Create a new tracer.
+
+        The tracer will create an Open Trace Format report during program
+        execution.  The multiple files of the report will all start with the
+        specified base name.
+
+        """
+        self._report_name_base = report_name_base
+        self._underlying = None
+
+    def __enter__(self):
+        if self._underlying is None:
+            self._underlying = \
+                ctypes.create_string_buffer(_sizeof_ppaml_tracer_t)
+            _ppaml_tracer_init(self._underlying, self._report_name_base)
+        return self
+
+    def __exit__(self, *exception_info):
+        if self._underlying is not None:
+            _ppaml_tracer_done(self._underlying)
+            self._underlying = None
+
+    def create_phase(self, name):
+        """Construct a Phase associated with this Tracer.
+
+        This function is merely a convenience function; internally, it shells
+        out to the Phase constructor.
+
+        """
+        return Phase(self, name)
+
+
+class Phase(object):
+    """A phase of computation traced by ppamltracer.
+
+    This class is designed to be used with Python's "with" statement-- e.g.,
+
+        with Phase(tracer, "my phase") as phase:
+            with phase.running():
+                do_stuff()
+            with phase.running():
+                do_stuff_again()
+
+    Note the double use of "with".  The outer "with" manages the lifetime of
+    a Phase; the inner "with" actually starts and stops the phase timer.
+
+    """
+
+    def __init__(self, tracer, name):
+        """Define a new phase tracked by a given tracer."""
+        self._tracer = tracer
+        self._name = name
+        self._underlying = None
+
+    def __enter__(self):
+        if self._underlying is None:
+            self._underlying = \
+                ctypes.create_string_buffer(_sizeof_ppaml_phase_t)
+            _ppaml_phase_init(
+                self._tracer._underlying,
+                self._underlying,
+                self._name)
+        return self
+
+    def __exit__(self, *exception_info):
+        if self._underlying is not None:
+            _ppaml_phase_done(self._underlying)
+            self._underlying = None
+
+    def _start(self):
+        _ppaml_phase_start(self._underlying)
+
+    def _stop(self):
+        _ppaml_phase_stop(self._underlying)
+
+    def running(self):
+        """ Create a resource manager for the phase timer.
+
+        This manager handles starting and stopping the phase, allowing you to
+        time operations by saying, e.g.,
+
+            with phase.running():
+                do_stuff()
+
+        """
+        return _PhaseTimerManager(self)
+
+
+class _PhaseTimerManager(object):
+    """Manage entry and exit from a Phase using the "with" statement."""
+
+    def __init__(self, phase):
+        self._phase = phase
+
+    def __enter__(self):
+        self._phase._start()
+
+    def __exit__(self, *exception_info):
+        self._phase._stop()
+
+
+############################# Exception hierarchy #############################
+
+class TracerError(Exception):
+    """A generic ppamltracer error."""
+    pass
+
+class OTFError(TracerError):
+    """An error related to Open Trace Format input and output."""
+    pass
+
+class OTFManagerError(OTFError):
+    """An error caused by the Open Trace Format manager."""
+    pass
+
+class OTFManagerInitializationError(OTFManagerError):
+    """Failure to initialize the Open Trace Format manager."""
+
+    def __init__(self):
+        super.__init__(
+            self,
+            "could not initialize Open Trace Format file manager")
+
+class OTFWriterError(OTFError):
+    """An error caused by the Open Trace Format writer."""
+    pass
+
+class OTFWriterInitializationError(OTFWriterError):
+    """Failure to initialize the Open Trace Format writer."""
+
+    def __init__(self):
+        super.__init__(self, "could not open Open Trace Format writer")
+
+class OTFWriterPhaseDefinitionError(OTFWriterError):
+    """Failure to define a phase. """
+
+    def __init__(self):
+        super.__init__(self, "could not define phase")
+
+class OTFWriterEntryError(OTFWriterError):
+    """Failure to record entry into a phase."""
+
+    def __init__(self):
+        super.__init__(self, "could not record phase start")
+
+class OTFWriterExitError(OTFWriterError):
+    """Failure to record exit from a phase."""
+
+    def __init__(self):
+        super.__init__(self, "could not record phase end")
+
+class OTFWriterCloseError(OTFWriterError):
+    """Failure to close the Open Trace Format writer."""
+
+    def __init__(self):
+        super.__init__(self, "could not close Open Trace Format writer")
+
+class OTFWriterResolutionError(OTFWriterError):
+    """Failure to set the tracer resolution."""
+
+    def __init__(self):
+        super.__init__(self, "could not set trace resolution")
+
+class OTFWriterProcessDefinitionError(OTFWriterError):
+    """Failure to define an Open Trace Format process."""
+
+    def __init__(self, process_name=None):
+        if process_name is None:
+            super.__init__(self, "could not define Open Trace Format process")
+        else:
+            super.__init__(self,
+                           ("could not define Open Trace Format process \""
+                            + process_name
+                            + "\""))
+
+class TimingError(TracerError):
+    """An error related to system timers."""
+    pass
+
+class ClockAcquisitionError(TimingError):
+    """A failure to get the current clock time."""
+
+    def __init__(self):
+        super.__init__(self, "could not get current time")
+
+
+############################### Warnings ###############################
+
+class UnwrappedCErrorWarning(Warning):
+    """A warning indicating a failure to correctly wrap a C API."""
+    pass
+
+def _warn_unexpected_return_code():
+    warnings.warn(("Unexpected C return code\n"
+                   + "*** This is a bug in ppamltracer-python!  Report it to the maintainers."),
+                  UnwrappedCErrorWarning,
+                  2)
diff --git a/bindings/python/setup.py b/bindings/python/setup.py
new file mode 100755
index 0000000..d8e9ec2
--- /dev/null
+++ b/bindings/python/setup.py
@@ -0,0 +1,34 @@
+#!/usr/bin/env python
+# setup.py -- distutils setup script for ppamltracer-python
+# Copyright (C) 2013  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.
+
+from distutils.core import setup
+
+setup(name="ppamltracer-python",
+      version="0.1.0",
+      description="ppamltracer Python bindings",
+      author="Benjamin Barenblat",
+      author_email="bbarenblat@galois.com",
+      classifiers=["Development Status :: 4 - Beta",
+                   "Intended Audience :: Developers",
+                   "License :: OSI Approved :: GNU General Public License (GPL)",
+                   "Topic :: Software Development :: Compilers"],
+      license="GPL",
+      py_modules=['ppamltracer'])
diff --git a/bindings/racket/.gitignore b/bindings/racket/.gitignore
new file mode 100644
index 0000000..9f3ac02
--- /dev/null
+++ b/bindings/racket/.gitignore
@@ -0,0 +1,16 @@
+# .gitignore for ppamltracer-racket                                 -*- conf -*-
+
+# Bytecode
+compiled/
+*.dep
+*.zo
+
+# Scribble
+manual/
+*.html
+*.tex
+*.pdf
+racket.css
+scribble.css
+scribble-style.css
+scribble-common.js
diff --git a/bindings/racket/README b/bindings/racket/README
new file mode 100644
index 0000000..b6c9d06
--- /dev/null
+++ b/bindings/racket/README
@@ -0,0 +1,11 @@
+			  ppamltracer-racket, v0.1.0
+
+This package contains Racket bindings to ppamltracer.  It requires Racket v5.2
+or later.
+
+Currently, this package is designed to be used as a collection; to install it,
+you should type `raco link --name ppamltracer .'.  (You may uninstall it with
+`raco link --remove ppamltracer'.)
+
+To build the documentation, which contains a detailed example of use, you
+should run `scribble ++xref-in setup/xref load-collections-xref manual.scrbl'.
diff --git a/bindings/racket/main.rkt b/bindings/racket/main.rkt
new file mode 100644
index 0000000..e4db143
--- /dev/null
+++ b/bindings/racket/main.rkt
@@ -0,0 +1,396 @@
+#lang racket/base
+#| ppamltracer -- Racket bindings to ppamltracer
+Copyright (C) 2013, 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. |#
+
+(require (for-syntax racket/base
+                     racket/syntax
+                     (only-in racket/list drop-right)
+                     (only-in racket/string string-join)
+                     (only-in srfi/13 string-tokenize)
+                     (only-in srfi/14 char-set char-set-complement)
+                     srfi/26; hole notation
+                     ))
+
+(require (rename-in ffi/unsafe [-> ~>])
+         ffi/unsafe/define)
+(require racket/contract)
+
+#| A shorthand for 'let-syntax-rule' with only one macro.  For example,
+
+    (let-syntax-rule (take-fst x y) x
+      (take-fst 'foo 'bar))
+
+expands to
+
+    'foo
+|#
+(define-syntax-rule (let-syntax-rule (name . args) template body)
+  (let-syntax ([name (syntax-rules () [(_ . args) template])])
+    body))
+
+;; Convenience macro to instantiate an exception at the current location.
+(define-syntax-rule (fail exception args ...)
+  (apply exception (list args ... (current-continuation-marks))))
+
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Low-level interface ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+;; Load the library.
+(define-ffi-definer define-ppamltracer (ffi-lib "libppamltracer"))
+
+#| We're going to model ppaml_tracer_t and ppaml_phase_t as abstract types by
+having Racket treat them as buffers.  These two symbols define how long those
+buffers need to be.  Ideally, they should be of type 'size_t', but Racket
+doesn't have a size_t builtin, so we just use the largest C unsigned integer
+type. |#
+(define-ppamltracer ppaml_tracer_t_size _uint64)
+(define-ppamltracer ppaml_phase_t_size _uint64)
+
+#| Define the struct types we're working with as buffer types.  Instead of
+mucking around with initializers and finalizers, which we can't seem to get
+working correctly, we simply export an API which enforces proper resource
+cleanup. |#
+(define (make-buffer size) (make-ctype (_bytes o size) #f #f))
+(define _ppaml_tracer_t (make-buffer ppaml_tracer_t_size))
+(define _ppaml_phase_t (make-buffer ppaml_phase_t_size))
+
+#| To help avoid passing structs of the wrong type in API internals, we'll
+manipulate the structs as tagged pointers. |#
+(define _tracer (_cpointer 'ppaml_tracer_t))
+(define _phase (_cpointer 'ppaml_phase_t))
+
+;; Allocation functions for _tracer and _phase.
+(define (malloc-tagged-pointer size-or-type tag)
+  (let ([result (malloc size-or-type 'atomic)])
+    (cpointer-push-tag! result tag)
+    result))
+(define (malloc-_tracer)
+  (malloc-tagged-pointer _ppaml_tracer_t 'ppaml_tracer_t))
+(define (malloc-_phase)
+  (malloc-tagged-pointer _ppaml_phase_t 'ppaml_phase_t))
+
+;; Import library functions.
+(define-ppamltracer ppaml_tracer_init (_fun _tracer _path ~> _int))
+(define-ppamltracer ppaml_tracer_done (_fun _tracer ~> _int))
+(define-ppamltracer ppaml_phase_init (_fun _tracer _phase _string ~> _int))
+(define-ppamltracer ppaml_phase_done (_fun _phase ~> _int))
+(define-ppamltracer ppaml_phase_start (_fun _phase ~> _int))
+(define-ppamltracer ppaml_phase_stop (_fun _phase ~> _int))
+
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Error handling ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+#| Convenience macro to create an exception.  For example,
+
+    (define-exception exn:fail:whatever)
+
+expands to
+
+    (struct exn:fail:whatever exn:fail ()
+            #:extra-constructor-name make-exn:fail:whatever
+            #:transparent)
+
+You can also call 'define-exception' with a message.  Then, instead of creating
+an extra binary make-prefixed constructor, 'define-exception' will create an
+extra /unary/ make-prefixed constructor.  All instances of the exception will
+then have the same message.  For example,
+
+    (define-exception exn:fail:whatever "whatever happened!")
+
+expands to
+
+    (struct exn:fail:whatever exn:fail ()
+            #:transparent)
+    (define (make-exn:fail:whatever continuation-mark-set)
+      (exn:fail:whatever "whatever happened!" continuation-mark-set))
+|#
+(define-syntax (define-exception stx)
+  (let ([#| Lifts a function which operates on data to operate on syntax
+         instead. |#
+         map-as-datum
+         (lambda (f stx) (datum->syntax stx (f (syntax->datum stx))))]
+        [#| Given an exception name (as a symbol), produces the conventional
+         super-exception.  For instance,
+
+             (take-base-exn 'exn:fail:whatever)
+
+         expands to
+
+             'exn:fail
+         |#
+         take-base-exn
+         (compose1 string->symbol
+                   (cut string-join <> ":")
+                   (cut drop-right <> 1)
+                   (cut string-tokenize <> (char-set-complement
+                                            (char-set #\:)))
+                   symbol->string)])
+    (syntax-case stx ()
+      [(_ name)
+       (with-syntax ([base-name (map-as-datum take-base-exn #'name)]
+                     [make-name (format-id stx "make-~a" #'name
+                                           #:source #'name)])
+         #'(struct name base-name ()
+                   #:extra-constructor-name make-name
+                   #:transparent))]
+      [(_ name message)
+       (with-syntax ([base-name (map-as-datum take-base-exn #'name)]
+                     [make-name (format-id stx "make-~a" #'name
+                                           #:source #'name)])
+         #'(begin
+             (struct name base-name () #:transparent)
+             (define (make-name continuation-mark-set)
+               (name message continuation-mark-set))))])))
+
+#| Like define-exception, but does not create an extra make-prefixed
+constructor at all. |#
+(define-syntax (define-exception* stx)
+  (let ([map-as-datum
+         (lambda (f stx) (datum->syntax stx (f (syntax->datum stx))))]
+        [take-base-exn
+         (compose1 string->symbol
+                   (cut string-join <> ":")
+                   (cut drop-right <> 1)
+                   (cut string-tokenize <> (char-set-complement
+                                            (char-set #\:)))
+                   symbol->string)])
+    (syntax-case stx ()
+      [(_ name)
+       (with-syntax ([base-name (map-as-datum take-base-exn #'name)])
+         #'(struct name base-name () #:transparent))])))
+
+;;;;; Exception hierarchy ;;;;;
+
+(define-exception exn:fail:ppamltracer)
+
+(define-exception exn:fail:ppamltracer:otf)
+
+(define-exception exn:fail:ppamltracer:otf:manager)
+
+(define-exception exn:fail:ppamltracer:otf:manager:initialization
+  "could not initialize Open Trace Format file manager")
+
+(define-exception exn:fail:ppamltracer:otf:writer)
+
+(define-exception exn:fail:ppamltracer:otf:writer:initialization
+  "could not open Open Trace Format writer")
+
+(define-exception exn:fail:ppamltracer:otf:writer:phase-definition
+  "could not define phase")
+
+(define-exception exn:fail:ppamltracer:otf:writer:entry
+  "could not record phase start")
+
+(define-exception exn:fail:ppamltracer:otf:writer:exit
+  "could not record phase end")
+
+(define-exception exn:fail:ppamltracer:otf:writer:close
+  "could not close Open Trace Format writer")
+
+(define-exception exn:fail:ppamltracer:otf:writer:resolution
+  "could not set trace resolution")
+
+(define-exception* exn:fail:ppamltracer:otf:writer:process-definition)
+(define (make-exn:fail:ppamltracer:otf:writer:process-definition
+         process-name
+         continuation-mark-set)
+  (exn:fail:ppamltracer:otf:writer:process-definition
+   (format "could not define Open Trace Format process ~v" process-name)
+   continuation-mark-set))
+
+(define-exception exn:fail:ppamltracer:timing)
+
+(define-exception exn:fail:ppamltracer:timing:clock-acquisition
+  "could not get current time")
+
+
+;;;;; Error-checked versions of library functions ;;;;;
+
+#| This macro makes checking C return codes trivial.  Invocation is analogous
+to that for the 'cond' form:
+
+    (define some-function
+      (checked some-c-function
+               [0 'ok]
+               [1 (exn make-exn:fail:ppamltracer "bad data format")]
+               [-1 'ok]))
+
+This defines 'some-function' as a function taking an arbitrary number of
+arguments.  'some-function', when invoked, will pass all its arguments to
+'some-c-function'.  If 'some-c-function' returns 0 or -1, then some-function
+will evaluate successfully to whatever 'some-c-function' returned; if
+'some-c-function' returns 1, though, 'some-function' will raise an
+'exn:fail:ppamltracer' exception with the specified error message.
+
+If 'some-c-function' returns an unexpected value, 'some-function' will raise an
+'exn:fail' noting the actual return value and declaring it a bug. |#
+(define-syntax-rule (checked proc [expected consequence] ...)
+  (let-syntax-rule (cond-rhs result consequence-or-exception)
+      (if (eq? consequence-or-exception 'ok)
+          result
+          (raise consequence-or-exception))
+    (lambda args
+      (let ([result (apply proc args)])
+        (case result
+            [(expected) (cond-rhs result consequence)]
+            ...
+            [else (error (quote proc)
+                         "unexpected return value ~v\n\
+This is a bug in ppamltracer!  Report it to the maintainers."
+                         result)])))))
+
+(define ((as-void proc) . args)
+  (void (apply proc args)))
+
+(define ppaml-tracer-init
+  (as-void
+   (checked ppaml_tracer_init
+            [0 'ok]
+            [1 (fail make-exn:fail:ppamltracer:otf:manager:initialization)]
+            [2 (fail make-exn:fail:ppamltracer:otf:writer:initialization)]
+            [3 (fail make-exn:fail:ppamltracer:otf:writer:resolution)]
+            [4 (fail make-exn:fail:ppamltracer:otf:writer:process-definition
+                     "main")])))
+
+(define ppaml-tracer-done
+  (as-void
+   (checked ppaml_tracer_done
+            [0 'ok]
+            [1 (fail make-exn:fail:ppamltracer:otf:writer:close)])))
+
+(define ppaml-phase-init
+
+  (as-void
+   (checked ppaml_phase_init
+            [0 'ok]
+            [1 (fail make-exn:fail:ppamltracer:otf:writer:phase-definition)])))
+
+(define ppaml-phase-start
+  (as-void
+   (checked ppaml_phase_start
+            [0 'ok]
+            [1 (fail make-exn:fail:ppamltracer:timing:clock-acquisition)]
+            [2 (fail make-exn:fail:ppamltracer:otf:writer:entry)])))
+
+(define ppaml-phase-stop
+  (as-void
+   (checked ppaml_phase_stop
+            [0 'ok]
+            [1 (fail make-exn:fail:ppamltracer:timing:clock-acquisition)]
+            [2 (fail make-exn:fail:ppamltracer:otf:writer:exit)])))
+
+(define ppaml-phase-done
+  (as-void
+   (checked ppaml_phase_done
+            [0 'ok])))
+
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; High-level API ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+#| The functions in this section comprise a relatively safe API for this
+library--i.e., using them will help avoid resource leaks.  Of course, Racket
+gives you plenty of rope to hang yourself--you could, for instance, call/cc
+your way back into the middle of some traced function. |#
+
+;; Predicates on '_tracer' and '_phase', to emulate declaration as structs.
+(define (cpointer-with-tag? obj tag)
+  (and (cpointer? obj)
+       (cpointer-has-tag? obj tag)))
+(define (tracer? obj) (cpointer-with-tag? obj 'ppaml_tracer_t))
+(define (phase? obj) (cpointer-with-tag? obj 'ppaml_phase_t))
+
+#| Execute a procedure in an exception-safe environment such that its resources
+are properly released upon exit.  With the exception handling stripped away,
+
+    (managed-execution resource initialize initialize-args proc finalize)
+
+evaluates to
+
+    (begin (apply initialize (cons resource initialize-args))
+           (proc resource)
+           (finalize resource))
+|#
+(define (managed-execution resource initialize initialize-args proc finalize)
+  (apply initialize (cons resource initialize-args))
+  (let ([result
+         (with-handlers
+             ([exn? (lambda (exn)
+                      #| An exception occurred during the execution of 'proc'.
+                      Clean up and re-throw. |#
+                      (with-handlers
+                          ([exn? (lambda (exn)
+                                   #| An exception occurred during cleanup!
+                                   We're already responding to an existing
+                                   exception, though, so just ignore it. |#
+                                   (void))])
+                        (finalize resource))
+                      (raise exn))])
+           (proc resource))])
+    (finalize resource)
+    result))
+
+(define (call-with-tracer report-name-base proc)
+  (managed-execution (malloc-_tracer)
+                     ppaml-tracer-init
+                     (list report-name-base)
+                     proc
+                     ppaml-tracer-done))
+
+(define (call-with-phase tracer phase-name proc)
+  (managed-execution (malloc-_phase)
+                     (lambda (phase tracer name)
+                       ;; Reorder arguments to fit C API.
+                       (ppaml-phase-init tracer phase name))
+                     (list tracer phase-name)
+                     proc
+                     ppaml-phase-done))
+
+(define (call-with-phase-running phase proc)
+  (managed-execution phase
+                     ppaml-phase-start
+                     '()
+                     (lambda (ignored) (proc))
+                     ppaml-phase-stop))
+
+
+;;;;; Macro versions ;;;;;
+
+(define-syntax-rule (let/tracer [tracer report-name-base] body ...)
+  (call-with-tracer report-name-base (lambda (tracer) body ...)))
+
+(define-syntax-rule (let/phase tracer [phase phase-name] body ...)
+  (call-with-phase tracer phase-name (lambda (phase) body ...)))
+
+(define-syntax-rule (with-phase-running phase body ...)
+  (call-with-phase-running phase (lambda () body ...)))
+
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Module interface ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(provide
+ (contract-out [tracer? (-> any/c boolean?)]
+               [phase? (-> any/c boolean?)]
+               [call-with-tracer (parametric->/c [A]
+                                   (-> path-string? (-> tracer? A) A))]
+               [call-with-phase (parametric->/c [A]
+                                  (-> tracer? string? (-> phase? A) A))]
+               [call-with-phase-running (parametric->/c [A]
+                                          (-> phase? (-> A) A))])
+ let/tracer
+ let/phase
+ with-phase-running)
diff --git a/bindings/racket/manual.scrbl b/bindings/racket/manual.scrbl
new file mode 100644
index 0000000..f27731b
--- /dev/null
+++ b/bindings/racket/manual.scrbl
@@ -0,0 +1,181 @@
+#lang scribble/manual
+@;{ manual.scrbl -- Scribble documentation for ppamltracer-racket
+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. }
+
+@(require (for-label racket/base
+                     racket/sequence))
+@(require (for-label ppamltracer))
+
+@title{ppamltracer}
+
+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 Racket library provides a high-level API on top of the libppamltracer C API.
+
+ppamltracer's usage can be summed up in a couple lines:
+
+@racketblock[
+(require ppamltracer)
+(let/tracer [tracer "/tmp/my_report"]
+  (let/phase tracer [phase "phase 1"]
+    (with-phase-running phase
+      (do-stuff)))
+  (let/phase tracer [phase "phase 2"]
+    (with-phase-running phase
+      (do-other-stuff))
+    (with-phase-running phase
+      (do-yet-more-stuff))))
+]
+
+This creates a report with the total runtime of @racket[do-stuff] recorded as "phase 1" and the total runtime of @racket[do-other-stuff] and @racket[do-yet-more-stuff] combined as "phase 2".
+
+@secref{getting-started} contains a more lengthy example.
+
+ppamltracer writes trace logs in the @hyperlink["http://tu-dresden.de/zih/otf/"]{Open Trace Format}, 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.
+
+We developed ppamltracer as part of DARPA's @hyperlink["http://darpa.mil/Our_Work/I2O/Programs/Probabilistic_Programming_for_Advanced_Machine_Learning_(PPAML).aspx"]{Probabilistic Programming for Advancing Machine Learning} (PPAML) project.
+
+
+@section[#:tag "getting-started"]{Getting Started}
+
+This basic example demonstrates using ppamltracer to trace two functions -- a factorial function and a Fibonacci number generator.
+
+@#reader scribble/comment-reader (racketblock
+;; simple.rkt -- basic ppamltracer example
+;; This file is in the public domain.
+
+(require racket/sequence)
+(require ppamltracer)
+
+(define (fact phase n)
+  ;; Record that we're running inside the factorial phase.
+  (with-phase-running phase
+    ;; Compute the factorial.
+    (if (= n 0)
+        1
+        (* n (fact phase (- n 1))))))
+
+(define (fib phase n)
+  ;; Record that we're running inside the Fibonacci phase.
+  (with-phase-running phase
+    ;; Compute the nth Fibonacci number.
+    (case n
+      [(0 1) n]
+      [else (+ (fib phase (- n 1)) (fib phase (- n 2)))])))
+
+;; Start ppamltracer.
+(let/tracer [tracer "/tmp/simple_report"]
+  ;; Register the factorial phase.
+  (let/phase tracer [phase "fact"]
+    ;; Print factorials.
+    (printf "Factorials: ")
+    (sequence-for-each (lambda (n) (printf "~a " (fact phase n)))
+                       (in-range 40))
+    (printf "\n"))
+  ;; Register the Fibonacci phase.
+  (let/phase tracer [phase "fib"]
+    ;; Print Fibonacci numbers.
+    (printf "Fibonacci numbers: ")
+    (sequence-for-each (lambda (n) (printf "~a " (fib phase n)))
+                       (in-range 16))
+    (printf "\n")))
+)
+
+@section{API in Depth}
+
+@defmodule[ppamltracer]
+
+@subsection{Tracers}
+
+ppamltracer is fundamentally a set of stateful operations; the @racket[tracer] data type holds the state ppamltracer needs to operate properly.
+
+@defproc[(tracer? [obj any/c])
+         boolean?]{
+  Evaluates to @racket[#t] if and only if @racket[obj] is a @racket[tracer].
+}
+
+@defproc[(call-with-tracer [report-name-base path-string?]
+                           [proc (-> tracer? A)])
+         A]{
+  Creates a new @racket[tracer].
+  The @racket[tracer] will save trace reports in Open Trace Format; all trace file paths will begin with @racket[report-name-base].
+}
+
+@defform[#:id let/tracer
+         #:literals (tracer)
+         (let/tracer [tracer report-name-base] body ...)
+         #:contracts ([report-name-base path-string?])]{
+  Macro version of @racket[call-with-tracer].
+  Equivalent to
+
+  @racketblock[
+  (call-with-tracer report-name-base (lambda (tracer) body ...))
+  ]
+}
+
+@subsection{Phases}
+
+A @racket[phase] represents a phase of execution about which the user wishes to gather timing statistics.
+
+@defproc[(phase? [obj any/c])
+         boolean?]{
+  Evaluates to @racket[#t] if and only if @racket[obj] is a @racket[phase].
+}
+
+@defproc[(call-with-phase [tracer tracer?]
+                          [phase-name string?]
+                          [proc (-> phase? A)])
+         A]{
+  Creates a new @racket[phase] attached to @racket[tracer] and named @racket[phase-name].
+}
+
+@defform[#:id let/phase
+         #:literals (phase)
+         (let/phase tracer [phase name] body ...)
+         #:contracts ([tracer tracer?]
+                      [name string?])]{
+  Macro version of @racket[call-with-phase].
+  Equivalent to
+
+  @racketblock[
+  (call-with-phase tracer name (lambda (phase) body ...))
+  ]
+}
+
+@subsection{Tracing}
+
+@defproc[(call-with-phase-running [phase phase?]
+                                  [proc (-> A)])
+         A]{
+  Runs @racket[proc], associating information about its timing and execution with @racket[phase] in the trace report.
+  Should @racket[proc] throw an exception, @racket[call-with-phase-running] will stop tracing before propagating the exception up the stack.
+}
+
+@defform[#:id with-phase-running
+         #:literals (phase)
+         (with-phase-running phase body ...)
+         #:contracts ([phase phase?])]{
+  Macro version of @racket[call-with-phase-running].
+  Equivalent to
+
+  @racketblock[
+  (call-with-phase-running phase (lambda () body ...))
+  ]
+}
+