doc/gtut-tour-02-simple.doc

   1
   2 /**
   3 @page GRAS_tut_tour_simpleexchange Lesson 2: Exchanging simple messages
   4
   5 \section GRAS_tut_tour_simpleexchange_toc Table of Contents
   6  - \ref GRAS_tut_tour_simpleexchange_msgtype
   7  - \ref GRAS_tut_tour_simpleexchange_socks
   8  - \ref GRAS_tut_tour_simpleexchange_exchange
   9  - \ref GRAS_tut_tour_simpleexchange_recaping
  10
  11 <hr>
  12
  13 \section GRAS_tut_tour_simpleexchange_msgtype Declaring the messages to be exchanged
  14
  15 We will now see how to exchange messages between hosts. As explained in
  16 section \ref GRAS_tut_intro_model, every GRAS message is (strongly) typed. A
  17 message type is described by its name and the datatype of the data it can
  18 convey. Each process which may exchange a given type of message should
  19 declare it before sending or receiving it. If the description used by the
  20 sender doesn't match the one used by the receiver, you'll get into trouble.
  21 Fortunately, such discrepency will be detected in SG.
  22
  23 We won't convey any payload in this lesson, so we just have to give the name
  24 of message to declare them:
  25 \dontinclude 02-simple.c
  26 \skip gras_msgtype_declare
  27 \until gras_msgtype_declare
  28
  29 Remember that all processes should declare the message types they use.
  30
  31 \section GRAS_tut_tour_simpleexchange_socks Identifying peers you want to communicate with
  32
  33 Then, you need to specify with who you want to communicate. This is done
  34 by opening sockets. GRAS sockets are loosely inspirated by the regular BSD
  35 sockets, but with several simplifications.
  36
  37 If you want to eventually receive messages, you have to open a so-called
  38 <i>server socket</i>. Actually, any GRAS process should open a server socket
  39 since it will allows to identify it uniquely in the system. A socket is
  40 defined by an host name and a port number (just like with BSD sockets).
  41
  42 Since server socket are on the current host, opening a socket to receive
  43 messages on the port 12345 is as easy as:
  44 \skip gras_socket_server
  45 \until gras_socket_server
  46
  47 Hardcoding port numbers that way may lead to difficulties on RL (at least)
  48 since at most one process can listen on a given port. So, if you can, prefer
  49 the \ref gras_socket_server_range, which picks a working port from a range
  50 of value. Of course, if you want your processes to find each others, at
  51 least one port must be hardcoded in the system. Then, any other processes
  52 contact the one listening on that port, which acts as a coordinator.
  53
  54 Our client should also open a server socket, but the picked port don't
  55 matter, so we use:
  56 \skip gras_socket_server
  57 \until gras_socket_server
  58
  59 It will select a port between 1024 (ports below 1024 are reserved under
  60 UNIX) and 10000. You can safely ignore the two last arguments for now and
  61 pass 0.
  62
  63 So, you now know how to create sockets allowing to receive messages. To send
  64 messages, you have to create a so-called <i>client socket</i>. For this, use
  65 \ref gras_socket_client with the hostname and the port of the process you
  66 want to contact as arguments. Our client should simply do:
  67
  68 \dontinclude 02-simple.c
  69 \skip socket_client
  70 \until socket_client
  71
  72 The corresponding server socket must be opened before any client socket can
  73 connect to it. It is thus safe to add a little delay before creating the
  74 client socket. But you cannot use the classical sleep() function for this,
  75 or you will delay the simulator in SG, not your processes. Use \ref
  76 gras_os_sleep instead.
  77
  78 \section GRAS_tut_tour_simpleexchange_exchange Actually exchanging messages
  79
  80 GRAS offers a plenty of ways to communicate. The simple one is to use \ref
  81 gras_msg_send on the sender side, and \ref gras_msg_wait on the receiver side.
  82
  83 \ref gras_msg_send expects 3 arguments: the socket on which to send the
  84 message, the message type, and a pointer to the actual content of the
  85 message. The simplest way to retrive a message type from its name is to use
  86 \ref gras_msgtype_by_name. Since we don't have any payload, this becomes:
  87
  88 \dontinclude 02-simple.c
  89 \skip msg_send
  90 \until msg_send
  91
  92 \ref gras_msg_wait accepts 4 arguments. The first one is the delay you are
  93 disposed to wait for messages, while the the type of message you are
  94 expecting. Then come output arguments. The third argument should be the
  95 address of a gras_socket_t variable which will indicate who wrote the
  96 message you received while the last argument is where to put the payload.
  97
  98 Since our server is willing to wait up to 60 seconds for a message, the
  99 following will do it:
 100 \dontinclude 02-simple.c
 101 \skip msg_wait
 102 \until msg_wait
 103
 104 \section GRAS_tut_tour_simpleexchange_recaping Recaping everything together
 105
 106 Here is the complete code of this example. Note the use of the functions
 107 \ref gras_socket_my_port, \ref gras_socket_peer_name and \ref
 108 gras_socket_peer_port to retrieve information about who you are connected to.
 109
 110 \include 02-simple.c
 111
 112 Here is the output of the simulator. Note that \ref gras_socket_peer_port
 113 actually returns the port number of the <i>server</i> of the peer. This may
 114 sound a bit strange to BSD experts, but it is actually really useful: you
 115 can store this value, and contact your peer afterward passing this number to
 116 \ref gras_socket_client .
 117 \include 02-simple.output
 118
 119 Here we are, you now know how to exchange messages between peers. There is
 120 still a large room for improvement, such as adding payload to messages. But
 121 there some little things you should know before we speak of payloads.
 122
 123 Go to \ref GRAS_tut_tour_args
 124
 125 */