src/bindings/java/HACKING

   1 * Memory Management
   2
   3 Both GC need to live in harmony:
   4
   5 - OCaml values that are stored on the Java side must but registered on
   6   the OCaml side with caml_register_generational_global_root(),
   7   otherwise, they can be reclaimed when they become unreachable from
   8   OCaml. If these are still reachable from Java, the java reference is
   9   now dangling.
  10
  11 - Java Objects that are stored on the OCaml side must be registered
  12   with jni::env().NewGlobalRef() for the same reason (if the become
  13   unreachable from Java, their reference becomes dangling in the OCaml
  14   code).
  15
  16 - When Java code is done with an OCaml value,
  17   it should call caml_unregister_generational_global_root()
  18
  19 - When OCaml code is done with a Java value, it should call
  20   env().DeleteGlobalRef()
  21
  22 Registering global references is costly (in both cases) so we avoid
  23 doing that for every node. We must do it on the Java side:
  24 - for the automaton
  25 - for the tree (i.e. an OCaml value holding a pointer to the root of
  26   the document
  27 And on the OCaml side:
  28
  29 - for the pointer to the Document node (root) held in an OCaml block.
  30   When the latter is reclamed we delete the GlobalRef associated to
  31   the pointer.
  32
  33 - for every MutableNodeList as well as the original NodeList, since
  34   they hold pointers to the document. In particular, MutableNodeList
  35   are created purely on the OCaml side and only returned as a final
  36   result.
  37
  38
  39 **** TODO: At the end of the evaluation of the automaton, no OCaml code
  40 runs anymore, so the OCaml GC does not get a chance to run. One way to
  41 ensure that OCaml's GC runs one last time, is to call Gc.{minor,
  42 major, full_major}, either explicitely or when the automaton is
  43 reclaimed by Java.
  44
  45 * Signals
  46
  47 The JVM uses straps signals (e.g. to raise exceptions instead of
  48 segfaulting etc.).  However the OCaml runtime also installs a signal
  49 handler and sometime gets signal targetted at the JVM. The solution to that
  50 is 'Signal chaining'
  51
  52 http://docs.oracle.com/javase/7/docs/technotes/guides/vm/signal-chaining.html
  53
  54 **** TODO: link against -ljsig instead of relying on LD_PRELOAD
  55
  56
  57 * Exceptions
  58
  59 Java exceptions are never checked for in the JNI code.
  60
  61 **** TODO:
  62 We should perform:
  63   if  (env().ExceptionCheck()) { ... }
  64 in the JNI code. However doing so for every call to Java might kill performances
  65
  66
  67 * Makefile
  68 The makefile is buggy and sometimes need to be run twice
  69 **** TODO: fix
  70
  71 * Stack Size
  72 The OCaml code is heavily recursive. It might cause stack overflows of the JVM stack,
  73 and if signal are not handled properly, a segfault instead of an exception. In case of
  74 segfault, first increase the stack size with -Xss100m or so.