doc/gtut-howto-design.doc

   1 /** @page GRAS_howto_design HOWTO design a GRAS application
   2
   3 This page tries to give some hints on how to design a GRAS application. The
   4 provided model and functionnalities are somehow different from the other
   5 existing solutions (nammly, MPI), and this page tries to give you the feeling
   6 of the GRAS philosophy. You may also want to (re)read the \ref GRAS_tut_intro.
   7
   8 As an example, you may have a look at \ref GRAS_tut_tour_explicitwait_use,
   9 which somehow follows the guidelines given here.
  10
  11 \section GRAS_howto_design_toc Table of content
  12   - \ref GRAS_howto_design_what
  13   - \ref GRAS_howto_design_design
  14     - \ref GRAS_howto_design_design_api
  15     - \ref GRAS_howto_design_design_processes
  16     - \ref GRAS_howto_design_design_protocol
  17       - \ref GRAS_howto_design_design_protocol_msg
  18       - \ref GRAS_howto_design_design_protocol_cb
  19   - \ref GRAS_howto_design_implem
  20     - \ref GRAS_howto_design_implem_cb
  21     - \ref GRAS_howto_design_implem_api
  22     - \ref GRAS_howto_design_implem_init
  23   - \ref GRAS_howto_design_test
  24     - \ref GRAS_howto_design_test_sim
  25     - \ref GRAS_howto_design_test_local
  26     - \ref GRAS_howto_design_test_dist
  27
  28 \section GRAS_howto_design_what What is a GRAS application
  29
  30 As explained in \ref GRAS_tut_intro, you should see a GRAS application as a
  31 distributed service. There is two main parts:
  32  - a user API, composed of regular functions offering services to the users
  33  - a set of nodes (or processes, or agents, name them as you want)
  34    collaborating and exchanging messages to achieve the requested service on
  35    behalf of the user.
  36
  37 It is naturally possible to not follow this split, and let the users of your
  38 service directly sending messages by themselves. Nevertheless, this
  39 encapsulation is a good thing because distributed computing is a bit hard to
  40 achieve. You may thus not want to force your users to go into this tricky
  41 part. Instead, shield them with a regular C API.
  42
  43 If you are the only user of the code you develop, I'd advice you to still
  44 follow this approach. But do as you prefer, of course.
  45
  46 \section GRAS_howto_design_design The design phase
  47
  48 \subsection GRAS_howto_design_design_api Specify the user API
  49
  50 These will be the entry points of your system, and you should think twice
  51 about their syntax and semantic.
  52
  53 \subsection GRAS_howto_design_design_processes Identify the types of processes in your application
  54
  55 Note that we are not speaking about the amount of processes in your
  56 application, but rather on the type of processes. The amount of distinct
  57 roles.
  58
  59 Depending on your application, there may be only one type (for example in a
  60 peer-to-peer system), two types of processes (for example in a client/server
  61 system), three types of processes (for example if you add a forwarder to a
  62 client/server system), or maybe much more.
  63
  64 \subsection GRAS_howto_design_design_protocol Design an application-level protocol
  65
  66 During this phase, you should try to sketch your application before
  67 implementing it.  You should sketch temporal execution of the application. I
  68 personnaly prefer to do so graphically on a blackboard, drawing comic strips
  69 of the several steps of the algorithm under specific conditions. Ask
  70 yourself questions as "What gets exchanged between who when the user request
  71 this?", "How to react when this condition occures?" and "What is the initial
  72 state of the system?"
  73
  74 Here are some important points to identify in your future application during
  75 the design phase:
  76
  77 \subsubsection GRAS_howto_design_design_protocol_msg Message types
  78
  79 The most important point to design a GRAS protocol is to identify the
  80 different type of messages that can be exchanged in your system, and the
  81 datatype of their payload. Doing so, remember that GRAS messages are
  82 strongly typed. They are formed by a so-called message type (identified by
  83 its name) and a type description describing what kind of data you can
  84 include in the message. The message type is a qualitative information
  85 "someone asked you to run that function" while the payload is the
  86 quantitative information (the arguments to the function).
  87
  88 A rule of thumb: <b>A given message type have only one semantic meaning, and
  89 one syntaxic payload datatype</b>. If you don't do so, you have a problem.
  90
  91    - If the same message type may have two semantic value depending on some
  92      fields of the payload, I'd say that you used MPI too much before. You
  93      should use the full power of the GRAS messaging functions by using
  94      several message types. It will simplify your code and yield better
  95      performance.
  96
  97    - You shouldn't have a given message type with differing payload
  98      datatypes. It is possible to do so (using gras_datadesc_ref_generic()),
  99      but it's quite painful, and is rarely what you really want. Are you
 100      sure you don't want to split these messages in two separate types?
 101
 102 \subsubsection GRAS_howto_design_design_protocol_cb Message callbacks
 103
 104 Also sketch what your processes should do when they get the given message.
 105 These action will constitute the message callbacks during the
 106 implementation. But you should first go through a design phase of the
 107 application level-protocol, were these action remain simplistic. Also
 108 identify the process-wide globals needed to write the callbacks (even if it
 109 can be later).
 110
 111
 112 \section GRAS_howto_design_implem The implementation phase
 113
 114 \subsection GRAS_howto_design_implem_cb Write your callbacks
 115
 116 Most of the time, you will find tons of specific cases you didn't thought
 117 about in the design phase, and going from a code sketch to an actual
 118 implementation is often quite difficult.
 119
 120 You will probably need some process-wide globals to store some state of your
 121 processes. See \ref GRAS_tut_tour_globals on need.
 122
 123 \subsection GRAS_howto_design_implem_api Implement your user-API
 124
 125 If your protocol was wisely designed, writting the user API should be quite
 126 easy.
 127
 128 \subsection GRAS_howto_design_implem_init Implement the initialization code
 129
 130 You must write some initialization code for all the process kinds of your
 131 application.
 132
 133 You may want to turn your code into a clean GRAS library by using the adhoc
 134 mecanism, but unfortunately, it's not documented yet. Worse, there is two
 135 such systems for now, one of them being deprecated. Check the \ref AMOK_pm
 136 implementation to see how to use the new system. Naturally, this is only
 137 optional.
 138
 139 \section GRAS_howto_design_test The test phase
 140
 141 Testing software is important to check that it works. But in a distributed
 142 setting, this is mandatory.
 143
 144 \subsection GRAS_howto_design_test_sim Test it on the simulator
 145
 146 In addition to all the good old bugs you find in a classical C program
 147 (memory corruption, logical errors, etc), distributed computing introduce
 148 subtil ways to get things wrong. Actually, this is why I wrote GRAS: to get
 149 able to test my code on simulator before using it in distributed settings.
 150
 151 The simulator is a nicely controled environment. You can rerun the same code
 152 in the exact same condition as often as you want to reproduce a bug. You can
 153 run the simulator in a debugger such as valgrind or gdb to debug all
 154 processes at once. You can cheat and have global variables (to check global
 155 invariants or such). You can test your code on platform you don't have
 156 access to in the real life, or in condition which almost never occur (such
 157 as having 80% of the nodes stopping at the same time).
 158
 159 Use all these possibilities, and test your code throughfully in the
 160 simulator. You may find it boring, but when you'll go to the next steps,
 161 you'll dream of going back into the comfort of the simulator.
 162
 163 \subsection GRAS_howto_design_test_local Test it locally
 164
 165 Once it works in the simulator, test it in real-life, but will all processes
 166 on the same host. Even if the GRAS API is made to make the simulator as
 167 close to the real life as possible, you often discover new and exciting bugs
 168 when going outside of the simulator. Fix'em all before going further.
 169
 170 If you find you've found a discrepency between both implementation of GRAS,
 171 please drop us a mail. That would be a bug.
 172
 173 \subsection GRAS_howto_design_test_dist Test it in a distributed setting
 174
 175 You are now ready for the big jump...
 176
 177
 178 */