[Router] Fixed Code Review Comments and Cleanup Codebase

Added more explanation to the command-line options messages and code
comments.

Cleaned up ParallelConnectionRouter-related codebase.

Author: ueqri

doc/src/vpr/command_line_usage.rst

@@ -1576,8 +1576,14 @@ The following options are only valid when the router is in timing-driven mode (t
 
     Controls whether to enable queue draining optimization for MultiQueue-based parallel connection router.
 
-    When enabled, queues can be emptied quickly by draining all elements if no further solutions need to be explored in the
-    path search to guarantee optimality or determinism after reaching the target.
+    When enabled, queues can be emptied quickly by draining all elements if no further solutions need to be explored after
+    the target is reached in the path search.
+
+    Note: For this optimization to maintain optimality and deterministic results, the 'ordering heuristic' (calculated by
+    :option:`--astar_fac` and :option:`--astar_offset`) must be admissible to ensure emptying queues of entries with higher
+    costs does not prune possibly superior solutions. However, you can still enable this optimization regardless of whether
+    optimality and determinism are required for your specific use case (in such cases, the 'ordering heuristic' can be
+    inadmissible).
 
     This parameter has no effect if :option:`--enable_parallel_connection_router` is not set.
 

utils/route_diag/src/main.cpp

@@ -97,7 +97,6 @@ static void do_one_route(const Netlist<>& net_list,
                                                   segment_inf,
                                                   is_flat);
 
-    // TODO: adding tests for parallel connection router
     SerialConnectionRouter<FourAryHeap> router(
         device_ctx.grid,
         *router_lookahead,

vpr/src/route/NestedNetlistRouter.h

@@ -70,15 +70,15 @@ class NestedNetlistRouter : public NetlistRouter {
     /** Route all nets in a PartitionTree node and add its children to the task queue. */
     void route_partition_tree_node(PartitionTreeNode& node);
 
-    std::shared_ptr<ConnectionRouterInterface> _make_router(const RouterLookahead* router_lookahead,
+    std::unique_ptr<ConnectionRouterInterface> _make_router(const RouterLookahead* router_lookahead,
                                                             const t_router_opts& router_opts,
                                                             bool is_flat) {
         auto& device_ctx = g_vpr_ctx.device();
         auto& route_ctx = g_vpr_ctx.mutable_routing();
 
         if (!router_opts.enable_parallel_connection_router) {
             // Serial Connection Router
-            return std::make_shared<SerialConnectionRouter<HeapType>>(
+            return std::make_unique<SerialConnectionRouter<HeapType>>(
                 device_ctx.grid,
                 *router_lookahead,
                 device_ctx.rr_graph.rr_nodes(),
@@ -89,7 +89,7 @@ class NestedNetlistRouter : public NetlistRouter {
                 is_flat);
         } else {
             // Parallel Connection Router
-            return std::make_shared<ParallelConnectionRouter<HeapType>>(
+            return std::make_unique<ParallelConnectionRouter<HeapType>>(
                 device_ctx.grid,
                 *router_lookahead,
                 device_ctx.rr_graph.rr_nodes(),
@@ -131,19 +131,19 @@ class NestedNetlistRouter : public NetlistRouter {
 
     /* Thread-local storage.
      * These are maps because thread::id is a random integer instead of 1, 2, ... */
-    std::unordered_map<std::thread::id, std::shared_ptr<ConnectionRouterInterface>> _routers_th;
+    std::unordered_map<std::thread::id, std::unique_ptr<ConnectionRouterInterface>> _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 */
-    std::shared_ptr<ConnectionRouterInterface> get_thread_router() {
+    ConnectionRouterInterface& get_thread_router() {
         auto id = std::this_thread::get_id();
         std::lock_guard<std::mutex> lock(_storage_mutex);
         if (!_routers_th.count(id)) {
             _routers_th.emplace(id, _make_router(_router_lookahead, _router_opts, _is_flat));
         }
-        return _routers_th.at(id);
+        return *_routers_th.at(id);
     }
 
     RouteIterResults& get_thread_results() {

vpr/src/route/NestedNetlistRouter.tpp

@@ -68,7 +68,7 @@ void NestedNetlistRouter<HeapType>::route_partition_tree_node(PartitionTreeNode&
         auto& results = get_thread_results();
 
         auto flags = route_net(
-            *get_thread_router(),
+            get_thread_router(),
             _net_list,
             net_id,
             _itry,

vpr/src/route/multi_queue_d_ary_heap.h

@@ -26,10 +26,12 @@
 #include <tuple>
 #include <memory>
 
-using MQHeapNode = std::tuple<HeapNodePriority, uint32_t /*FIXME*/>;
+// FIXME: Use unified heap node struct (HeapNodeId) and comparator (HeapNodeComparator)
+// defined in heap_type.h. Currently, the MQ_IO is not compatible with them. Need a lot
+// of refactoring in MQ_IO to make it work, which is left for another PR to clean it up.
+using MQHeapNode = std::tuple<HeapNodePriority, uint32_t /* FIXME: Use HeapNodeId */>;
 
-// FIXME: use unified heap node struct and comparator in heap_type.h
-struct MQHeapNodeTupleComparator {
+struct MQHeapNodeTupleComparator /* FIXME: Use HeapNodeComparator */ {
     bool operator()(const MQHeapNode& u, const MQHeapNode& v) {
         return std::get<0>(u) > std::get<0>(v);
     }
@@ -102,15 +104,15 @@ class MultiQueueDAryHeap {
         return (bool)(pq_->empty());
     }
 
-    uint64_t getNumPushes() const {
+    uint64_t get_num_pushes() const {
         return pq_->getNumPushes();
     }
 
-    uint64_t getNumPops() const {
+    uint64_t get_num_pops() const {
         return pq_->getNumPops();
     }
 
-    uint64_t getHeapOccupancy() const {
+    uint64_t get_heap_occupancy() const {
         return pq_->getQueueOccupancy();
     }
 
@@ -119,7 +121,7 @@ class MultiQueueDAryHeap {
     }
 
 #ifdef MQ_IO_ENABLE_CLEAR_FOR_POP
-    void setMinPrioForPop(const HeapNodePriority& minPrio) {
+    void set_min_priority_for_pop(const HeapNodePriority& minPrio) {
         pq_->setMinPrioForPop(minPrio);
     }
 #endif

vpr/src/route/parallel_connection_router.cpp

@@ -181,8 +181,8 @@ void ParallelConnectionRouter<Heap>::timing_driven_find_single_shortest_path_fro
     this->thread_barrier_.wait();
 
     // Collect the number of heap pushes and pops
-    this->router_stats_->heap_pushes += this->heap_.getNumPushes();
-    this->router_stats_->heap_pops += this->heap_.getNumPops();
+    this->router_stats_->heap_pushes += this->heap_.get_num_pushes();
+    this->router_stats_->heap_pops += this->heap_.get_num_pops();
 
     // Reset the heap for the next connection
     this->heap_.reset();
@@ -394,7 +394,7 @@ void ParallelConnectionRouter<Heap>::timing_driven_add_to_heap(const t_conn_cost
     if (to_node == target_node) {
 #ifdef MQ_IO_ENABLE_CLEAR_FOR_POP
         if (multi_queue_direct_draining_) {
-            this->heap_.setMinPrioForPop(new_total_cost);
+            this->heap_.set_min_priority_for_pop(new_total_cost);
         }
 #endif
         return;