src/interpreter/dynamic_loading_ffi/README.md

   1 This group implement a partial support for the Nit FFI in the interpreter.
   2 It compiles foreign code on demand into a dynamic library that is then loaded and executed.
   3
   4 ## Features
   5
   6 This FFI implementation is a proof of concept, it implements the light FFI and only a subset of the full FFI.
   7
   8 ### From the light FFI:
   9
  10 * Nested extern methods.
  11 * Module level code blocks.
  12 * Passage of primitive types.
  13 * Extern classes and constructors.
  14
  15 ### From the full FFI:
  16
  17 * Static Nit types in C.
  18 * Public code block propagation.
  19 * The `cflags` and `ldflags` annotations.
  20
  21 ### Missing features: (Still TODO)
  22
  23 * Callback to Nit code.
  24 * Support C++, Java and Objective-C.
  25 * Reference pinning.
  26 * Support the `pkgconfig` and `extra_java_files` annotations.
  27
  28 ## The shared library and its API
  29
  30 The generated shared library hold the compiled foreign code of a single module.
  31 It is generated a the first extern method invocation within the module.
  32
  33 The shared library also implements a standard API to be used by the interpreter.
  34 This API is compose of 2 main elements:
  35
  36 * A single data structure to pass Nit instances and primitive data types:
  37
  38   ~~~C
  39   typedef union nit_call_arg {
  40       long value_Int;
  41       int value_Bool;
  42       uint32_t value_Char;
  43       uint8_t value_Byte;
  44       int8_t value_Int8;
  45       int16_t value_Int16;
  46       uint16_t value_UInt16;
  47       int32_t value_Int32;
  48       uint32_t value_UInt32;
  49       double value_Float;
  50       void* value_Pointer;
  51   } nit_call_arg;
  52   ~~~
  53
  54 * Standardized entrypoints, one per extern method in the module.
  55   Their signature is composed of the number or arguments,
  56   a preallocated array of the arguments and a preallocated structure for the return value.
  57
  58   ~~~C
  59   int (*nit_foreign_lib_entry)(int argc, nit_call_arg *args, nit_call_arg *ret);
  60   ~~~
  61
  62   Each entrypoints unpack the arguments and call the FFI implementation method.
  63   The return value is stored in the preallocated structure where the interpreter can retreive it.