src/testbed/testbed_api_topology.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2008--2013 GNUnet e.V.
   4
   5       GNUnet is free software; you can redistribute it and/or modify
   6       it under the terms of the GNU General Public License as published
   7       by the Free Software Foundation; either version 3, or (at your
   8       option) any later version.
   9
  10       GNUnet is distributed in the hope that it will be useful, but
  11       WITHOUT ANY WARRANTY; without even the implied warranty of
  12       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13       General Public License for more details.
  14
  15       You should have received a copy of the GNU General Public License
  16       along with GNUnet; see the file COPYING.  If not, write to the
  17       Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18       Boston, MA 02110-1301, USA.
  19  */
  20
  21 /**
  22  * @file testbed/testbed_api_topology.h
  23  * @brief header for intra library exported functions
  24  * @author Sree Harsha Totakura <sreeharsha@totakura.in>
  25  */
  26
  27 #ifndef TESTBED_API_TOPOLOGY_H
  28 #define TESTBED_API_TOPOLOGY_H
  29
  30 /**
  31  * Returns the number of links that are required to generate a 2d torus for the
  32  * given number of peers. Also returns the arrangment (number of rows and the
  33  * length of each row)
  34  *
  35  * @param num_peers number of peers
  36  * @param rows number of rows in the 2d torus. Can be NULL.
  37  * @param rows_len the length of each row. This array will be allocated
  38  *          fresh. The caller should free it. Can be NULL.
  39  */
  40 unsigned int
  41 GNUNET_TESTBED_2dtorus_calc_links (unsigned int num_peers, unsigned int *rows,
  42                                    unsigned int **rows_len);
  43
  44
  45 /**
  46  * Get a topology from a string input.
  47  *
  48  * @param topology where to write the retrieved topology
  49  * @param topology_string The string to attempt to
  50  *        get a configuration value from
  51  * @return GNUNET_YES if topology string matched a
  52  *         known topology, GNUNET_NO if not
  53  */
  54 int
  55 GNUNET_TESTBED_topology_get_ (enum GNUNET_TESTBED_TopologyOption *topology,
  56                               const char *topology_string);
  57
  58
  59 /**
  60  * Returns the string corresponding to the given topology
  61  *
  62  * @param topology the topology
  63  * @return the string (freshly allocated) of given topology; NULL if topology cannot be
  64  *           expressed as a string
  65  */
  66 char *
  67 GNUNET_TESTBED_topology_to_str_ (enum GNUNET_TESTBED_TopologyOption topology);
  68
  69
  70 /**
  71  * Functions of this type are called to process underlay link
  72  *
  73  * @param cls closure
  74  * @param A offset of first peer
  75  * @param B offset of second peer
  76  * @param bandwidth the bandwidth of the link in bytes per second
  77  * @param latency the latency of link in milliseconds
  78  * @param loss the percentage of messages dropped on the link
  79  * @return GNUNET_OK to continue processing; GNUNET_SYSERR to abort
  80  */
  81 typedef int (*underlay_link_processor) (void *cls,
  82                                         unsigned int A,
  83                                         unsigned int B,
  84                                         unsigned int bandwidth,
  85                                         unsigned int latency,
  86                                         unsigned int loss);
  87
  88
  89 /**
  90  * Function to construct an underlay topology
  91  *
  92  * @param num_peers the number of peers for which the topology should be
  93  *          generated
  94  * @param proc the underlay link processor callback.  Will be called for each
  95  *          underlay link generated unless a previous call to this callback
  96  *          returned GNUNET_SYSERR.  Cannot be NULL.
  97  * @param cls closure for proc
  98  * @param ... variable arguments denoting the topology and its parameters.  They
  99  *          should start with the type of topology to generate followed by their
 100  *          options.  These arguments should *always* end with
 101  *          GNUNET_TESTBED_TOPOLOGY_OPTION_END option
 102  * @return GNUNET_OK if underlay link generation is successful; GNUNET_SYSERR
 103  *          upon error in generating the underlay or if any calls to the
 104  *          underlay link processor returned GNUNET_SYSERR
 105  */
 106 int
 107 GNUNET_TESTBED_underlay_construct_ (int num_peers,
 108                                     underlay_link_processor proc,
 109                                     void *cls,
 110                                     ...);
 111
 112 #endif
 113 /* end of  testbed_api_topology.h */