X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/c91b68ade95e42efb7a24f19fb5228bee0b618d0..187ba0c05f9fbe51175179b9f637b6554f947468:/doc/gtut-files/gtut-howto-design.doc diff --git a/doc/gtut-files/gtut-howto-design.doc b/doc/gtut-files/gtut-howto-design.doc deleted file mode 100644 index 715d850ab7..0000000000 --- a/doc/gtut-files/gtut-howto-design.doc +++ /dev/null @@ -1,179 +0,0 @@ -/** @defgroup GRAS_howto_design HOWTO design a GRAS application - @ingroup GRAS_howto HOWTOs - -This page tries to give some hints on how to design a GRAS application. The -provided model and functionnalities are somehow different from the other -existing solutions (nammly, MPI), and this page tries to give you the feeling -of the GRAS philosophy. You may also want to (re)read the \ref GRAS_tut_intro. - -As an example, you may have a look at \ref GRAS_tut_tour_explicitwait_use, -which somehow follows the guidelines given here. - -\section GRAS_howto_design_toc Table of content - - \ref GRAS_howto_design_what - - \ref GRAS_howto_design_design - - \ref GRAS_howto_design_design_api - - \ref GRAS_howto_design_design_processes - - \ref GRAS_howto_design_design_protocol - - \ref GRAS_howto_design_design_protocol_msg - - \ref GRAS_howto_design_design_protocol_cb - - \ref GRAS_howto_design_implem - - \ref GRAS_howto_design_implem_cb - - \ref GRAS_howto_design_implem_api - - \ref GRAS_howto_design_implem_init - - \ref GRAS_howto_design_test - - \ref GRAS_howto_design_test_sim - - \ref GRAS_howto_design_test_local - - \ref GRAS_howto_design_test_dist - -\section GRAS_howto_design_what What is a GRAS application - -As explained in \ref GRAS_tut_intro, you should see a GRAS application as a -distributed service. There is two main parts: - - a user API, composed of regular functions offering services to the users - - a set of nodes (or processes, or agents, name them as you want) - collaborating and exchanging messages to achieve the requested service on - behalf of the user. - -It is naturally possible to not follow this split, and let the users of your -service directly sending messages by themselves. Nevertheless, this -encapsulation is a good thing because distributed computing is a bit hard to -achieve. You may thus not want to force your users to go into this tricky -part. Instead, shield them with a regular C API. - -If you are the only user of the code you develop, I'd advice you to still -follow this approach. But do as you prefer, of course. - -\section GRAS_howto_design_design The design phase - -\subsection GRAS_howto_design_design_api Specify the user API - -These will be the entry points of your system, and you should think twice -about their syntax and semantic. - -\subsection GRAS_howto_design_design_processes Identify the types of processes in your application - -Note that we are not speaking about the amount of processes in your -application, but rather on the type of processes. The amount of distinct -roles. - -Depending on your application, there may be only one type (for example in a -peer-to-peer system), two types of processes (for example in a client/server -system), three types of processes (for example if you add a forwarder to a -client/server system), or maybe much more. - -\subsection GRAS_howto_design_design_protocol Design an application-level protocol - -During this phase, you should try to sketch your application before -implementing it. You should sketch temporal execution of the application. I -personnaly prefer to do so graphically on a blackboard, drawing comic strips -of the several steps of the algorithm under specific conditions. Ask -yourself questions as "What gets exchanged between who when the user request -this?", "How to react when this condition occures?" and "What is the initial -state of the system?" - -Here are some important points to identify in your future application during -the design phase: - -\subsubsection GRAS_howto_design_design_protocol_msg Message types - -The most important point to design a GRAS protocol is to identify the -different type of messages that can be exchanged in your system, and the -datatype of their payload. Doing so, remember that GRAS messages are -strongly typed. They are formed by a so-called message type (identified by -its name) and a type description describing what kind of data you can -include in the message. The message type is a qualitative information -"someone asked you to run that function" while the payload is the -quantitative information (the arguments to the function). - -A rule of thumb: A given message type have only one semantic meaning, and -one syntaxic payload datatype. If you don't do so, you have a problem. - - - If the same message type may have two semantic value depending on some - fields of the payload, I'd say that you used MPI too much before. You - should use the full power of the GRAS messaging functions by using - several message types. It will simplify your code and yield better - performance. - - - You shouldn't have a given message type with differing payload - datatypes. It is possible to do so (using gras_datadesc_ref_generic()), - but it's quite painful, and is rarely what you really want. Are you - sure you don't want to split these messages in two separate types? - -\subsubsection GRAS_howto_design_design_protocol_cb Message callbacks - -Also sketch what your processes should do when they get the given message. -These action will constitute the message callbacks during the -implementation. But you should first go through a design phase of the -application level-protocol, were these action remain simplistic. Also -identify the process-wide globals needed to write the callbacks (even if it -can be later). - - -\section GRAS_howto_design_implem The implementation phase - -\subsection GRAS_howto_design_implem_cb Write your callbacks - -Most of the time, you will find tons of specific cases you didn't thought -about in the design phase, and going from a code sketch to an actual -implementation is often quite difficult. - -You will probably need some process-wide globals to store some state of your -processes. See \ref GRAS_tut_tour_globals on need. - -\subsection GRAS_howto_design_implem_api Implement your user-API - -If your protocol was wisely designed, writting the user API should be quite -easy. - -\subsection GRAS_howto_design_implem_init Implement the initialization code - -You must write some initialization code for all the process kinds of your -application. - -You may want to turn your code into a clean GRAS library by using the adhoc -mecanism, but unfortunately, it's not documented yet. Worse, there is two -such systems for now, one of them being deprecated. Check the \ref AMOK_pm -implementation to see how to use the new system. Naturally, this is only -optional. - -\section GRAS_howto_design_test The test phase - -Testing software is important to check that it works. But in a distributed -setting, this is mandatory. - -\subsection GRAS_howto_design_test_sim Test it on the simulator - -In addition to all the good old bugs you find in a classical C program -(memory corruption, logical errors, etc), distributed computing introduce -subtil ways to get things wrong. Actually, this is why I wrote GRAS: to get -able to test my code on simulator before using it in distributed settings. - -The simulator is a nicely controled environment. You can rerun the same code -in the exact same condition as often as you want to reproduce a bug. You can -run the simulator in a debugger such as valgrind or gdb to debug all -processes at once. You can cheat and have global variables (to check global -invariants or such). You can test your code on platform you don't have -access to in the real life, or in condition which almost never occur (such -as having 80% of the nodes stopping at the same time). - -Use all these possibilities, and test your code throughfully in the -simulator. You may find it boring, but when you'll go to the next steps, -you'll dream of going back into the comfort of the simulator. - -\subsection GRAS_howto_design_test_local Test it locally - -Once it works in the simulator, test it in real-life, but will all processes -on the same host. Even if the GRAS API is made to make the simulator as -close to the real life as possible, you often discover new and exciting bugs -when going outside of the simulator. Fix'em all before going further. - -If you find you've found a discrepency between both implementation of GRAS, -please drop us a mail. That would be a bug. - -\subsection GRAS_howto_design_test_dist Test it in a distributed setting - -You are now ready for the big jump... - - -*/