+++ /dev/null
-/** @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: <b>A given message type have only one semantic meaning, and
-one syntaxic payload datatype</b>. 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...
-
-
-*/
