README.charm4py

   1
   2 Building Charm++ shared library for Charm4py
   3 ============================================
   4
   5 - Build libcharm for non-SMP mode using 'charm4py' build target.
   6   For example, on a regular Linux machine:
   7   ./build charm4py netlrts-linux-x86_64 -j8 --with-production
   8
   9   NOTE: We are currently requiring non-smp mode because in the most common Python implementation
  10   (CPython), multiple threads cannot run Python code concurrently due to the Global Interpreter Lock
  11   (GIL).
  12
  13 Adding modules (e.g. load balancers) to libcharm.so
  14 ---------------------------------------------------
  15
  16 Currently, modules need to be manually registered (there is a section in
  17 init.C with #if CMK_CHARMPY where this can be done), and the LIBCHARM_LIBS variable in the Makefile
  18 needs to be modified to include the module.
  19
  20 Developer documentation
  21 =======================
  22
  23 Chares that are defined and that run outside of the C/C++ runtime (e.g. Python objects in a Charm4py
  24 program) require lightweight objects acting as counterpart inside the C/C++ runtime.
  25 These C++ objects are:
  26
  27   ReadOnlyExt, MainchareExt, GroupExt and ArrayElemExt
  28
  29 and their function is mainly to relay received messages to their external counterpart.
  30
  31 To allow use of the C++ runtime from external clients (e.g. Charm4py), changes to the
  32 following files have been made:
  33
  34 charm++.h
  35   Declaration of ReadOnlyExt, GroupExt, MainchareExt
  36
  37 charm.h
  38   Declaration of several functions intended to be called from external client. This
  39   includes:
  40     - register callbacks to external client functions
  41     - register external Charm entities (Readonlies, Mainchare, Group, Array)
  42     - object creation
  43     - send message functions
  44     - hooks to Charm functions
  45
  46 register.C
  47   define registration functions for external Charm entities
  48
  49 ck.C
  50   implements most of the new functions and methods
  51
  52 ckarray.h/C
  53   ArrayElemExt
  54
  55 init.C
  56   Changes to circumvent linking issues (see 'Improve/support external module linking'
  57   below for details)
  58   NOTE: These changes are only enabled if building Charm with charm4py support.
  59
  60 TODO
  61 ====
  62
  63 Improve/support external module linking
  64 ---------------------------------------
  65
  66 There are modules like tracing and load balancers that the Charm++ runtime expects
  67 to be linked at the time the final executable is generated. This includes
  68 definitions of the following functions (at the least empty definitions of them):
  69
  70 void CkRegisterMainModule();
  71 void _registerExternalModules(char **argv);
  72 void _createTraces(char **argv);
  73
  74 These are typically defined in a moduleInit.C or similar file created by charmc
  75 during linking of final program executable.
  76
  77 Problem is that when accesing the Charm shared library from Charm4py, these functions
  78 are never defined, so I have disabled calls to them in some cases, or bypassed with alternative
  79 code with #if CMK_CHARMPY macro.
  80
  81 This means that I implemented an alternative way of registering the main
  82 module, via a callback to external client (called from init.C).
  83 And this also means that registering modules like load balancers has to be done
  84 manually in the Charm code (e.g. in init.C).
  85
  86 This process should be improved.
  87
  88 A solution might be to define these functions in a Python c-extension module, and
  89 maybe when accessing the shared library the functions are found, although this
  90 method assumes that the external client will define them.
  91
  92 Or maybe modify charmc to allow building a shared library with the components that
  93 the user wants predefined and linked in.