doc/module-gras.doc

   1 #####################################################################
   2 ###########################  CORE ###################################
   3 #####################################################################
   4
   5 /** \addtogroup GRAS_API
   6
   7     \section GRAS_funct Offered functionnalities
   8      - <b>\ref GRAS_comm</b>: Exchanging messages between peers
   9        - \ref GRAS_dd : any data which may transit on the network must be
  10          described beforehand so that GRAS can handle the platform
  11          heterogeneity and convert them if needed.
  12        - \ref GRAS_sock : this is how to open a communication channel to
  13          other processes, and retrive information about them.
  14        - \ref GRAS_msg : communications are message oriented. You have to
  15          describe all possible messages and their payload beforehand, and
  16          can then attach callbacks to the arrival of a given kind of message.
  17        - \ref GRAS_timer : this is how to program repetitive and delayed
  18          tasks, not unlike cron(8) and at(1). This cannot be used to timeout
  19          a function (like setitimer(2) or signal(2) games could do).
  20      - <b>\ref GRAS_run</b>: Running both on top of the simulator and on
  21        top of real platforms, and portability support.
  22        - \ref GRAS_virtu : You naturally don't want to call the
  23           gettimeofday(2) function in simulation mode since it would give
  24           you the time on the host running the simulation, not the time in
  25           the simulated world (you are belonging to).\n
  26           This a system call virtualization layer, which also acts as a
  27           portability layer.
  28        - \ref GRAS_globals : The use of globals is forbidden since the
  29          "processes" are threads in simulation mode. \n
  30          This is how to let GRAS handle your globals properly.
  31        - \ref GRAS_emul : Support to emulate code excution (ie, reporting
  32          execution time into the simulator and having code sections specific
  33          to simulation or to real mode).
  34
  35     \section GRAS_example Examples
  36
  37     There is for now rather few examples of GRAS, but it's better than
  38     nothing, isn't it?
  39
  40        - \ref GRAS_ex_ping
  41        - \ref GRAS_ex_mmrpc
  42        - \ref GRAS_ex_token
  43        - \ref GRAS_ex_timer
  44
  45     \section GRAS_tut_presentation Tutorial
  46
  47     We even have a tutorial for the GRAS framework. Here is the table of
  48     content:
  49        - \ref GRAS_tut_intro
  50          - \ref GRAS_tut_intro_what
  51          - \ref GRAS_tut_intro_model
  52        - \ref GRAS_tut_tour
  53          - \ref GRAS_tut_tour_install
  54          - \ref GRAS_tut_tour_setup
  55          - \ref GRAS_tut_tour_simpleexchange
  56          - \ref GRAS_tut_tour_args
  57          - \ref GRAS_tut_tour_callbacks
  58          - \ref GRAS_tut_tour_globals
  59          - \ref GRAS_tut_tour_logs
  60          - \ref GRAS_tut_tour_timers
  61          - \ref GRAS_tut_tour_exceptions
  62          - \ref GRAS_tut_tour_rpc
  63
  64     @{ */
  65        /** @defgroup GRAS_comm    Communication facilities */
  66        /** @defgroup GRAS_run     Virtualization */
  67        /** @defgroup GRAS_ex      Examples */
  68        /** @defgroup GRAS_tut     GRAS Tutorial */
  69 /** @} */
  70 #####################################################################
  71 /** @addtogroup GRAS_comm
  72
  73    Here are the communication facilities. GRAS allows you to exchange
  74    <i>messages</i> on <i>sockets</i> (which can be seen as pipes between
  75    processes). On reception, messages start <i>callbacks</i> (that's the
  76    default communication mode, not the only one). All messages of a given
  77    type convey the same kind of data, and you have to describe it
  78    beforehand.
  79
  80    Timers are also seen as a mean of communication (with yourself). It
  81    allows you to run a repetitive task ("do this every N second until I tell
  82    you to stop"), or to deffer a treatment ("do this in 3 sec").
  83
  84     @{ */
  85        /** @defgroup GRAS_dd      Data description      */
  86        /** @defgroup GRAS_sock    Sockets               */
  87        /** @defgroup GRAS_msg     Messages              */
  88        /** @defgroup GRAS_timer   Timers                */
  89
  90 /** @} */
  91 #####################################################################
  92 /** @addtogroup GRAS_run
  93
  94    Virtualization facilities allow your code to run both on top of the simulator or in real setting.
  95
  96     @{ */
  97
  98        /** @defgroup GRAS_globals Globals               */
  99        /** @defgroup GRAS_emul    Emulation support */
 100        /** @defgroup GRAS_virtu   Syscalls              */
 101
 102 /** @} */
 103
 104 #####################################################################
 105 /** @addtogroup GRAS_ex
 106
 107     There is for now rather few examples of GRAS, but it's better than
 108     nothing, isn't it?
 109
 110        - \ref GRAS_ex_ping
 111        - \ref GRAS_ex_mmrpc
 112        - \ref GRAS_ex_token
 113        - \ref GRAS_ex_timer
 114
 115     \htmlonly <!--
 116       DOXYGEN_NAVBAR_CHILD "Ping-Pong"=GRAS_ex_ping.html
 117       DOXYGEN_NAVBAR_CHILD "RPC"=GRAS_ex_mmrpc.html
 118       DOXYGEN_NAVBAR_CHILD "Token Ring"=GRAS_ex_token.html
 119       DOXYGEN_NAVBAR_CHILD "Timers"=GRAS_ex_timer.html
 120     --> \endhtmlonly
 121
 122   There is some more examples in the distribution, under the directory
 123   <tt>examples/gras</tt>.
 124 */
 125
 126 #####################################################################
 127 #########################  EXAMPLES #################################
 128 #####################################################################
 129
 130 ---------------------------------------------------------------------
 131 ------------------------- Ping Pong ---------------------------------
 132 ---------------------------------------------------------------------
 133
 134 /** \page GRAS_ex_ping The classical Ping-Pong in GRAS
 135
 136     This example implements the very classical ping-pong in GRAS. It
 137     involves a client (initiating the ping-pong) and a server (answering to
 138     client's requests).
 139
 140     It works the following way:
 141      - Both the client and the server register all needed messages
 142      - The server registers a callback to the ping message, which sends pong
 143        to the expeditor
 144      - The client sends the ping message to the server, and waits for the
 145        pong message as an answer.
 146
 147     This example resides in the <b>examples/gras/ping/ping.c</b> file. Yes, both
 148     the code of the client and of the server is placed in the same file. See
 149     the \ref GRAS_tut_tour_setup of the tutorial if wondering.
 150
 151     \section GRAS_ex_ping_toc Table of contents of the ping example
 152       - \ref GRAS_ex_ping_common
 153         - \ref GRAS_ex_ping_initial
 154         - \ref GRAS_ex_ping_register
 155       - \ref GRAS_ex_ping_server
 156         - \ref GRAS_ex_ping_serdata
 157         - \ref GRAS_ex_ping_sercb
 158         - \ref GRAS_ex_ping_sermain
 159       - \ref GRAS_ex_ping_client
 160         - \ref GRAS_ex_ping_climain
 161
 162     <hr>
 163
 164     \dontinclude gras/ping/ping_common.c
 165
 166     \section GRAS_ex_ping_common 1) Common code to the client and the server
 167
 168     \subsection GRAS_ex_ping_initial 1.a) Initial settings
 169
 170     Let's first load the module header and declare a logging category (see
 171     \ref XBT_log for more info on logging).
 172
 173     \skip include
 174     \until XBT_LOG
 175
 176     The module header <tt>ping.h</tt> reads:
 177
 178     \dontinclude gras/ping/ping.h
 179     \skip include
 180     \until argv
 181     \until argv
 182
 183     \subsection GRAS_ex_ping_register 1.b) Register the messages
 184
 185     This function, called by both the client and the server is in charge of
 186     declaring the existing messages to GRAS. Since the payload does not
 187     involve any newly created types but only int, this is quite easy.
 188     (to exchange more complicated types, see \ref GRAS_dd or
 189     \ref GRAS_ex_mmrpc for an example).
 190
 191     \dontinclude gras/ping/ping_common.c
 192     \skip register_messages
 193     \until }
 194
 195     [Back to \ref GRAS_ex_ping_toc]
 196
 197     \section GRAS_ex_ping_server 2) Server's code
 198
 199     \subsection GRAS_ex_ping_serdata 2.a) The server's globals
 200
 201     In order to ensure the communication between the "main" and the callback
 202     of the server, we need to declare some globals. We have to put them in a
 203     struct definition so that they can be handled properly in GRAS (see the
 204     \ref GRAS_tut_tour_globals for more info).
 205
 206     \dontinclude gras/ping/ping_server.c
 207     \skip typedef struct
 208     \until }
 209
 210     \subsection GRAS_ex_ping_sercb 2.b) The callback to the ping message
 211
 212     Here is the callback run when the server receives any ping message (this
 213     will be registered later by the server).
 214
 215     \skip server_cb_ping_handler
 216     \until end_of_server_cb_ping_handler
 217
 218     \subsection GRAS_ex_ping_sermain 2.c) The "main" of the server
 219
 220     This is the "main" of the server. As explained in the tutorial, \ref
 221     GRAS_tut_tour_setup, you must not write any main()
 222     function yourself. Instead, you just have to write a regular function
 223     like this one which will act as a main.
 224
 225     \skip server
 226     \until end_of_server
 227
 228     [Back to \ref GRAS_ex_ping_toc]
 229
 230     \section GRAS_ex_ping_client 3) Client's code
 231
 232     \subsection GRAS_ex_ping_climain 3.a) Client's "main" function
 233
 234     This function is quite straightforward, and the inlined comments should
 235     be enough to understand it.
 236
 237     \dontinclude gras/ping/ping_client.c
 238     \skip client
 239     \until end_of_client
 240
 241     [Back to \ref GRAS_ex_ping_toc]
 242  */
 243
 244 ---------------------------------------------------------------------
 245 --------------------- Simple Token Ring -----------------------------
 246 ---------------------------------------------------------------------
 247
 248 /** \page GRAS_ex_token Token Ring example
 249
 250    This example implements the token ring algorithm. It involves several
 251    nodes arranged in a ring (each of them have a left and a right neighbour)
 252    and exchanging a "token". This algorithm is one of the solution to ensure
 253    the mutual exclusion between distributed processes. There is only one
 254    token at any time, so the process in its possession is ensured to be the
 255    only one having it. So, if there is an action you want all processes to
 256    do alternativly, but you cannot afford to have two processes doing it at
 257    the same time, let the process having the token doing it.
 258
 259    Actually, there is a lot of different token ring algorithms in the
 260    litterature, so this example implements one of them: the simplest one.
 261    The ring is static (no new node can join it, and you'll get trouble if
 262    one node dies or leaves), and nothing is done for the case in which the
 263    token is lost.
 264
 265    - \ref GRAS_ex_stoken_deploy
 266    - \ref GRAS_ex_stoken_global
 267    - \ref GRAS_ex_stoken_callback
 268    - \ref GRAS_ex_stoken_main
 269
 270    \section GRAS_ex_stoken_deploy 1) Deployment file
 271
 272    Here is the deployment file:
 273    \include examples/gras/mutual_exclusion/simple_token/simple_token.xml
 274
 275    The neighbour of each node is given at startup as command line argument.
 276    Moreover, one of the nodes is instructed by a specific argument (the one
 277    on Tremblay here) to create the token at the begining of the algorithm.
 278
 279    \section GRAS_ex_stoken_global 2) Global definition
 280
 281    The token is incarned by a specific message, which circulates from node
 282    to node (the payload is an integer incremented at each hop). So, the most
 283    important part of the code is the message callback, which forwards the
 284    message to the next node. That is why we have to store all variable in a
 285    global, as explained in the \ref GRAS_globals section.
 286
 287    \dontinclude examples/gras/mutual_exclusion/simple_token/simple_token.c
 288    \skip typedef
 289    \until }
 290
 291    \section GRAS_ex_stoken_callback 3) The callback
 292
 293    Even if this is the core of this algorithm, this function is quite
 294    straightforward.
 295
 296    \skip node_cb_stoken_handler
 297    \until end_of_node_cb_stoken_handler
 298
 299    \section GRAS_ex_stoken_main 4) The main function
 300
 301    This function is splited in two parts: The first one performs all the
 302    needed initialisations (points 1-7) while the end (point 8. below) calls
 303    gras_msg_handle() as long as the planned amount of ring loops are not
 304    performed.
 305
 306    \skip node
 307    \until end_of_node
 308
 309 */
 310
 311 ---------------------------------------------------------------------
 312 -------------------------- MM RPC -----------------------------------
 313 ---------------------------------------------------------------------
 314
 315 /** \page GRAS_ex_mmrpc A simple RPC for matrix multiplication
 316
 317     This example implements a remote matrix multiplication. It involves a client
 318     (creating the matrices and sending the multiplications requests) and a server
 319     (computing the multiplication on client's behalf).
 320
 321     This example also constitutes a more advanced example of data description
 322     mechanisms, since the message payload type is a bit more complicated than in
 323     other examples such as the ping one (\ref GRAS_ex_ping).
 324
 325     It works the following way (not very different from the ping example):
 326      - Both the client and the server register all needed messages and datatypes
 327      - The server registers a callback to the "request" message, which computes
 328        what needs to be and returns the result to the expeditor.
 329      - The client creates two matrices, ask for their multiplication and check
 330        the server's answer.
 331
 332     This example resides in the <b>examples/gras/mmrpc/mmrpc.c</b> file. (See
 333     the \ref GRAS_tut_tour_setup of the tutorial if wondering why both the server
 334     and the client live in the same source file)
 335
 336     \section GRAS_ex_mmrpc_toc Table of contents of the mmrpc example
 337       - \ref GRAS_ex_mmrpc_common
 338         - \ref GRAS_ex_mmrpc_header
 339         - \ref GRAS_ex_mmrpc_dataregister
 340         - \ref GRAS_ex_mmrpc_logdef
 341         - \ref GRAS_ex_mmrpc_msgregister
 342         - \ref GRAS_ex_mmrpc_matdump
 343       - \ref GRAS_ex_mmrpc_server
 344         - \ref GRAS_ex_mmrpc_serinc
 345         - \ref GRAS_ex_mmrpc_sercb
 346         - \ref GRAS_ex_mmrpc_sermain
 347       - \ref GRAS_ex_mmrpc_client
 348         - \ref GRAS_ex_mmrpc_cliinc
 349         - \ref GRAS_ex_mmrpc_climain
 350
 351     <hr>
 352
 353
 354     \section GRAS_ex_mmrpc_common 1) Common code to the client and the server (mmrpc_common.c and mmrpc.h)
 355
 356
 357     \subsection GRAS_ex_mmrpc_header 1.a) Module header (mmrpc.h)
 358
 359     This loads the gras header and declare the function's prototypes as well
 360     as the matrix size.
 361
 362     \dontinclude gras/mmrpc/mmrpc.h
 363     \skip include
 364     \until argv
 365     \until argv
 366
 367     \subsection GRAS_ex_mmrpc_dataregister 1.b) Register the data types (mmrpc.h)
 368
 369     The messages involved in this example do use structures as payload,
 370     so we have to declare it to GRAS. Hopefully, this can be done easily by enclosing
 371     the structure declaration within a \ref GRAS_DEFINE_TYPE macro call. It will then copy this
 372     declaration into an hidden string variable, which can be automatically parsed at
 373     run time. Of course, the declaration is also copied unmodified by this macro, so that it
 374     gets parsed by the compiler also.
 375
 376     There is some semantic that GRAS cannot guess alone and you need to  <i>annotate</i>
 377     your declaration to add some. For example, the ctn pointer can be a reference to an
 378     object or a whole array (in which case you also has to specify its size). This is done
 379     with the GRAS_ANNOTE call. It is removed from the text passed to the compiler, but it helps
 380     GRAS getting some information about the semantic of your data. Here, it says that \a ctn is an
 381     array, which size is the result of the operation \a rows * \a cols (with \a rows and \a cols
 382     being the other fields of the structure).
 383
 384     Please note that this annotation mechanism is not as robust and cool as this example seems to
 385     imply. If you want to use it yourself, you'd better use the exact right syntax, which is
 386     detailed in the \ref GRAS_dd section.
 387
 388     \skip GRAS_DEFINE_TYPE
 389     \until matrix_t
 390
 391     \subsection GRAS_ex_mmrpc_logdef 1.c) Logging category definition (mmrpc_common.c)
 392
 393     Let's first load the module header and declare a logging category (see
 394     \ref XBT_log for more info on logging). This logging category does live
 395     in this file (ie the required symbols are defined here and declared as
 396     "extern" in any other file using them). That is why we use
 397     \ref XBT_LOG_NEW_DEFAULT_CATEGORY here and
 398     \ref XBT_LOG_EXTERNAL_DEFAULT_CATEGORY in mmrpc_client.c and mmrpc_server.c.
 399
 400     \dontinclude gras/mmrpc/mmrpc_common.c
 401     \skip include
 402     \until XBT_LOG
 403
 404     \subsection GRAS_ex_mmrpc_msgregister 1.d) Register the messages (mmrpc_common.c)
 405
 406     This function, called by both the client and the server is in charge of
 407     declaring the existing messages to GRAS. Note the use of the \ref gras_datadesc_by_symbol
 408     function to parse and retrieve the structure declaration which were passed to \ref GRAS_DEFINE_TYPE
 409     above.
 410
 411     The datatype description builded that way can then be used to build an array datatype or
 412     to declare messages.
 413
 414     \skip register_messages
 415     \until }
 416
 417     \subsection GRAS_ex_mmrpc_matdump 1.e) Helper debugging function (mmrpc_common.c)
 418
 419     This function dumps a matrix to screen for debugging.
 420
 421     \skip mat_dump
 422     \until end_of_matrix
 423     \until }
 424
 425     [Back to \ref GRAS_ex_mmrpc_toc]
 426
 427     \section GRAS_ex_mmrpc_server 2) Server's code (mmrpc_server.c)
 428
 429     \subsection GRAS_ex_mmrpc_serinc 2.a) Server intial settings
 430
 431     All module symbols live in the mmrpc_common.c file. We thus have to
 432     define \ref GRAS_DEFINE_TYPE_EXTERN to the preprocessor so that the
 433     \ref GRAS_DEFINE_TYPE symbols don't get included here. Likewise, we use
 434     \ref XBT_LOG_EXTERNAL_DEFAULT_CATEGORY to get the log category in here.
 435
 436     \dontinclude gras/mmrpc/mmrpc_server.c
 437     \skip define
 438     \until XBT_LOG
 439
 440     \subsection GRAS_ex_mmrpc_sercb 2.b) The callback to the mmrpc message
 441
 442     Here is the callback run when the server receives any mmrpc message (this
 443     will be registered later by the server). Note the way we get the message
 444     payload. In the ping example, there was one additional level of pointer
 445     indirection (see \ref GRAS_ex_ping_sercb). This is because the payload is
 446     an array here (ie a pointer) whereas it is a scalar in the ping example.
 447
 448     \skip server_cb_request_handler
 449     \until end_of_server_cb_request_handler
 450
 451     \subsection GRAS_ex_mmrpc_sermain 2.c) The "main" of the server
 452
 453     This is the "main" of the server. As explained in the tutorial, \ref
 454     GRAS_tut_tour_setup, you must not write any main()
 455     function yourself. Instead, you just have to write a regular function
 456     like this one which will act as a main.
 457
 458     \skip server
 459     \until end_of_server
 460
 461     [Back to \ref GRAS_ex_mmrpc_toc]
 462
 463     \section GRAS_ex_mmrpc_client 3) Client's code (mmrpc_client.c)
 464
 465     \subsection GRAS_ex_mmrpc_cliinc 2.a) Server intial settings
 466
 467     As for the server, some extra love is needed to make sure that automatic
 468     datatype parsing and log categories do work even if we are using several
 469     files.
 470
 471     \dontinclude gras/mmrpc/mmrpc_client.c
 472     \skip define
 473     \until XBT_LOG
 474
 475     \subsection GRAS_ex_mmrpc_climain 3.b) Client's "main" function
 476
 477     This function is quite straightforward, and the inlined comments should
 478     be enough to understand it.
 479
 480     \dontinclude gras/mmrpc/mmrpc_client.c
 481     \skip argv
 482     \until end_of_client
 483
 484     [Back to \ref GRAS_ex_mmrpc_toc]
 485   */
 486
 487 ---------------------------------------------------------------------
 488 ---------------------------- Timers ---------------------------------
 489 ---------------------------------------------------------------------
 490
 491 /** \page GRAS_ex_timer Some timer games
 492
 493     This example fools around with the GRAS timers (\ref GRAS_timer). It is
 494     mainly a regression test, since it uses almost all timer features.
 495
 496     The main program registers a repetititive task and a delayed one, and
 497     then loops until the <tt>still_to_do</tt> variables of its globals reach
 498     0. The delayed task set it to 5, and the repetititive one decrease it
 499     each time. Here is an example of output:
 500 \verbatim Initialize GRAS
 501  Initialize XBT
 502  [1108335471] Programming the repetitive_action with a frequency of 1.000000 sec
 503  [1108335471] Programming the delayed_action for after 2.000000 sec
 504  [1108335471] Have a rest
 505  [1108335472] Canceling the delayed_action.
 506  [1108335472] Re-programming the delayed_action for after 2.000000 sec
 507  [1108335472] Repetitive_action has nothing to do yet
 508  [1108335473] Repetitive_action has nothing to do yet
 509  [1108335473] delayed_action setting globals->still_to_do to 5
 510  [1108335474] repetitive_action decrementing globals->still_to_do. New value: 4
 511  [1108335475] repetitive_action decrementing globals->still_to_do. New value: 3
 512  [1108335476] repetitive_action decrementing globals->still_to_do. New value: 2
 513  [1108335477] repetitive_action decrementing globals->still_to_do. New value: 1
 514  [1108335478] repetitive_action decrementing globals->still_to_do. New value: 0
 515  Exiting GRAS\endverbatim
 516
 517     Source code:
 518      - \ref GRAS_ex_timer_decl
 519      - \ref GRAS_ex_timer_delay
 520      - \ref GRAS_ex_timer_repeat
 521      - \ref GRAS_ex_timer_main
 522
 523     \dontinclude timer.c
 524
 525     \section GRAS_ex_timer_decl   1. Declarations and headers
 526     \skip include
 527     \until my_globals
 528
 529     \section GRAS_ex_timer_delay  2. Source code of the delayed action
 530     \skip repetitive_action
 531     \until end_of_repetitive_action
 532
 533     \section GRAS_ex_timer_repeat 3. Source code of the repetitive action
 534     \skip delayed_action
 535     \until end_of_delayed_action
 536
 537     \section GRAS_ex_timer_main   4. Source code of main function
 538     \skip client
 539     \until end_of_client
 540 */