Module: ppl/ppl Branch: master Commit: 3ba2322b9b323b0c25dfb9004bfb67bc89e21fd4 URL: http://www.cs.unipr.it/git/gitweb.cgi?p=ppl/ppl.git;a=commit;h=3ba2322b9b323...
Author: Enea Zaffanella zaffanella@cs.unipr.it Date: Mon May 4 13:51:56 2009 +0200
Documented recent changes in the Java interface.
---
NEWS | 7 ++ interfaces/Java/README.java | 30 ++++++++-- .../Parma_Polyhedra_Library.java | 62 ++++++++++++++------ 3 files changed, 76 insertions(+), 23 deletions(-)
diff --git a/NEWS b/NEWS index cc6ecb8..90125e6 100644 --- a/NEWS +++ b/NEWS @@ -17,6 +17,13 @@ o When the PPL has been configured with procedure checks that the FPU can indeed be controlled and fails if that is not the case.
+o The Java interface has to be explicitly initialized before use by + calling static method Parma_Polyhedra_Library.initialize_library(). + Initialization makes more explicit the exact point where PPL + floating point rounding mode is set; it also allows for the caching + of Java classes and field/method IDs, thereby reducing the overhead + of native method callbacks. +
Deprecated and removed methods ------------------------------ diff --git a/interfaces/Java/README.java b/interfaces/Java/README.java index 9e2848c..e5ef557 100644 --- a/interfaces/Java/README.java +++ b/interfaces/Java/README.java @@ -17,10 +17,30 @@ by issuing a command like:
$ java -classpath .:<PPL prefix>/<libdir>/ppl/ppl_java.jar My_Test
-Note that the source code in My_Test.java should take care of loading -the PPL interface library, by calling `System.load' and passing the -full path of the dynamic shared object. For instance, on a Linux machine -and assuming <PPL prefix>=/usr/local/, the call will be something like: +Note that the source code in My_Test.java should take care of:
- System.load("/usr/local/lib/ppl/libppl_java.so"); +a) Load the PPL interface library, by calling `System.load' and + passing the full path of the dynamic shared object. For instance, + on a Linux machine and assuming <PPL prefix>=/usr/local/, the call + will be something like:
+ System.load("/usr/local/lib/ppl/libppl_java.so"); + +b) Make sure that only the intended version(s) of the library has been + loaded, e.g., by calling static method + + Parma_Polyhedra_Library.version(); + +c) Starting from PPL version 0.11, before calling any other method from + other PPL package classes, initialize the Java interface by calling + the static method + + Parma_Polyhedra_Library.initialize_library(); + + When done using the library, finalize it by calling the static method + + Parma_Polyhedra_Library.finalize_library(); + + After finalization no other method of the library may be used (except + for those in class Parma_Polyhedra_Library), unless the library + is re-initialized by calling initialize_library(). diff --git a/interfaces/Java/parma_polyhedra_library/Parma_Polyhedra_Library.java b/interfaces/Java/parma_polyhedra_library/Parma_Polyhedra_Library.java index 1a2b891..f12be27 100644 --- a/interfaces/Java/parma_polyhedra_library/Parma_Polyhedra_Library.java +++ b/interfaces/Java/parma_polyhedra_library/Parma_Polyhedra_Library.java @@ -45,6 +45,33 @@ site: http://www.cs.unipr.it/ppl/ . */ Here is a list of notes with general information and advice on the use of the Java interface.
+ - When the Parma Polyhedra Library is configured, it will automatically + test for the existence of the Java system (unless configuration options + are passed to disable the build of the Java interface; + see configuration option <code>--enable-interfaces</code>). + If Java is correctly installed in a standard location, things will be + arranged so that the Java interface is built and installed + (see configuration option <code>--with-java</code> if you need to + specify a non-standard location for the Java system). + + - The Java interface files are all installed in the directory + \c prefix/lib/ppl. Since this includes shared and + dynamically loaded libraries, you must make your dynamic + linker/loader aware of this fact. If you use a GNU/Linux system, + try the commands <CODE>man ld.so</CODE> and <CODE>man ldconfig</CODE> + for more information. + + - Any application using the PPL should: + - Load the PPL interface library by calling <code>System.load</code> + and passing the full path of the dynamic shared object; + - Make sure that only the intended version(s) of the library has + been loaded, e.g., by calling static method <code>version()</code> + in class \c parma_polyhedra_library.Parma_Polyhedra_Library; + - Starting from version 0.11, initialize the interface by calling + static method <code>initialize_library()</code>; + when all library work is done, finalize the interface by calling + <code>finalize_library()</code>. + - The numerical abstract domains available to the Java user as Java classes consist of the <EM>simple</EM> domains, <EM>powersets</EM> of a simple domain and <EM>products</EM> @@ -77,14 +104,10 @@ site: http://www.cs.unipr.it/ppl/ . */ - In the following, any of the above numerical abstract domains is called a PPL <EM>domain</EM> and any element of a PPL domain is called a <EM>PPL object</EM>. - - The Java interface files are all installed in the directory - \c prefix/lib/ppl. Since this includes shared and - dynamically loaded libraries, you must make your dynamic - linker/loader aware of this fact. If you use a GNU/Linux system, - try the commands <CODE>man ld.so</CODE> and <CODE>man ldconfig</CODE> - for more information. + - A Java program can create a new object for a PPL domain by using the constructors for the class corresponding to the domain. + - For a PPL object with space dimension \p k, the identifiers used for the PPL variables must lie between 0 and \f$k-1\f$ and correspond to the indices of the @@ -96,22 +119,13 @@ site: http://www.cs.unipr.it/ppl/ . */ should follow all the (space) dimension-compatibility rules stated in Section \extref{representation, Representations of Convex Polyhedra} of the main PPL user manual. + - As explained above, a polyhedron has a fixed topology C or NNC, that is determined at the time of its initialization. All subsequent operations on the polyhedron must respect all the topological compatibility rules stated in Section \extref{representation, Representations of Convex Polyhedra} of the main PPL user manual. - - Any application using the PPL should make sure that only the - intended version(s) of the library are ever used. - - When the Parma Polyhedra Library is configured, it will automatically - test for the existence of the Java system (unless configuration options - are passed to disable the build of the Java interface; - see configuration option <code>--enable-interfaces</code>). - If Java is correctly installed in a standard location, things will be - arranged so that the Java interface is built and installed - (see configuration option <code>--with-java</code> if you need to - specify a non-standard location for the Java system).
*/ /* \mainpage */
@@ -130,10 +144,22 @@ public class Parma_Polyhedra_Library { //! \name Library initialization and finalization //@{
- //! Initializes the library. + /*! \brief + Initializes the Parma Polyhedra Library. + + This method must be called after loading the library and + before calling any other method from any other PPL package class. + */ public static native void initialize_library();
- //! Finalizes the library. + /*! \brief + Finalizes the Parma Polyhedra Library. + + This method must be called when work with the library is done. + After finalization, no other library method can be called + (except those in class Parma_Polyhedra_Library), unless the library + is re-initialized by calling <code>initialize_library()</code>. + */ public static native void finalize_library();
//@} // Library initialization and finalization