1 /* amok_bandwidth - Bandwidth test facilities */
3 /* Copyright (c) 2004, 2005, 2006, 2007, 2009, 2010. The SimGrid Team.
4 * All rights reserved. */
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. */
9 #ifndef AMOK_BANDWIDTH_H
10 #define AMOK_BANDWIDTH_H
12 /** \addtogroup AMOK_bw
13 * \brief Test the bandwidth between two nodes
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.
19 * \htmlonly <h3>Bandwidth measurement</h3>\endhtmlonly
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.
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).
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.
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.
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>
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).
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.
82 * <center><img align=center src="amok_bw_sat.png" alt="amok bandwidth saturation protocol"><br>
83 * Fig 2: AMOK link saturation protocol.</center>
91 XBT_PUBLIC(void) amok_bw_init(void);
92 XBT_PUBLIC(void) amok_bw_exit(void);
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,
99 /*OUT*/ double *sec, double *bw);
101 XBT_PUBLIC(void) amok_bw_request(const char *from_name,
102 unsigned int from_port, const char *to_name,
103 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,
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, double min_duration);
114 /* ***************************************************************************
116 * ***************************************************************************/
119 XBT_PUBLIC(void) amok_bw_saturate_start(const char *from_name,
120 unsigned int from_port,
122 unsigned int to_port,
123 unsigned int msg_size,
126 XBT_PUBLIC(void) amok_bw_saturate_begin(const char *to_name,
127 unsigned int to_port,
128 unsigned int msg_size,
130 /*out */ double *elapsed, double *bw);
132 XBT_PUBLIC(void) amok_bw_saturate_stop(const char *from_name,
133 unsigned int from_port,
134 /*out */ double *time, double *bw);
138 #endif /* AMOK_BANDWIDTH_H */