/* 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 . * * To contact Galois, complete the Web form at * 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 Tracer.createPhase. */ public final class Phase extends CWrapper { /** * The Tracer this phase is associated with. */ private final Tracer tracer; /** * The name of the phase. */ private final String name; /** * Creates and initializes a Phase. You should not call this; * call {@link Tracer.createPhase} instead. * * @param tracer the {@link Tracer} to associate the Phase * 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 malloc to allocate a ppaml_phase_t. * * @return Same as malloc. */ private static native long mallocPhase(); /** * Wraps ppaml_phase_init. * * @return -1 if converting name from a String to * a char * failed; all other return codes are the same as * ppaml_phase_init. */ private static native int ppaml_phase_init( long tracer, long phase, final String reportNameBase); /** * Wraps ppaml_phase_done. * * @return Same as ppaml_phase_done. */ private static native int ppaml_phase_done(long phase); /** * Wraps free. */ 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. * *

Precondition: Initialization succeeded. * * @throws OutOfMemoryError converting name from a * String to a char * 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 ppaml_phase_start. * * @return Same as ppaml_phase_start. */ private static native int ppaml_phase_start(long phase); /** * Wraps ppaml_phase_stop. * * @return Same as ppaml_phase_stop. */ private static native int ppaml_phase_stop(long phase); ///// JNI adapter code ///// /** * Records the start of a Phase. * * @throws ClosedException the Phase 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 Phase. * * @throws ClosedException the Phase 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); } } }