README.charmpy

   1
   2 Building Charm++ shared library for Charmpy
   3 ===========================================
   4
   5 - Build Charm++ in non-SMP mode using '--build-shared --enable-charmpy'
   6   For example, on a regular Linux machine:
   7   ./build charm++ netlrts-linux-x86_64 -j8 --with-production --build-shared --enable-charmpy
   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 - cd lib
  14
  15 - gcc -shared -o libcharm.so -Wl,--whole-archive libck.a libconv-core.a libconv-util.a \
  16   libmemory-default.a libconv-machine.a libthreads-default.a libconv-partition.a libtmgr.a \
  17   libhwloc_embedded.a libldb-rand.a libconv-ldb.a libmoduleGreedyRefineLB.a -Wl,--no-whole-archive -lstdc++
  18
  19   NOTE: For Clang (e.g. on macOS), replace '--whole-archive' and '--no-whole-archive' options with
  20         '-all_load' and '-noall_load' respectively.
  21
  22 - Optionally, add extra modules to the above command, e.g. libmoduleRefineLB.a
  23   but note that currently they also need to be manually registered/added in the code.
  24
  25 Developer documentation
  26 =======================
  27
  28 Chares that are defined and that run outside of the C/C++ runtime (e.g. Python objects in a Charmpy
  29 program) require lightweight objects acting as counterpart inside the C/C++ runtime.
  30 These C++ objects are:
  31
  32   ReadOnlyExt, MainchareExt, GroupExt and ArrayElemExt
  33
  34 and their function is mainly to relay received messages to their external counterpart.
  35
  36 To allow use of the C++ runtime from external clients (e.g. Charmpy), changes to the
  37 following files have been made:
  38
  39 charm++.h
  40   Declaration of ReadOnlyExt, GroupExt, MainchareExt
  41
  42 charm.h
  43   Declaration of several functions intended to be called from external client. This
  44   includes:
  45     - register callbacks to external client functions
  46     - register external Charm entities (Readonlies, Mainchare, Group, Array)
  47     - object creation
  48     - send message functions
  49     - hooks to Charm functions
  50
  51 register.C
  52   define registration functions for external Charm entities
  53
  54 ck.C
  55   implements most of the new functions and methods
  56
  57 ckarray.h/C
  58   ArrayElemExt
  59
  60 init.C
  61   Changes to circumvent linking issues (see 'Improve/support external module linking'
  62   below for details)
  63   NOTE: These changes are only enabled if building Charm with charmpy support.
  64
  65 TODO
  66 ====
  67
  68 Build libcharm shared library with charmc
  69 -----------------------------------------
  70
  71 The above method to generate libcharm may not work in specialized environments. For example, it does
  72 not work on Cray XE because there are a large number of additional system dependencies that libcharm
  73 has to know about. To avoid this, libcharm should be generated by charmc which knows all the required
  74 flags to make a working executable (in this case library).
  75
  76 Improve/support external module linking
  77 ---------------------------------------
  78
  79 There are modules like tracing and load balancers that the Charm++ runtime expects
  80 to be linked at the time the final executable is generated. This includes
  81 definitions of the following functions (at the least empty definitions of them):
  82
  83 void CkRegisterMainModule();
  84 void _registerExternalModules(char **argv);
  85 void _createTraces(char **argv);
  86
  87 These are typically defined in a moduleInit.C or similar file created by charmc
  88 during linking of final program executable.
  89
  90 Problem is that when accesing the Charm shared library from Charmpy, these functions
  91 are never defined, so I have disabled calls to them in some cases, or bypassed with alternative
  92 code with #if CMK_CHARMPY macro.
  93
  94 This means that I implemented an alternative way of registering the main
  95 module, via a callback to external client (called from init.C).
  96 And this also means that registering modules like load balancers has to be done
  97 manually in the Charm code (e.g. in init.C).
  98
  99 This process should be improved.
 100
 101 A solution might be to define these functions in a Python c-extension module, and
 102 maybe when accessing the shared library the functions are found, although this
 103 method assumes that the external client will define them.
 104
 105 Or maybe modify charmc to allow building a shared library with the components that
 106 the user wants predefined and linked in.