include/simgrid/kernel/routing/ClusterZone.hpp

   1 /* Copyright (c) 2013-2021. The SimGrid Team. All rights reserved.          */
   2
   3 /* This program is free software; you can redistribute it and/or modify it
   4  * under the terms of the license (GNU LGPL) which comes with this package. */
   5
   6 #ifndef SIMGRID_ROUTING_CLUSTER_HPP_
   7 #define SIMGRID_ROUTING_CLUSTER_HPP_
   8
   9 #include <simgrid/kernel/routing/NetZoneImpl.hpp>
  10 #include <xbt/ex.h>
  11
  12 #include <unordered_map>
  13
  14 namespace simgrid {
  15 namespace kernel {
  16 namespace routing {
  17
  18 /**
  19  * @brief Placeholder for old ClusterZone class
  20  *
  21  * The ClusterZone is now implemented through a StarZone.
  22  *
  23  * Leave this class as a placeholder to avoid compatibility issues
  24  * with codes that use the Engine::get_filtered_netzones.
  25  *
  26  * The old ClusterZone is now called BaseCluster and it's used ONLY as base to
  27  * implement the complex cluster such as Torus, DragonFly and Fat-Tree
  28  */
  29 class ClusterZone : public NetZoneImpl {
  30 protected:
  31   using NetZoneImpl::NetZoneImpl;
  32 };
  33
  34 /**
  35  *  @brief Old ClusterZone implementation
  36  *
  37  *  NOTE: Cannot be directly instantiated anymore.
  38  *
  39  *  NetZone where each component is connected through a private link
  40  *
  41  *  Cluster zones have a collection of private links that interconnect their components.
  42  *  This is particularly well adapted to model a collection of elements interconnected
  43  *  through a hub or a through a switch.
  44  *
  45  *  In a cluster, each component are given from 1 to 3 private links at creation:
  46  *   - Private link (mandatory): link connecting the component to the cluster core.
  47  *   - Limiter (optional): Additional link on the way from the component to the cluster core
  48  *   - Loopback (optional): non-shared link connecting the component to itself.
  49  *
  50  *  Then, the cluster core may be constituted of a specific backbone link or not;
  51  *  A backbone can easily represent a network connected in a Hub.
  52  *  If you want to model a switch, either don't use a backbone at all,
  53  *  or use a fatpipe link (non-shared link) to represent the switch backplane.
  54  *
  55  *  \verbatim
  56  *   (outer world)
  57  *         |
  58  *   ======+====== <--backbone
  59  *   |   |   |   |
  60  * l0| l1| l2| l4| <-- private links + limiters
  61  *   |   |   |   |
  62  *   X   X   X   X <-- cluster's hosts
  63  * \endverbatim
  64  *
  65  * \verbatim
  66  *   (outer world)
  67  *         |       <-- NO backbone
  68  *        /|\
  69  *       / | \     <-- private links + limiters     __________
  70  *      /  |  \
  71  *  l0 / l1|   \l2
  72  *    /    |    \
  73  * host0 host1 host2
  74  * \endverbatim
  75
  76  *  So, a communication from a host A to a host B goes through the following links (if they exist):
  77  *   <tt>limiter(A)_UP, private(A)_UP, backbone, private(B)_DOWN, limiter(B)_DOWN.</tt>
  78  *  link_UP and link_DOWN usually share the exact same characteristics, but their
  79  *  performance are not shared, to model the fact that TCP links are full-duplex.
  80  *
  81  *  A cluster is connected to the outer world through a router that is connected
  82  *  directly to the cluster's backbone (no private link).
  83  *
  84  *  A communication from a host A to the outer world goes through the following links:
  85  *   <tt>limiter(A)_UP, private(A)_UP, backbone</tt>
  86  *  (because the private router is directly connected to the cluster core).
  87  */
  88 class XBT_PRIVATE ClusterBase : public ClusterZone {
  89   /* We use a map instead of a std::vector here because that's a sparse vector. Some values may not exist */
  90   /* The pair is {link_up, link_down} */
  91   std::unordered_map<unsigned long, std::pair<resource::LinkImpl*, resource::LinkImpl*>> private_links_;
  92   std::unordered_map<unsigned long, NetPoint*> gateways_; //!< list of gateways for leafs (if they're netzones)
  93   resource::LinkImpl* backbone_     = nullptr;
  94   NetPoint* router_                 = nullptr;
  95   bool has_limiter_                 = false;
  96   bool has_loopback_                = false;
  97   unsigned long num_links_per_node_ = 1; /* may be 1 (if only a private link), 2 or 3 (if limiter and loopback) */
  98
  99   s4u::Link::SharingPolicy link_sharing_policy_ =
 100       s4u::Link::SharingPolicy::SPLITDUPLEX; //!< cluster links: sharing policy
 101   double link_bw_  = 0.0;                    //!< cluster links: bandwidth
 102   double link_lat_ = 0.0;                    //!< cluster links: latency
 103
 104 protected:
 105   using ClusterZone::ClusterZone;
 106   void set_num_links_per_node(unsigned long num) { num_links_per_node_ = num; }
 107   resource::LinkImpl* get_uplink_from(unsigned long position) const { return private_links_.at(position).first; }
 108   resource::LinkImpl* get_downlink_to(unsigned long position) const { return private_links_.at(position).second; }
 109
 110   double get_link_latency() const { return link_lat_; }
 111   double get_link_bandwidth() const { return link_bw_; }
 112   s4u::Link::SharingPolicy get_link_sharing_policy() const { return link_sharing_policy_; }
 113
 114   void set_loopback();
 115   bool has_loopback() const { return has_loopback_; }
 116   void set_limiter();
 117   bool has_limiter() const { return has_limiter_; }
 118   void set_backbone(resource::LinkImpl* bb) { backbone_ = bb; }
 119   bool has_backbone() const { return backbone_ != nullptr; }
 120   void set_router(NetPoint* router) { router_ = router; }
 121   /** @brief Sets gateway for the leaf */
 122   void set_gateway(unsigned long position, NetPoint* gateway);
 123   /** @brief Gets gateway for the leaf or nullptr */
 124   NetPoint* get_gateway(unsigned long position);
 125   void add_private_link_at(unsigned long position, std::pair<resource::LinkImpl*, resource::LinkImpl*> link);
 126   bool private_link_exists_at(unsigned long position) const
 127   {
 128     return private_links_.find(position) != private_links_.end();
 129   }
 130
 131   void get_graph(const s_xbt_graph_t* graph, std::map<std::string, xbt_node_t, std::less<>>* nodes,
 132                  std::map<std::string, xbt_edge_t, std::less<>>* edges) override
 133   {
 134     /* the old and generic implementation of get_graph doesn't make sense for complex clusters */
 135     THROW_UNIMPLEMENTED;
 136   };
 137
 138   unsigned long node_pos(unsigned long id) const { return id * num_links_per_node_; }
 139   unsigned long node_pos_with_loopback(unsigned long id) const { return node_pos(id) + (has_loopback_ ? 1 : 0); }
 140
 141 public:
 142   /** Fill the leaf retriving netpoint from a user's callback */
 143   void fill_leaf_from_cb(unsigned long position, const std::vector<unsigned long>& dimensions,
 144                          const s4u::ClusterCallbacks& set_callbacks, NetPoint** node_netpoint, s4u::Link** lb_link,
 145                          s4u::Link** limiter_link);
 146   /** @brief Set the characteristics of links inside a Cluster zone */
 147   virtual void set_link_characteristics(double bw, double lat, s4u::Link::SharingPolicy sharing_policy);
 148   unsigned long node_pos_with_loopback_limiter(unsigned long id) const
 149   {
 150     return node_pos_with_loopback(id) + (has_limiter_ ? 1 : 0);
 151   }
 152 };
 153 } // namespace routing
 154 } // namespace kernel
 155 } // namespace simgrid
 156
 157 #endif /* SIMGRID_ROUTING_CLUSTER_HPP_ */