doc/module-gras.doc

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