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
  11 #include <unordered_map>
  12
  13 namespace simgrid {
  14 namespace kernel {
  15 namespace routing {
  16
  17 /** @ingroup ROUTING_API
  18  *  @brief NetZone where each component is connected through a private link
  19  *
  20  *  Cluster zones have a collection of private links that interconnect their components.
  21  *  This is particularly well adapted to model a collection of elements interconnected
  22  *  through a hub or a through a switch.
  23  *
  24  *  In a cluster, each component are given from 1 to 3 private links at creation:
  25  *   - Private link (mandatory): link connecting the component to the cluster core.
  26  *   - Limiter (optional): Additional link on the way from the component to the cluster core
  27  *   - Loopback (optional): non-shared link connecting the component to itself.
  28  *
  29  *  Then, the cluster core may be constituted of a specific backbone link or not;
  30  *  A backbone can easily represent a network connected in a Hub.
  31  *  If you want to model a switch, either don't use a backbone at all,
  32  *  or use a fatpipe link (non-shared link) to represent the switch backplane.
  33  *
  34  *  \verbatim
  35  *   (outer world)
  36  *         |
  37  *   ======+====== <--backbone
  38  *   |   |   |   |
  39  * l0| l1| l2| l4| <-- private links + limiters
  40  *   |   |   |   |
  41  *   X   X   X   X <-- cluster's hosts
  42  * \endverbatim
  43  *
  44  * \verbatim
  45  *   (outer world)
  46  *         |       <-- NO backbone
  47  *        /|\
  48  *       / | \     <-- private links + limiters     __________
  49  *      /  |  \
  50  *  l0 / l1|   \l2
  51  *    /    |    \
  52  * host0 host1 host2
  53  * \endverbatim
  54
  55  *  So, a communication from a host A to a host B goes through the following links (if they exist):
  56  *   <tt>limiter(A)_UP, private(A)_UP, backbone, private(B)_DOWN, limiter(B)_DOWN.</tt>
  57  *  link_UP and link_DOWN usually share the exact same characteristics, but their
  58  *  performance are not shared, to model the fact that TCP links are full-duplex.
  59  *
  60  *  A cluster is connected to the outer world through a router that is connected
  61  *  directly to the cluster's backbone (no private link).
  62  *
  63  *  A communication from a host A to the outer world goes through the following links:
  64  *   <tt>limiter(A)_UP, private(A)_UP, backbone</tt>
  65  *  (because the private router is directly connected to the cluster core).
  66  */
  67
  68 class ClusterZone : public NetZoneImpl {
  69   /* We use a map instead of a std::vector here because that's a sparse vector. Some values may not exist */
  70   /* The pair is {link_up, link_down} */
  71   std::unordered_map<unsigned int, std::pair<resource::LinkImpl*, resource::LinkImpl*>> private_links_;
  72   std::unordered_map<unsigned int, NetPoint*> gateways_; //!< list of gateways for leafs (if they're netzones)
  73   resource::LinkImpl* backbone_    = nullptr;
  74   NetPoint* router_                = nullptr;
  75   bool has_limiter_                = false;
  76   bool has_loopback_               = false;
  77   unsigned int num_links_per_node_ = 1; /* may be 1 (if only a private link), 2 or 3 (if limiter and loopback) */
  78
  79   s4u::Link::SharingPolicy link_sharing_policy_; //!< cluster links: sharing policy
  80   double link_bw_;                               //!< cluster links: bandwidth
  81   double link_lat_;                              //!< cluster links: latency
  82
  83 protected:
  84   void set_num_links_per_node(unsigned int num) { num_links_per_node_ = num; }
  85   resource::LinkImpl* get_uplink_from(unsigned int position) const { return private_links_.at(position).first; }
  86   resource::LinkImpl* get_downlink_to(unsigned int position) const { return private_links_.at(position).second; }
  87
  88   double get_link_latency() const { return link_lat_; }
  89   double get_link_bandwidth() const { return link_bw_; }
  90   s4u::Link::SharingPolicy get_link_sharing_policy() const { return link_sharing_policy_; }
  91
  92 public:
  93   explicit ClusterZone(const std::string& name);
  94
  95   /** @brief Set the characteristics of links inside a Cluster zone */
  96   virtual void set_link_characteristics(double bw, double lat, s4u::Link::SharingPolicy sharing_policy);
  97   void set_loopback();
  98   bool has_loopback() const { return has_loopback_; }
  99   void set_limiter();
 100   bool has_limiter() const { return has_limiter_; }
 101   void set_backbone(resource::LinkImpl* bb) { backbone_ = bb; }
 102   bool has_backbone() const { return backbone_ != nullptr; }
 103   void set_router(NetPoint* router) { router_ = router; }
 104   /** @brief Sets gateway for the leaf */
 105   void set_gateway(unsigned int position, NetPoint* gateway);
 106   /** @brief Gets gateway for the leaf or nullptr */
 107   NetPoint* get_gateway(unsigned int position);
 108   void add_private_link_at(unsigned int position, std::pair<resource::LinkImpl*, resource::LinkImpl*> link);
 109   bool private_link_exists_at(unsigned int position) const
 110   {
 111     return private_links_.find(position) != private_links_.end();
 112   }
 113
 114   void get_local_route(NetPoint* src, NetPoint* dst, Route* into, double* latency) override;
 115   void get_graph(const s_xbt_graph_t* graph, std::map<std::string, xbt_node_t, std::less<>>* nodes,
 116                  std::map<std::string, xbt_edge_t, std::less<>>* edges) override;
 117
 118   void create_links(int id, int rank);
 119
 120   unsigned int node_pos(int id) const { return id * num_links_per_node_; }
 121   unsigned int node_pos_with_loopback(int id) const { return node_pos(id) + (has_loopback_ ? 1 : 0); }
 122   unsigned int node_pos_with_loopback_limiter(int id) const
 123   {
 124     return node_pos_with_loopback(id) + (has_limiter_ ? 1 : 0);
 125   }
 126   /** Fill the leaf retriving netpoint from a user's callback */
 127   void fill_leaf_from_cb(unsigned int position, const std::vector<unsigned int>& dimensions,
 128                          const s4u::ClusterCallbacks& set_callbacks, NetPoint** node_netpoint, s4u::Link** lb_link,
 129                          s4u::Link** limiter_link);
 130 };
 131 } // namespace routing
 132 } // namespace kernel
 133 } // namespace simgrid
 134
 135 #endif /* SIMGRID_ROUTING_CLUSTER_HPP_ */