doc/gtut-howto-design.doc

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