X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/b2f3150048cd87c9e16e251fea65c40221fd56ea..19df82877ce519ee7ce4b9daee206ad6939f4710:/src/kernel/routing/AsImpl.hpp

diff --git a/src/kernel/routing/AsImpl.hpp b/src/kernel/routing/AsImpl.hpp
index ce34fdf50f..ce762368d4 100644
--- a/src/kernel/routing/AsImpl.hpp
+++ b/src/kernel/routing/AsImpl.hpp
@@ -22,8 +22,29 @@ namespace routing {
   /** @brief Autonomous Systems
    *
    * An AS is a network container, in charge of routing information between elements (hosts) and to the nearby ASes.
-   * In SimGrid, there is a hierarchy (a tree) of ASes, with a unique root AS (that you can retrieve from the
-   * s4u::Engine).
+   * In SimGrid, there is a hierarchy of ASes, ie a tree with a unique root AS, that you can retrieve from the
+   * s4u::Engine.
+   *
+   * The purpose of the kernel::routing module is to retrieve the routing path between two points in a time- and
+   * space-efficient manner. This is done by AsImpl::getGlobalRoute(), called when creating a communication to
+   * retrieve both the list of links that the create communication will use, and the summed latency that these
+   * links represent.
+   *
+   * The network could recompute the latency by itself from the list, but it would require an additional link
+   * set traversal. This operation being on the critical path of SimGrid, the routing computes the latency on the
+   * behalf of the network.
+   *
+   * Finding the path between two nodes is rather complex because we navigate a hierarchy of ASes, each of them
+   * being a full network. In addition, the routing can declare shortcuts (called bypasses), either within an AS
+   * at the route level or directly between ASes. Also, each AS can use a differing routing algorithm, depending
+   * on its class. @ref{AsFull} have a full matrix giving explicitly the path between any pair of their
+   * contained nodes, while @ref{AsDijkstra} or @ref{AsFloyd} rely on a shortest path algorithm. @ref{AsVivaldi}
+   * does not even have any link but only use only coordinate information to compute the latency.
+   *
+   * So AsImpl::getGlobalRoute builds the path recursively asking its specific information to each traversed AS with
+   * AsImpl::getLocalRoute, that is redefined in each sub-class.
+   * The algorithm for that is explained in http://hal.inria.fr/hal-00650233/
+   *
    */
   XBT_PUBLIC_CLASS AsImpl : public s4u::As
   {
@@ -36,32 +57,15 @@ namespace routing {
     /** @brief Make an host within that AS */
     simgrid::s4u::Host* createHost(const char* name, std::vector<double>* speedPerPstate, int coreAmount);
 
+  protected:
     /**
-     * @brief Probe the routing path between two points
-     *
-     * The networking model uses this function when creating a communication
-     * to retrieve both the list of links that the create communication will use,
-     * and the summed latency that these links represent.
-     *
-     * The network could recompute the latency by itself from the list, but it would
-     * require an additional link set traversal. This operation being on the critical
-     * path of SimGrid, the routing computes the latency in behalf of the network.
+     * @brief Probe the routing path between two points that are local to the called AS.
      *
-     * Things are rather complex here because we have to find the path from ASes to ASes, and within each.
-     * In addition, the different ASes may use differing routing models.
-     * Some ASes may be routed in full, others may have only some connection information and use a shortest path on top
-     * of that, and so on.
-     * Some ASes may even not have any predefined links and use only coordinate information to compute the latency.
-     *
-     * So, the path is constructed recursively, with each traversed AS adding its information to the set.
-     * The algorithm for that is explained in http://hal.inria.fr/hal-00650233/
-     *
-     * @param src Initial point of the routing path
-     * @param dst Final point of the routing path
-     * @param into Container into which the traversed links should be pushed
+     * @param src where from
+     * @param dst where to
+     * @param into Container into which the traversed links and gateway informations should be pushed
      * @param latency Accumulator in which the latencies should be added (caller must set it to 0)
      */
-  protected:
     virtual void getLocalRoute(NetCard * src, NetCard * dst, sg_platf_route_cbarg_t into, double* latency) = 0;
     /** @brief retrieves the list of all routes of size 1 (of type src x dst x Link) */
     /* returns whether we found a bypass path */
@@ -69,10 +73,18 @@ namespace routing {
                         /* OUT */ std::vector<surf::Link*> * links, double* latency);
 
   public:
+    /* @brief get the route between two nodes in the full platform
+     *
+     * @param src where from
+     * @param dst where to
+     * @param links Accumulator in which all traversed links should be pushed (caller must empty it)
+     * @param latency Accumulator in which the latencies should be added (caller must set it to 0)
+     */
+    static void getGlobalRoute(routing::NetCard * src, routing::NetCard * dst,
+                               /* OUT */ std::vector<surf::Link*> * links, double* latency);
+
     virtual void getOneLinkRoutes(std::vector<Onelink*> * accumulator);
     virtual void getGraph(xbt_graph_t graph, xbt_dict_t nodes, xbt_dict_t edges) = 0;
-    static void getRouteRecursive(routing::NetCard * src, routing::NetCard * dst,
-                                  /* OUT */ std::vector<surf::Link*> * links, double* latency);
     enum class RoutingMode {
       unset = 0, /**< Undefined type                                   */
       base,      /**< Base case: use simple link lists for routing     */