doc/gtut-tour-10-rpc.doc

   1 /**
   2 @page GRAS_tut_tour_rpc Lesson 10: Remote Procedure Calling (RPC)
   3
   4 \section GRAS_tut_tour_rpc_toc Table of Contents
   5  - \ref GRAS_tut_tour_rpc_intro
   6   - \ref GRAS_tut_tour_rpc_use
   7       - \ref GRAS_tut_tour_rpc_use_declare
   8       - \ref GRAS_tut_tour_rpc_use_i2a_cb
   9       - \ref GRAS_tut_tour_rpc_use_a2i_cb
  10       - \ref GRAS_tut_tour_rpc_use_rest
  11  - \ref GRAS_tut_tour_rpc_recap
  12
  13 <hr>
  14
  15 \section GRAS_tut_tour_rpc_intro Introduction
  16
  17 So far, we saw how to send messages from one host to another, but quite
  18 often, we need a two-way message exchange: a "client" sends a request to a
  19 "server", and the server returns a result after doing some sort of
  20 computation. This design is often refered to as "Remote Procedure Call" or
  21 RPC for short.
  22
  23 It is naturally possible to build RPC exchanges using only one-way messages,
  24 as the ones we used in GRAS so far, but it's a bit awkward. That is why GRAS
  25 provide a support for RPC, as we will now detail.
  26
  27 \section GRAS_tut_tour_rpc_use Putting rpc into action
  28
  29 We will build a simple RPC where clients use a remote server to convert
  30 strings into numbers and vice-versa (ie, changing between "1234" and 1234).
  31 To achieve its duty, the server will simply use the strtol function in one
  32 direction. In the other direction, we will use bprintf(). This is a sprintf()
  33 version allocating the needed room before doing the conversion. Its
  34 portability is discutable, but SimGrid declares this function when it cannot
  35 be found on the host architecture, so you can use it peacefully.
  36
  37 \subsection GRAS_tut_tour_rpc_use_declare Declaring the RPC
  38
  39 To declare a RPC message, we should simply use gras_msgtype_declare_rpc().
  40 Compared to gras_msgtype_declare() that we use to declare one-way messages,
  41 this function accepts one extra argument: the datatype of the answer
  42 message. In our example, we accept one string in input, and a long in
  43 output for the a2i conversion (a=char 2=to i=integer), and the contrary in
  44 the other direction.
  45
  46 \dontinclude 10-rpc.c
  47 \skip gras_msgtype_declare_rpc
  48 \until long
  49 \until string
  50
  51 \subsection GRAS_tut_tour_rpc_use_i2a_cb Declaring a simple RPC callback: the integer to string conversion
  52
  53 RPC callbacks are very close to "regular" ones. The only difference is that
  54 they must call gras_msg_rpcreturn() at some point to return their result to
  55 the caller. This function accepts 3 arguments: First the timeout to use when
  56 sending back the result (we must use callbacks when doing network
  57 communication to avoid deadlocks and such issues). The second argument is
  58 the callback context that the callback got as first argument. It denotes how
  59 to reach the caller and such. The last argument is a pointer to a variable
  60 containing the result to pass to the caller.
  61
  62 Having the callee explicitly returning data to the caller allows to free
  63 data that were allocated to do the job asked by the client, as in this
  64 example.
  65
  66 \skip server_convert_i2a_cb
  67 \until end_of_convert_callback
  68
  69 \subsection GRAS_tut_tour_rpc_use_a2i_cb RPC and exceptions: the string to integer conversion
  70
  71 When converting strings into integer, we must deal with the possibility that
  72 the provided string is not a number. This is done very easily by raising an
  73 exception in the RPC callback. This exception will get captured by the
  74 middleware running the callback on the server side, sent accross the network
  75 to the client side, and revived here. In short, exceptions raised on callee
  76 side get passed automagically to the caller.
  77
  78 \skip server_convert_a2i_cb
  79 \until end_of_convert_callback
  80
  81 \subsection GRAS_tut_tour_rpc_use_rest The rest of the story
  82
  83 The rest of the story is not really exciting. The server and the client are
  84 very classical compared to what we saw so far. We simply have a specific
  85 message "done" to stop the server when the client is done using it.
  86
  87 This may also be the first time you see the xbt_ex_display() function, which
  88 allows to display an exception as if it were not catched without killing the
  89 process.
  90
  91 \section GRAS_tut_tour_rpc_recap Recapping everything together
  92
  93 The program now reads:
  94 \include 10-rpc.c
  95
  96 Which produces the expected output:
  97 \include 10-rpc.output
  98
  99
 100 */