ZC API: Rename registration mode variable from mode to regMode
[charm.git] / 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.