include/amok/bandwidth.h

   1 /* $Id$ */
   2
   3 /* amok_bandwidth - Bandwidth test facilities                               */
   4
   5 /* Copyright (c) 2003-2005 Martin Quinson. All rights reserved.             */
   6
   7 /* This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the license (GNU LGPL) which comes with this package. */
   9
  10 #ifndef AMOK_BANDWIDTH_H
  11 #define AMOK_BANDWIDTH_H
  12
  13 #include "amok/base.h"
  14
  15 /* module handling */
  16
  17
  18 /** \addtogroup AMOK_bw
  19  *  \brief Test the bandwidth between two nodes
  20  *
  21  *  This module allows you to retrieve the bandwidth between to arbitrary hosts,
  22  *  provided that they run some GRAS process which initialized this module.
  23  *
  24  *  Retrieving the bandwidth is usually done by active measurment: one send
  25  *  a packet of known size, time how long it needs to go back and forth,
  26  *  and you get the bandwidth in Kb/s available on the wire.
  27  *
  28  *  This is not as easy as it first seems to do so in GRAS. The first issue
  29  *  is that GRAS messages can get buffered, or the receiver cannot be
  30  *  waiting for the message when it arrives. This results in extra delays
  31  *  impacting the measurement quality. You thus have to setup a rendez-vous
  32  *  protocol. The second issue is that GRAS message do have an header, so
  33  *  figuring out their size is not trivial. Moreover, they get converted
  34  *  when the sender and receiver processor architecture are different,
  35  *  inducing extra delays. For this, GRAS provide the so-called measurement
  36  *  sockets. On them, you can send raw data which is not converted (see
  37  *  \ref GRAS_sock_meas).
  38  *
  39  *  Solving all these problems is quite error prone and anoying, so we
  40  *  implemented this in the current module so that you don't have to do it
  41  *  yourself. The API is very simple. Use amok_bw_test() to get the BW
  42  *  between the local host and the specified peer, or amok_bw_request() to
  43  *  get the BW between two remote hosts. The elapsed time, as long as the
  44  *  achieved bandwidth is returned in the last arguments of the functions.
  45  *
  46  *  All sizes are in bytes. The \a buf_size is the size of the buffer
  47  *   (this is a socket parameter set automatically). The \a exp_size is the
  48  *   amount of data to send during an experiment. \a msg_size is the size
  49  *   of each message sent. These values allow you to study phenomenon such
  50  *   as TCP slow start (which are not correctly modelized by \ref SURF_API,
  51  *   yet). They are mimicked from the NWS API, and default values could be
  52  *   buf_size=32k, msg_size=16k and exp_size=64k. That means that the
  53  *   socket will be prepared to accept 32k in its buffer and then four
  54  *   messages of 16k will be sent (so that the total amount of data equals
  55  *   64k). Of course, you can use other values if you want to.
  56  *
  57  *  \htmlonly
  58  * <img align=center src="amok_bw_test.png" alt="amok bandwidth measurement protocol"><br>
  59  * \endhtmlonly
  60  *
  61  *  \todo Cleanup and implement the link saturation stuff.
  62  *
  63  *  @{
  64  */
  65
  66 void amok_bw_init(void);
  67 void amok_bw_exit(void);
  68
  69 void amok_bw_test(gras_socket_t peer,
  70                   unsigned long int buf_size,unsigned long int exp_size,unsigned long int msg_size,
  71           /*OUT*/ double *sec, double *bw);
  72
  73 void amok_bw_request(const char* from_name,unsigned int from_port,
  74                      const char* to_name,unsigned int to_port,
  75                      unsigned long int buf_size,unsigned long int exp_size,unsigned long int msg_size,
  76              /*OUT*/ double *sec, double*bw);
  77
  78 /** @} */
  79 #if 0
  80
  81 /* ***************************************************************************
  82  * Link saturation
  83  * ***************************************************************************/
  84
  85 /**
  86  * grasbw_saturate_start:
  87  * @from_name: Name of the host we are asking to do a experiment with (to_name:to_port)
  88  * @from_port: port on which the process we are asking for an experiment is listening
  89  * (for message, do not give a raw socket here. The needed raw socket will be negociated
  90  * between the peers)
  91  * @to_name: Name of the host with which we should conduct the experiment
  92  * @to_port: port on which the peer process is listening for message
  93  * @msgSize: Size of each message sent.
  94  * @timeout: How long in maximum should be the saturation.
  95  *
  96  * Ask the process 'from_name:from_port' to start to saturate the link between itself
  97  * and to_name:to_name.
  98  */
  99 void grasbw_saturate_start(const char* from_name,unsigned int from_port,
 100                                   const char* to_name,unsigned int to_port,
 101                                   unsigned int msgSize, unsigned int timeout);
 102
 103 /**
 104  * grasbw_saturate_stop:
 105  * @from_name: Name of the host we are asking to do a experiment with (to_name:to_port)
 106  * @from_port: port on which the process we are asking for an experiment is listening
 107  * (for message, do not give a raw socket here. The needed raw socket will be negociated
 108  * between the peers)
 109  * @to_name: Name of the host with which we should conduct the experiment
 110  * @to_port: port on which the peer process is listening for message
 111  *
 112  * Ask the process 'from_name:from_port' to stop saturating the link between itself
 113  * and to_name:to_name.
 114  */
 115 void grasbw_saturate_stop(const char* from_name,unsigned int from_port,
 116                                  const char* to_name,unsigned int to_port);
 117
 118
 119 #endif /* if 0 */
 120 #endif /* AMOK_BANDWIDTH_H */