From b69ec3f6d953e67422dd32b72688cba850fd1b2e Mon Sep 17 00:00:00 2001 From: Benjamin Barenblat Date: Mon, 13 Jan 2014 15:56:57 -0800 Subject: Initial commit --- .../src/java/com/galois/ppaml/tracer/CWrapper.java | 184 +++++++++++++++++ .../ppaml/tracer/ClockAcquisitionException.java | 35 ++++ .../ppaml/tracer/NativeOutOfMemoryError.java | 38 ++++ .../java/com/galois/ppaml/tracer/OTFException.java | 34 ++++ .../galois/ppaml/tracer/OTFManagerException.java | 34 ++++ .../tracer/OTFManagerInitializationException.java | 34 ++++ .../ppaml/tracer/OTFWriterCloseException.java | 34 ++++ .../ppaml/tracer/OTFWriterEntryException.java | 34 ++++ .../galois/ppaml/tracer/OTFWriterException.java | 34 ++++ .../ppaml/tracer/OTFWriterExitException.java | 34 ++++ .../tracer/OTFWriterInitializationException.java | 34 ++++ .../tracer/OTFWriterPhaseDefinitionException.java | 34 ++++ .../OTFWriterProcessDefinitionException.java | 34 ++++ .../ppaml/tracer/OTFWriterResolutionException.java | 34 ++++ .../src/java/com/galois/ppaml/tracer/Phase.java | 220 +++++++++++++++++++++ .../com/galois/ppaml/tracer/TimingException.java | 34 ++++ .../src/java/com/galois/ppaml/tracer/Tracer.java | 163 +++++++++++++++ .../ppaml/tracer/UnexpectedReturnValueError.java | 37 ++++ .../java/com/galois/ppaml/tracer/package-info.java | 80 ++++++++ 19 files changed, 1165 insertions(+) create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/CWrapper.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/ClockAcquisitionException.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/NativeOutOfMemoryError.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/OTFException.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/OTFManagerException.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/OTFManagerInitializationException.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterCloseException.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterEntryException.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterException.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterExitException.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterInitializationException.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterPhaseDefinitionException.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterProcessDefinitionException.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/OTFWriterResolutionException.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/Phase.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/TimingException.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/Tracer.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/UnexpectedReturnValueError.java create mode 100644 bindings/java/src/java/com/galois/ppaml/tracer/package-info.java (limited to 'bindings/java/src/java/com/galois') 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 . + * + * 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 class which wraps a C structure and associated functions. + * + *

This class is intended to work hand-in-hand with Java Native Interface + * code that follows a four-stage lifecycle: + * + *

+ *
Allocation
The system reserves memory and resources needed by + * the structure.
+ *
Initialization
The system installs data into the structure to + * make it ready for use.
+ *
Finalization
The system cleans up the data structure under the + * assumption that it will not be used anymore.
+ *
Freeing
The system releases memory and resources needed by the + * structure.
+ *
+ * + * 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: + * + *
+ *
Open
The system allocates and initializes the underlying + * structure.
+ *
Close
The system finalizes and frees the underlying + * structure.
+ *
+ * + *

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. + * + *

Precondition: cPointer is 0. + * + *

Postcondition: If allocation was successful, + * cPointer is not 0. + */ + abstract protected void allocateCPointer(); + + /** + * Installs data into the structure to make it ready for use. + * + *

Precondition: Allocation succeeded. + */ + abstract protected void initializeCPointer(); + + /** + * Cleans up the structure under the assumption that it will not be used + * anymore. + * + *

Precondition: Initialization succeeded. + */ + abstract protected void finalizeCPointer(); + + /** + * Releases memory and resources needed by the structure. + * + *

Precondition: cPointer is not 0.
+ * Precondition: Finalization succeeded. + * + *

Postcondition: cPointer is 0. + */ + 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 CWrapper.OpenedException 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 CWrapper.ClosedException 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 . + * + * 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; + +/** + * 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 . + * + * 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; + +/** + * 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 . + * + * 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; + +/** + * 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 . + * + * 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; + +/** + * 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 . + * + * 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; + +/** + * 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 . + * + * 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; + +/** + * 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 . + * + * 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; + +/** + * 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 . + * + * 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; + +/** + * 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 . + * + * 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; + +/** + * 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 . + * + * 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; + +/** + * 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 . + * + * 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; + +/** + * 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 . + * + * 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; + +/** + * 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 . + * + * 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; + +/** + * 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 . + * + * 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); + } + } + +} 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 . + * + * 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; + +/** + * 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 . + * + * 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; + +/** + * State class for ppamltracer. + * + *

ppamltracer is fundamentally a set of stateful operations; a + * Tracer 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 Tracer. 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 + * Tracer. + * + * @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 malloc to allocate a ppaml_tracer_t. + * + * @return Same as malloc. + */ + private static native long mallocTracer(); + + /** + * Wraps ppaml_tracer_init. + * + * @return -1 if converting reportNameBase from a + * String to a char * failed; all other return + * codes are the same as ppaml_tracer_init. + */ + private static native int ppaml_tracer_init( + long tracer, + final String reportNameBase); + + /** + * Wraps ppaml_tracer_done. + * + * @return Same as ppaml_tracer_done. + */ + private static native int ppaml_tracer_done(long tracer); + + /** + * Wraps free. + */ + 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. + * + *

Precondition: Initialization succeeded. + * + * @throws OutOfMemoryError converting reportNameBase from a + * String to a char * 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 . + * + * 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; + +/** + * 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 . + * + * To contact Galois, complete the Web form at + * or write to Galois, Inc., 421 Southwest + * 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */ + +/** + * A lightweight, portable tracing library for instrumenting 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. This Java package provides bindings to the libppamltracer C API. + * + *

This package's usage can be summed up in a few lines: + * + * 

+ *   // 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();
+ *
+ * + *

This creates a report with the total runtime of doStuff + * recorded as "phase 1" and the total runtime of doOtherStuff and + * doYetMoreStuff combined as "phase 2". + * + *

com.galois.ppaml.tracer.examples.Simple, included in the + * distribution, contains a more lengthy example. + * + *

ppamltracer writes trace logs in the + * 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 + * Probabilistic + * Programming for Advancing Machine Learning (PPAML) project. + * + * @author Galois, Inc. + * + * @version 0.1.0 + */ + +package com.galois.ppaml.tracer; -- cgit v1.2.3