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