jxs

Java binding for libxs -- the Crossroads IO library.

What is this?

This package contains two Java bindings for libxs, the Crossroads IO library:

A deprecated binding based on JNA. This was the first implementation in this package, but its performance was unacceptable.
A supported binding based on JNI. The performance for this binding is similar (but lower) to the performance for the native libxs.

How to Use

You will need the following:

A copy of the JDK. The binding has been tested on v1.6.0_30 running on a Windows 7 machine.
A copy of ant. I use v1.8.4.
When using JNI (the supported option), a C compiler. I use MSVC 2010.
When using JNI (the supported option), a copy of cpptasks, an ant helper that automates compilation of C code. I use v1.0b5.

You can run at with ant -lib lib/ant/cpptasks-1.0b5.jar jar to use the included cpptasks
Look at the build.<OS>.properties file for your OS. Pay particular attention to the value of: dir.jni.headers

Once your environment is set up and you have downloaded jxs, you can do any of these:

ant jar -- create all JARs.
ant test -- run all unit tests (none for now).
ant run -- run a specific class in one of the JARs.
ant perf -- run performance tests.

Debugging the build

It can be helpful to run the build using ant -v to debug compiltion issues.

ant -v -lib lib/ant/cpptasks-1.0b5.jar jar

To run a basic tester class:

ant -Dcn=io.crossroads.jni.Tester run

You may need to specify the path to the libxs.(dll,dylib,so).

MacOSX: DYLD_LIBRARY_PATH=../libxs/lib ant -Dcn=io.crossroads.jni.Tester run
Unix: LD_LIBRARY_PATH=../libxs/lib ant -Dcn=io.crossroads.jni.Tester run

ant -Dcn=io.crossroads.jni.local_lat -Dargs="tcp://127.0.0.1:5556 1 100000" perf ant -Dcn=io.crossroads.jni.remote_lat -Dargs="tcp://127.0.0.1:5556 1 100000" perf

Similarly, for the throughput test:

ant -Dcn=io.crossroads.jni.local_thr -Dargs="tcp://127.0.0.1:5556 1 100000" perf ant -Dcn=io.crossroads.jni.remote_thr -Dargs="tcp://127.0.0.1:5556 1 100000" perf

Finally, for the inproc-based latency and throughput tests (these do not require two command prompts):

ant -Dcn=io.crossroads.jni.inproc_lat -Dargs="1 100000" perf

ant -Dcn=io.crossroads.jni.inproc_thr -Dargs="1 100000" perf

Status

The XS library is about 90% supported now. Still missing are:

Support for setting context options (xs_setctxopt()).
Support for setting / getting socket options (xs_setsockopt(), xs_getsockopt()).
Support for plugins (don't know yet if this will ever be added).

License

This project is released under the LGPL license, as is the native libxs library. See LICENSE for more details as well as the Crossroads I/O Licensing page.