doc/gtut-tour-2-simple.doc

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