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