3 /* amok_bandwidth - Bandwidth test facilities */
5 /* Copyright (c) 2003-2005 Martin Quinson. All rights reserved. */
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. */
10 #ifndef AMOK_BANDWIDTH_H
11 #define AMOK_BANDWIDTH_H
13 #include "amok/base.h"
18 /** \addtogroup AMOK_bw
19 * \brief Test the bandwidth between two nodes
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.
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.
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).
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.
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.
58 * <img align=center src="amok_bw_test.png" alt="amok bandwidth measurement protocol"><br>
61 * \todo Cleanup and implement the link saturation stuff.
66 void amok_bw_init(void);
67 void amok_bw_exit(void);
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);
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);
78 double * amok_bw_matrix(xbt_dynar_t hosts, /* dynar of xbt_host_t */
79 int buf_size_bw, int exp_size_bw, int msg_size_bw);
81 /* ***************************************************************************
83 * ***************************************************************************/
86 void amok_bw_saturate_start(const char* from_name,unsigned int from_port,
87 const char* to_name,unsigned int to_port,
88 unsigned int msg_size, double duration);
90 void amok_bw_saturate_begin(const char* to_name,unsigned int to_port,
91 unsigned int msg_size, double duration,
92 /*out*/ double *elapsed, double *bw);
94 void amok_bw_saturate_stop(const char* from_name,unsigned int from_port,
95 /*out*/ unsigned int *time, unsigned int *bw);
99 #endif /* AMOK_BANDWIDTH_H */