1 /* Copyright (c) 2013-2023. The SimGrid Team. All rights reserved. */
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. */
6 #ifndef SIMGRID_ROUTING_CLUSTER_HPP_
7 #define SIMGRID_ROUTING_CLUSTER_HPP_
9 #include <simgrid/kernel/routing/NetZoneImpl.hpp>
12 #include <unordered_map>
14 namespace simgrid::kernel::routing {
17 * @brief Placeholder for old ClusterZone class
19 * The ClusterZone is now implemented through a StarZone.
21 * Leave this class as a placeholder to avoid compatibility issues
22 * with codes that use the Engine::get_filtered_netzones.
24 * The old ClusterZone is now called BaseCluster and it's used ONLY as base to
25 * implement the complex cluster such as Torus, DragonFly and Fat-Tree
27 class ClusterZone : public NetZoneImpl {
29 using NetZoneImpl::NetZoneImpl;
33 * @brief Old ClusterZone implementation
35 * NOTE: Cannot be directly instantiated anymore.
37 * NetZone where each component is connected through a private link
39 * Cluster zones have a collection of private links that interconnect their components.
40 * This is particularly well adapted to model a collection of elements interconnected
41 * through a hub or a through a switch.
43 * In a cluster, each component are given from 1 to 3 private links at creation:
44 * - Private link (mandatory): link connecting the component to the cluster core.
45 * - Limiter (optional): Additional link on the way from the component to the cluster core
46 * - Loopback (optional): non-shared link connecting the component to itself.
48 * Then, the cluster core may be constituted of a specific backbone link or not;
49 * A backbone can easily represent a network connected in a Hub.
50 * If you want to model a switch, either don't use a backbone at all,
51 * or use a fatpipe link (non-shared link) to represent the switch backplane.
56 * ======+====== <--backbone
58 * l0| l1| l2| l4| <-- private links + limiters
60 * X X X X <-- cluster's hosts
67 * / | \ <-- private links + limiters __________
74 * So, a communication from a host A to a host B goes through the following links (if they exist):
75 * <tt>limiter(A)_UP, private(A)_UP, backbone, private(B)_DOWN, limiter(B)_DOWN.</tt>
76 * link_UP and link_DOWN usually share the exact same characteristics, but their
77 * performance are not shared, to model the fact that TCP links are full-duplex.
79 * A cluster is connected to the outer world through a router that is connected
80 * directly to the cluster's backbone (no private link).
82 * A communication from a host A to the outer world goes through the following links:
83 * <tt>limiter(A)_UP, private(A)_UP, backbone</tt>
84 * (because the private router is directly connected to the cluster core).
86 class XBT_PRIVATE ClusterBase : public ClusterZone {
87 /* We use a map instead of a std::vector here because that's a sparse vector. Some values may not exist */
88 /* The pair is {link_up, link_down} */
89 std::unordered_map<unsigned long, std::pair<resource::StandardLinkImpl*, resource::StandardLinkImpl*>> private_links_;
90 std::unordered_map<unsigned long, NetPoint*> gateways_; //!< list of gateways for leafs (if they're netzones)
91 resource::StandardLinkImpl* backbone_ = nullptr;
92 NetPoint* router_ = nullptr;
93 bool has_limiter_ = false;
94 bool has_loopback_ = false;
95 unsigned long num_links_per_node_ = 1; /* may be 1 (if only a private link), 2 or 3 (if limiter and loopback) */
97 s4u::Link::SharingPolicy link_sharing_policy_ =
98 s4u::Link::SharingPolicy::SPLITDUPLEX; //!< cluster links: sharing policy
99 double link_bw_ = 0.0; //!< cluster links: bandwidth
100 double link_lat_ = 0.0; //!< cluster links: latency
103 using ClusterZone::ClusterZone;
104 void set_num_links_per_node(unsigned long num) { num_links_per_node_ = num; }
105 resource::StandardLinkImpl* get_uplink_from(unsigned long position) const
107 return private_links_.at(position).first;
109 resource::StandardLinkImpl* get_downlink_to(unsigned long position) const
111 return private_links_.at(position).second;
114 double get_link_latency() const { return link_lat_; }
115 double get_link_bandwidth() const { return link_bw_; }
116 s4u::Link::SharingPolicy get_link_sharing_policy() const { return link_sharing_policy_; }
119 bool has_loopback() const { return has_loopback_; }
121 bool has_limiter() const { return has_limiter_; }
122 void set_backbone(resource::StandardLinkImpl* bb) { backbone_ = bb; }
123 bool has_backbone() const { return backbone_ != nullptr; }
124 void set_router(NetPoint* router) { router_ = router; }
125 /** @brief Sets gateway for the leaf */
126 void set_gateway(unsigned long position, NetPoint* gateway);
127 /** @brief Gets gateway for the leaf or nullptr */
128 NetPoint* get_gateway(unsigned long position);
129 void add_private_link_at(unsigned long position,
130 std::pair<resource::StandardLinkImpl*, resource::StandardLinkImpl*> link);
131 bool private_link_exists_at(unsigned long position) const
133 return private_links_.find(position) != private_links_.end();
136 unsigned long node_pos(unsigned long id) const { return id * num_links_per_node_; }
137 unsigned long node_pos_with_loopback(unsigned long id) const { return node_pos(id) + (has_loopback_ ? 1 : 0); }
140 /** Fill the leaf retriving netpoint from a user's callback */
141 void fill_leaf_from_cb(unsigned long position, const std::vector<unsigned long>& dimensions,
142 const s4u::ClusterCallbacks& set_callbacks, NetPoint** node_netpoint, s4u::Link** lb_link,
143 s4u::Link** limiter_link);
144 /** @brief Set the characteristics of links inside a Cluster zone */
145 virtual void set_link_characteristics(double bw, double lat, s4u::Link::SharingPolicy sharing_policy);
146 unsigned long node_pos_with_loopback_limiter(unsigned long id) const
148 return node_pos_with_loopback(id) + (has_limiter_ ? 1 : 0);
151 } // namespace simgrid::kernel::routing
153 #endif /* SIMGRID_ROUTING_CLUSTER_HPP_ */