Implement the bridge to call Tatoo from java. Very slow at the moment.

[tatoo.git] / src / bindings / java / HACKING

diff --git a/src/bindings/java/HACKING b/src/bindings/java/HACKING
new file mode 100644 (file)
index 0000000..618f29c
--- /dev/null
+++ b/src/bindings/java/HACKING
@@ -0,0 +1,74 @@
+* Memory Management
+
+Both GC need to live in harmony:
+
+- OCaml values that are stored on the Java side must but registered on
+  the OCaml side with caml_register_generational_global_root(),
+  otherwise, they can be reclaimed when they become unreachable from
+  OCaml. If these are still reachable from Java, the java reference is
+  now dangling.
+
+- Java Objects that are stored on the OCaml side must be registered
+  with jni::env().NewGlobalRef() for the same reason (if the become
+  unreachable from Java, their reference becomes dangling in the OCaml
+  code).
+
+- When Java code is done with an OCaml value,
+  it should call caml_unregister_generational_global_root()
+
+- When OCaml code is done with a Java value, it should call
+  env().DeleteGlobalRef()
+
+Registering global references is costly (in both cases) so we avoid
+doing that for every node. We must do it on the Java side:
+- for the automaton
+- for the tree (i.e. an OCaml value holding a pointer to the root of
+  the document
+And on the OCaml side:
+
+- for the pointer to the Document node (root) held in an OCaml block.
+  When the latter is reclamed we delete the GlobalRef associated to
+  the pointer.
+
+- for every MutableNodeList as well as the original NodeList, since
+  they hold pointers to the document. In particular, MutableNodeList
+  are created purely on the OCaml side and only returned as a final
+  result.
+
+
+**** TODO: At the end of the evaluation of the automaton, no OCaml code
+runs anymore, so the OCaml GC does not get a chance to run. One way to
+ensure that OCaml's GC runs one last time, is to call Gc.{minor,
+major, full_major}, either explicitely or when the automaton is
+reclaimed by Java.
+
+* Signals
+
+The JVM uses straps signals (e.g. to raise exceptions instead of
+segfaulting etc.).  However the OCaml runtime also installs a signal
+handler and sometime gets signal targetted at the JVM. The solution to that
+is 'Signal chaining'
+
+http://docs.oracle.com/javase/7/docs/technotes/guides/vm/signal-chaining.html
+
+**** TODO: link against -ljsig instead of relying on LD_PRELOAD
+
+
+* Exceptions
+
+Java exceptions are never checked for in the JNI code.
+
+**** TODO:
+We should perform:
+  if  (env().ExceptionCheck()) { ... }
+in the JNI code. However doing so for every call to Java might kill performances
+
+
+* Makefile
+The makefile is buggy and sometimes need to be run twice
+**** TODO: fix
+
+* Stack Size
+The OCaml code is heavily recursive. It might cause stack overflows of the JVM stack,
+and if signal are not handled properly, a segfault instead of an exception. In case of
+segfault, first increase the stack size with -Xss100m or so.
\ No newline at end of file