From 3e1f85ff47cd3650dcb4b1b7aedb802657221377 Mon Sep 17 00:00:00 2001
From: mquinson <mquinson@48e7efb5-ca39-0410-a469-dd3cf9ba447f>
Date: Fri, 24 Mar 2006 09:54:37 +0000
Subject: [PATCH 1/1] Improve the documentation

git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@1979 48e7efb5-ca39-0410-a469-dd3cf9ba447f
---
 include/amok/bandwidth.h | 44 ++++++++++++++++++++++++++++++++--------
 1 file changed, 35 insertions(+), 9 deletions(-)

diff --git a/include/amok/bandwidth.h b/include/amok/bandwidth.h
index a4dc5f6e91..271bb9a707 100644
--- a/include/amok/bandwidth.h
+++ b/include/amok/bandwidth.h
@@ -19,15 +19,41 @@
  *  \brief Test the bandwidth between two nodes
  *
  *  This module allows you to retrieve the bandwidth between to arbitrary hosts, 
- *  provided that they run some GRAS process which initialized this module.
- *
- *  The API is very simple. Use amok_bw_test() to get the BW between the local host
- *  and the specified peer, or amok_bw_request() to get the BW between two remote 
- *  hosts. The elapsed time, as long as the achieved bandwidth is returned in the 
- *  last arguments of the functions.
- *
- *  All sizes are in kilo bytes.
+ *  provided that they run some GRAS process which initialized this module. 
+ * 
+ *  Retrieving the bandwidth is usually done by active measurment: one send
+ *  a packet of known size, time how long it needs to go back and forth,
+ *  and you get the bandwidth in Kb/s available on the wire.
+ * 
+ *  This is not as easy as it first seems to do so in GRAS. The first issue
+ *  is that GRAS messages can get buffered, or the receiver cannot be
+ *  waiting for the message when it arrives. This results in extra delays
+ *  impacting the measurement quality. You thus have to setup a rendez-vous
+ *  protocol. The second issue is that GRAS message do have an header, so
+ *  figuring out their size is not trivial. Moreover, they get converted
+ *  when the sender and receiver processor architecture are different,
+ *  inducing extra delays. For this, GRAS provide the so-called measurement
+ *  sockets. On them, you can send raw data which is not converted (see
+ *  \ref GRAS_sock_meas). 
  *
+ *  Solving all these problems is quite error prone and anoying, so we
+ *  implemented this in the current module so that you don't have to do it
+ *  yourself. The API is very simple. Use amok_bw_test() to get the BW
+ *  between the local host and the specified peer, or amok_bw_request() to
+ *  get the BW between two remote hosts. The elapsed time, as long as the
+ *  achieved bandwidth is returned in the last arguments of the functions.
+ * 
+ *  All sizes are in kilo bytes. The \a buf_size is the size of the buffer
+ *   (this is a socket parameter set automatically). The \a exp_size is the
+ *   amount of data to send during an experiment. \a msg_size is the size
+ *   of each message sent. These values allow you to study phenomenon such
+ *   as TCP slow start (which are not correctly modelized by \ref SURF_API,
+ *   yet). They are mimicked from the NWS API, and default values could be
+ *   buf_size=32k, msg_size=16k and exp_size=64k. That means that the
+ *   socket will be prepared to accept 32k in its buffer and then four
+ *   messages of 16k will be sent (so that the total amount of data equals
+ *   64k). Of course, you can use other values if you want to.
+ * 
  *  \todo Cleanup and implement the link saturation stuff.
  *
  *  @{
@@ -42,7 +68,7 @@ void amok_bw_test(gras_socket_t peer,
 
 void amok_bw_request(const char* from_name,unsigned int from_port,
 		     const char* to_name,unsigned int to_port,
-		     unsigned long int bufSize,unsigned long int expSize,unsigned long int msgSize,
+		     unsigned long int buf_size,unsigned long int exp_size,unsigned long int msg_size,
 	     /*OUT*/ double *sec, double*bw);
 
 /** @} */
-- 
2.20.1