change name to NestedNetlistRouter

Author: duck2

libs/libvtrutil/src/vtr_thread_pool.h

@@ -19,25 +19,42 @@
 
 namespace vtr {
 
+/**
+ * A thread pool for parallel task execution. It is a naive
+ * implementation which uses a queue for each thread and assigns
+ * tasks in a round robin fashion.
+ *
+ * Example usage:
+ *
+ * vtr::thread_pool pool(4);
+ * pool.schedule_work([]{
+ *     // Task body
+ * });
+ * pool.wait_for_all(); // There's no API to wait for a single task
+ */
 class thread_pool {
 private:
+    /* Thread-local data */
     struct ThreadData {
         std::thread thread;
+        /* Per-thread task queue */
         std::queue<std::function<void()>> task_queue;
+
+        /* Threads wait on cv for a stop signal or a new task
+         * queue_mutex is required for condition variable */
         std::mutex queue_mutex;
         std::condition_variable cv;
         bool stop = false;
-        size_t thread_id;
-
-        ThreadData(size_t id) : thread_id(id) {}
     };
 
+    /* Container for thread-local data */
     std::vector<std::unique_ptr<ThreadData>> threads;
+    /* Used for round-robin scheduling */
     std::atomic<size_t> next_thread{0};
-    std::atomic<size_t> total_tasks_queued{0};
+    /* Used for wait_for_all */
     std::atomic<size_t> active_tasks{0};
 
-    /* Condition variable for wait_for_all*/
+    /* Condition variable for wait_for_all */
     std::mutex completion_mutex;
     std::condition_variable completion_cv;
 
@@ -46,14 +63,15 @@ class thread_pool {
         threads.reserve(thread_count);
 
         for (size_t i = 0; i < thread_count; i++) {
-            auto thread_data = std::make_unique<ThreadData>(i);
+            auto thread_data = std::make_unique<ThreadData>();
 
             thread_data->thread = std::thread([&]() {
                 ThreadData* td = thread_data.get();
 
                 while (true) {
                     std::function<void()> task;
-                    {
+
+                    { /* Wait until a task is available or stop signal is received */
                         std::unique_lock<std::mutex> lock(td->queue_mutex);
 
                         td->cv.wait(lock, [td]() {
@@ -64,6 +82,7 @@ class thread_pool {
                             return;
                         }
 
+                        /* Fetch a task from the queue */
                         task = std::move(td->task_queue.front());
                         td->task_queue.pop();
                     }
@@ -84,20 +103,19 @@ class thread_pool {
         /* Round-robin thread assignment */
         size_t thread_idx = (next_thread++) % threads.size();
         auto thread_data = threads[thread_idx].get();
-        size_t task_id = ++total_tasks_queued;
 
-        auto task = [this, f = std::forward<F>(f), thread_id = thread_data->thread_id, task_id]() {
+        auto task = [this, f = std::forward<F>(f)]() {
             vtr::Timer task_timer;
 
             try {
                 f();
             } catch (const std::exception& e) {
-                VTR_LOG_ERROR("Thread %zu failed task %zu with error: %s\n", 
-                             thread_id, task_id, e.what());
+                VTR_LOG_ERROR("Thread %zu failed task with error: %s\n", 
+                             std::this_thread::get_id(), e.what());
                 throw;
             } catch (...) {
-                VTR_LOG_ERROR("Thread %zu failed task %zu with unknown error\n", 
-                             thread_id, task_id);
+                VTR_LOG_ERROR("Thread %zu failed task with unknown error\n", 
+                             std::this_thread::get_id());
                 throw;
             }
 

vpr/src/base/ShowSetup.cpp

@@ -254,8 +254,8 @@ static void ShowRouterOpts(const t_router_opts& RouterOpts) {
 
     VTR_LOG("RouterOpts.router_algorithm: ");
     switch (RouterOpts.router_algorithm) {
-        case MIXED:
-            VTR_LOG("MIXED\n");
+        case NESTED:
+            VTR_LOG("NESTED\n");
             break;
         case PARALLEL:
             VTR_LOG("PARALLEL\n");

vpr/src/base/read_options.cpp

@@ -171,8 +171,8 @@ struct ParseRoutePredictor {
 struct ParseRouterAlgorithm {
     ConvertedValue<e_router_algorithm> from_str(const std::string& str) {
         ConvertedValue<e_router_algorithm> conv_value;
-        if (str == "mixed")
-            conv_value.set_value(MIXED);
+        if (str == "nested")
+            conv_value.set_value(NESTED);
         else if (str == "parallel")
             conv_value.set_value(PARALLEL);
         else if (str == "parallel_decomp")
@@ -189,8 +189,8 @@ struct ParseRouterAlgorithm {
 
     ConvertedValue<std::string> to_str(e_router_algorithm val) {
         ConvertedValue<std::string> conv_value;
-        if (val == MIXED)
-            conv_value.set_value("mixed");
+        if (val == NESTED)
+            conv_value.set_value("nested");
         else if (val == PARALLEL)
             conv_value.set_value("parallel");
         else if (val == PARALLEL_DECOMP)
@@ -2409,9 +2409,10 @@ argparse::ArgumentParser create_arg_parser(const std::string& prog_name, t_optio
             "Specifies the router algorithm to use.\n"
             " * timing driven: focuses on routability and circuit speed [default]\n"
             " * parallel: timing_driven with nets in different regions of the chip routed in parallel\n"
-            " * parallel_decomp: timing_driven with additional parallelism obtained by decomposing high-fanout nets, possibly reducing quality\n")
+            " * parallel_decomp: timing_driven with additional parallelism obtained by decomposing high-fanout nets, possibly reducing quality\n"
+            " * nested: parallel with parallelized path search\n")
         .default_value("timing_driven")
-        .choices({"mixed","parallel", "parallel_decomp", "timing_driven"})
+        .choices({"nested","parallel", "parallel_decomp", "timing_driven"})
         .show_in(argparse::ShowIn::HELP_ONLY);
 
     route_grp.add_argument(args.min_incremental_reroute_fanout, "--min_incremental_reroute_fanout")

vpr/src/base/vpr_types.h

@@ -1186,7 +1186,7 @@ struct t_ap_opts {
  * read_rr_graph_name:  stores the file name of the rr graph to be read by vpr */
 
 enum e_router_algorithm {
-    MIXED,
+    NESTED,
     PARALLEL,
     PARALLEL_DECOMP,
     TIMING_DRIVEN,

vpr/src/route/MixedNetlistRouter.h renamed to vpr/src/route/NestedNetlistRouter.h

@@ -1,6 +1,6 @@
 #pragma once
 
-/** @file Mixed case for NetlistRouter */
+/** @file Nested parallel case for NetlistRouter */
 #include "netlist_routers.h"
 #include "vtr_optional.h"
 #include "vtr_thread_pool.h"
@@ -9,15 +9,21 @@
 /* Add cmd line option for this later */
 constexpr int MAX_THREADS = 4;
 
-/** Mixed impl for NetlistRouter.
+/** Nested parallel impl for NetlistRouter.
+ *
+ * Calls a parallel ConnectionRouter for route_net to extract even more parallelism.
+ * The main reason why this is a different router instead of templating NetlistRouter
+ * on ConnectionRouter is this router does not use TBB. The scheduling performance is
+ * worse, but it can wait in individual tasks now (which is not possible with TBB).
+ *
  * Holds enough context members to glue together ConnectionRouter and net routing functions,
  * such as \ref route_net. Keeps the members in thread-local storage where needed,
  * i.e. ConnectionRouters and RouteIterResults-es.
  * See \ref route_net. */
 template<typename HeapType>
-class MixedNetlistRouter : public NetlistRouter {
+class NestedNetlistRouter : public NetlistRouter {
   public:
-    MixedNetlistRouter(
+    NestedNetlistRouter(
         const Netlist<>& net_list,
         const RouterLookahead* router_lookahead,
         const t_router_opts& router_opts,
@@ -43,15 +49,18 @@ class MixedNetlistRouter : public NetlistRouter {
         , _choking_spots(choking_spots)
         , _is_flat(is_flat)
         , _thread_pool(MAX_THREADS) {}
-    ~MixedNetlistRouter() {}
+    ~NestedNetlistRouter() {}
 
     /** Run a single iteration of netlist routing for this->_net_list. This usually means calling
      * \ref route_net for each net, which will handle other global updates.
      * \return RouteIterResults for this iteration. */
     RouteIterResults route_netlist(int itry, float pres_fac, float worst_neg_slack);
     /** Inform the PartitionTree of the nets with updated bounding boxes */
     void handle_bb_updated_nets(const std::vector<ParentNetId>& nets);
+
+    /** Set rcv_enabled for each ConnectionRouter this is managing */
     void set_rcv_enabled(bool x);
+    /** Set timing_info for each ConnectionRouter this is managing */
     void set_timing_info(std::shared_ptr<SetupHoldTimingInfo> timing_info);
 
   private:
@@ -95,13 +104,17 @@ class MixedNetlistRouter : public NetlistRouter {
     /** The partition tree. Holds the groups of nets for each partition */
     vtr::optional<PartitionTree> _tree;
 
+    /** Thread pool for parallel routing. See vtr_thread_pool.h for implementation */
     vtr::thread_pool _thread_pool;
 
-    /* Thread-local storage */
+    /* Thread-local storage.
+     * These are maps because thread::id is a random integer instead of 1, 2, ... */
     std::unordered_map<std::thread::id, ConnectionRouter<HeapType>> _routers_th;
     std::unordered_map<std::thread::id, RouteIterResults> _results_th;
     std::mutex _storage_mutex;
 
+    /** Get a thread-local ConnectionRouter. We lock the id->router lookup, but this is
+     * accessed once per partition so the overhead should be small */
     ConnectionRouter<HeapType>& get_thread_router() {
         auto id = std::this_thread::get_id();
         std::lock_guard<std::mutex> lock(_storage_mutex);
@@ -118,4 +131,4 @@ class MixedNetlistRouter : public NetlistRouter {
     }
 };
 
-#include "MixedNetlistRouter.tpp"
+#include "NestedNetlistRouter.tpp"

vpr/src/route/MixedNetlistRouter.tpp renamed to vpr/src/route/NestedNetlistRouter.tpp

@@ -8,7 +8,7 @@
 #include "vtr_time.h"
 
 template<typename HeapType>
-inline RouteIterResults MixedNetlistRouter<HeapType>::route_netlist(int itry, float pres_fac, float worst_neg_slack) {
+inline RouteIterResults NestedNetlistRouter<HeapType>::route_netlist(int itry, float pres_fac, float worst_neg_slack) {
     /* Reset results for each thread */
     for (auto& [_, results] : _results_th) {
         results = RouteIterResults();
@@ -50,7 +50,7 @@ inline RouteIterResults MixedNetlistRouter<HeapType>::route_netlist(int itry, fl
 }
 
 template<typename HeapType>
-void MixedNetlistRouter<HeapType>::route_partition_tree_node(PartitionTreeNode& node) {
+void NestedNetlistRouter<HeapType>::route_partition_tree_node(PartitionTreeNode& node) {
     auto& route_ctx = g_vpr_ctx.mutable_routing();
 
     /* node.nets is an unordered set, copy into vector to sort */
@@ -123,19 +123,19 @@ void MixedNetlistRouter<HeapType>::route_partition_tree_node(PartitionTreeNode&
 }
 
 template<typename HeapType>
-void MixedNetlistRouter<HeapType>::handle_bb_updated_nets(const std::vector<ParentNetId>& nets) {
+void NestedNetlistRouter<HeapType>::handle_bb_updated_nets(const std::vector<ParentNetId>& nets) {
     VTR_ASSERT(_tree);
     _tree->update_nets(nets);
 }
 
 template<typename HeapType>
-void MixedNetlistRouter<HeapType>::set_rcv_enabled(bool x) {
+void NestedNetlistRouter<HeapType>::set_rcv_enabled(bool x) {
     for (auto& [_, router] : _routers_th) {
         router.set_rcv_enabled(x);
     }
 }
 
 template<typename HeapType>
-void MixedNetlistRouter<HeapType>::set_timing_info(std::shared_ptr<SetupHoldTimingInfo> timing_info) {
+void NestedNetlistRouter<HeapType>::set_timing_info(std::shared_ptr<SetupHoldTimingInfo> timing_info) {
     _timing_info = timing_info;
 }

vpr/src/route/netlist_routers.h

@@ -71,7 +71,7 @@ class NetlistRouter {
 
 /* Include the derived classes here to get the HeapType-templated impls */
 #include "SerialNetlistRouter.h"
-#include "MixedNetlistRouter.h"
+#include "NestedNetlistRouter.h"
 #ifdef VPR_USE_TBB
 #    include "ParallelNetlistRouter.h"
 #    include "DecompNetlistRouter.h"
@@ -105,8 +105,8 @@ inline std::unique_ptr<NetlistRouter> make_netlist_router_with_heap(
             routing_predictor,
             choking_spots,
             is_flat);
-    } else if (router_opts.router_algorithm == e_router_algorithm::MIXED) {
-        return std::make_unique<MixedNetlistRouter<HeapType>>(
+    } else if (router_opts.router_algorithm == e_router_algorithm::NESTED) {
+        return std::make_unique<NestedNetlistRouter<HeapType>>(
             net_list,
             router_lookahead,
             router_opts,