include/amok/bandwidth.h

   1 /* amok_bandwidth - Bandwidth test facilities                               */
   2
   3 /* Copyright (c) 2004, 2005, 2006, 2007, 2009, 2010. The SimGrid Team.
   4  * All rights reserved.                                                     */
   5
   6 /* This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the license (GNU LGPL) which comes with this package. */
   8
   9 #ifndef AMOK_BANDWIDTH_H
  10 #define AMOK_BANDWIDTH_H
  11
  12 /** \addtogroup AMOK_bw
  13  *  \brief Test the bandwidth between two nodes
  14  *
  15  *  This module allows you to retrieve the bandwidth between to arbitrary hosts
  16  *  and saturating the links leading to them, provided that they run some GRAS
  17  *  process which initialized this module.
  18  *
  19  * \htmlonly <h3>Bandwidth measurement</h3>\endhtmlonly
  20  *
  21  *  Retrieving the bandwidth is usually done by active measurment: one send
  22  *  a packet of known size, time how long it needs to go back and forth,
  23  *  and you get the bandwidth in Kb/s available on the wire.
  24  *
  25  *  This is not as easy as it first seems to do so in GRAS. The first issue
  26  *  is that GRAS messages can get buffered, or the receiver cannot be
  27  *  waiting for the message when it arrives. This results in extra delays
  28  *  impacting the measurement quality. You thus have to setup a rendez-vous
  29  *  protocol. The second issue is that GRAS message do have an header, so
  30  *  figuring out their size is not trivial. Moreover, they get converted
  31  *  when the sender and receiver processor architecture are different,
  32  *  inducing extra delays. For this, GRAS provide the so-called measurement
  33  *  sockets. On them, you can send raw data which is not converted (see
  34  *  \ref GRAS_sock_meas).
  35  *
  36  *  Solving all these problems is quite error prone and anoying, so we
  37  *  implemented this in the current module so that you don't have to do it
  38  *  yourself. The API is very simple. Use amok_bw_test() to get the BW
  39  *  between the local host and the specified peer, or amok_bw_request() to
  40  *  get the BW between two remote hosts. The elapsed time, as long as the
  41  *  achieved bandwidth is returned in the last arguments of the functions.
  42  *
  43  *  All sizes are in bytes. The \a buf_size is the size of the buffer
  44  *   (this is a socket parameter set automatically). The \a exp_size is the
  45  *   amount of data to send during an experiment. \a msg_size is the size
  46  *   of each message sent. These values allow you to study phenomenon such
  47  *   as TCP slow start (which are not correctly modelized by \ref SURF_API,
  48  *   yet). They are mimicked from the NWS API, and default values could be
  49  *   buf_size=32k, msg_size=16k and exp_size=64k. That means that the
  50  *   socket will be prepared to accept 32k in its buffer and then four
  51  *   messages of 16k will be sent (so that the total amount of data equals
  52  *   64k). Of course, you can use other values if you want to.
  53  *
  54  *  \htmlonly
  55  * <center><img align=center src="amok_bw_test.png" alt="amok bandwidth measurement protocol"><br>
  56  * Fig 1: AMOK bandwidth measurement protocol.</center>
  57  * <h3>Link saturation</h3>
  58  * \endhtmlonly
  59  *
  60  *  You sometimes want to try saturating some link during the network
  61  *  related experiments (at least, we did ;). This also can turn quite
  62  *  untrivial to do, unless you use this great module. You can either ask
  63  *  for the saturation between the current host and a distant one with
  64  *  amok_bw_saturate_begin() or between two distant hosts with
  65  *  amok_bw_saturate_start(). In any case, remember that gras actors
  66  *  (processes) are not interruptible. It means that an actor you
  67  *  instructed to participate to a link saturation experiment will not do
  68  *  anything else until it is to its end (either because the asked duration
  69  *  was done or because someone used amok_bw_saturate_stop() on the emitter
  70  *  end of the experiment).
  71  *
  72  *  The following figure depicts the used protocol. Note that any
  73  *  handshaking messages internal messages are omitted for sake of
  74  *  simplicity. In this example, the experiment ends before the planned
  75  *  experiment duration is over because one host use the
  76  *  amok_bw_saturate_stop() function, but things are not really different
  77  *  if the experiment stops alone. Also, it is not mandatory that the host
  78  *  calling amok_bw_saturate_stop() is the same than the one which called
  79  *  amok_bw_saturate_start(), despite what is depicted here.
  80  *
  81  *  \htmlonly
  82  * <center><img align=center src="amok_bw_sat.png" alt="amok bandwidth saturation protocol"><br>
  83  * Fig 2: AMOK link saturation protocol.</center>
  84  * \endhtmlonly
  85  *
  86  *  @{
  87  */
  88
  89 /* module handling */
  90
  91 XBT_PUBLIC(void) amok_bw_init(void);
  92 XBT_PUBLIC(void) amok_bw_exit(void);
  93
  94 XBT_PUBLIC(void) amok_bw_test(gras_socket_t peer,
  95                               unsigned long int buf_size,
  96                               unsigned long int msg_size,
  97                               unsigned long int msg_amount,
  98                               double min_duration,
  99                               /*OUT*/ double *sec, double *bw);
 100
 101 XBT_PUBLIC(void) amok_bw_request(const char *from_name,
 102                                  unsigned int from_port,
 103                                  const char *to_name, unsigned int to_port,
 104                                  unsigned long int buf_size,
 105                                  unsigned long int msg_size,
 106                                  unsigned long int msg_amount,
 107                                  double min_duration, /*OUT*/ double *sec,
 108                                  double *bw);
 109
 110 XBT_PUBLIC(double *) amok_bw_matrix(xbt_dynar_t hosts,  /* dynar of xbt_host_t */
 111                                     int buf_size_bw, int msg_size_bw,
 112                                     int msg_amount_bw,
 113                                     double min_duration);
 114
 115 /* ***************************************************************************
 116  * Link saturation
 117  * ***************************************************************************/
 118
 119
 120 XBT_PUBLIC(void) amok_bw_saturate_start(const char *from_name,
 121                                         unsigned int from_port,
 122                                         const char *to_name,
 123                                         unsigned int to_port,
 124                                         unsigned int msg_size,
 125                                         double duration);
 126
 127 XBT_PUBLIC(void) amok_bw_saturate_begin(const char *to_name,
 128                                         unsigned int to_port,
 129                                         unsigned int msg_size,
 130                                         double duration,
 131                                         /*out */ double *elapsed,
 132                                         double *bw);
 133
 134 XBT_PUBLIC(void) amok_bw_saturate_stop(const char *from_name,
 135                                        unsigned int from_port,
 136                                        /*out */ double *time, double *bw);
 137
 138 /** @} */
 139
 140 #endif                          /* AMOK_BANDWIDTH_H */