diff options
author | Benjamin Barenblat <bbarenblat@galois.com> | 2014-01-13 15:56:57 -0800 |
---|---|---|
committer | Benjamin Barenblat <bbarenblat@galois.com> | 2014-01-13 15:56:57 -0800 |
commit | b69ec3f6d953e67422dd32b72688cba850fd1b2e (patch) | |
tree | a24e664807c19bd3b50f504ce0d33df24f135a23 /bindings/java/src/java/com/galois/ppaml/tracer/CWrapper.java |
Initial commit
Diffstat (limited to 'bindings/java/src/java/com/galois/ppaml/tracer/CWrapper.java')
-rw-r--r-- | bindings/java/src/java/com/galois/ppaml/tracer/CWrapper.java | 184 |
1 files changed, 184 insertions, 0 deletions
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(); + } + +} |