Logo AND Algorithmique Numérique Distribuée

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