Java binding for GMP

[arnaud nauwynck]

Hi,

First of all, thanks for your amazing library. great job, amazing
performances.

I have looked at a Java library for wrapping GMP native API functions into
java wrapper functions, but I didn't find something over internet.
I have done one myself, and I would like to contribute it back to the GMP
project.

it consists of
  ~ 700 lines of swig code (resembling C header files)
  ~ 1300 lines of java code  (+ generated code)
  ~ 2000 lines of java JUnit test code

Here is my code on github:

https://github.com/Arnaud-Nauwynck/JNI-wrapper-for-GMP-Gnu-Multi-Precision-Library


An example of java API usage is the following:

        import org.gnu.gmp.swig;

        MPZ left = new MPZ(12);         // constructor with java int value
        MPZ right = new MPZ();          // construtor with no value
        right.set_si(34);                      // set int value
        MPZ res = new MPZ();
        res.set_add(left, right);           // compute and set addition
        res.dispose();                        // explicitely dispose
        // ... left.dispose(); right.dispose() ... automatically dispose
from garbage collector



Here are some remarks on my code:
- it works on my PC (linux debian amd64) with a good code coverage (~90%)
by JUnit tests
- it is fast .. fast ...  so much faster than java.math.BigInteger ...
- it took me few evenings to do, but I did not took time to make it
"GNU"-compliant code quality (I would probably not be able to)
- the build system is currently rather minimalist :  I have used maven for
the java compilation part into jar  (simplest possible, and well integrated
with maven repository dependencies management)
- the native build part is done with a Makefile of ~20 ugly lines ... not
multi-platform, it assumes gcc + gmp + java + swig are correctly installed
on your PC
  I have hard-coded dir pathes from my own PC, which must be edited before
compiling it on your own!  I also encountered linking problem on debian,
and googled for a quick fix

to compile it:
  - launch "make"   (for regenerating the .so from the swig interface)
  - use eclipse for compiling the java     or  use "mvn install
-DskipTests=true" for compiling and building the jar without testing

for testing JUnit tests, you need to have libgmp.so and this libgmpjni.so
in your LD_LIBRARY_PATH env var
  for exemple type the following (on unix / cygwin):
   $ export LD_LIBRARY_PATH=`pwd`
   $ mvn test -DskipTests=false
 to launch JUnit tests from eclipse, you must also edit the project JUnit
eclipse launcher environment variable to have the LD_LIBRARY_PATH  (or
start eclipse after having set this var)


- the result naming convention I choosed is a strange mix between GMP c
convention and java convention :
      - I have transformed wherever possible global methods with prefix
mpz_ / mpq_ / mpf_ into instance method of java classes MPZ / MPQ / MPF
      - method starts with set_ or get_ to show that it is setter or getter.
      - the rest of the name is similar to the GMP method

- the library chosen for the java to native code mapping is SWIG  (Simple
Wrapper Interface Generator), but generated code is compiled and based on
java JNI technology.
- there are other alternatives to Swig-JNI, but I didn't have a look at
them.. In particular, it should be compared to other library like "JNA", or
new-style annotation dynamic binding libraries  like javacpp ... see
http://code.google.com/p/javacpp/
In javacpp wiki page, they sites other libraries : SWIG<http://www.swig.org/>,
CableSwig <http://www.itk.org/ITK/resources/CableSwig.html>,
JNIGeneratorApp<http://www.eclipse.org/swt/jnigen.php>,
JNIWrapper <http://www.teamdev.com/jniwrapper/>, Platform
Invoke<http://msdn.microsoft.com/en-us/library/0h9e9t7d.aspx>,
GlueGen <http://jogamp.org/gluegen/www/>,
JNIDirect<http://homepage.mac.com/pcbeard/JNIDirect/>,
JNA <https://github.com/twall/jna>, JNIEasy <http://www.innowhere.com/>,
JniMarshall<http://flinflon.brandonu.ca/Dueck/SystemsProgramming/JniMarshall/>,
JNative <http://jnative.free.fr/>, J/Invoke <http://www.jinvoke.com/>,
HawtJNI <http://hawtjni.fusesource.org/>,
BridJ<http://code.google.com/p/bridj/>,
etc.

- I did not mapped some methods regarding FILE, dump, alloc/init/clear/,
either because they are unpractical  in java (FILE* instead of
InputStream/OutputStream), or unsafe
- I have doubt on the mapping of "unsigned long int" from java to JNI
(using jlong), and I dont know how this might work for negative values
passed from java ... so I simply check them and throw "new
IllegalArgumentException()" if arguments are negative in java.
- I don't check null pointer (disposed native resources) in java... I
assume objects are valid, to avoid performance null check of argument in
every method (I was lazy writing the checks, but performance problem should
be nothing compared to risks of potential jvm crash)


So this it it
Please take this code, do whatever you want on it, and study the
possibility to deliver it as a part of the official java languages binding
for GMP.
If you don't have time, don't like it, or dont wan't, no problem. But if it
is only for minor things you would like me to improve, fill free to ask me.
Of course, you can fork me on github to suggest me some Pull Requests to
apply.

So I write again the url :

https://github.com/Arnaud-Nauwynck/JNI-wrapper-for-GMP-Gnu-Multi-Precision-Library


Thanks in advance,

Regards,

Arnaud Nauwynck