Added Doxygen comments to HeapImplementation and its children (excluding bucket heap)

Author: Nathan Shreve

vpr/src/route/four_ary_heap.h

@@ -12,6 +12,12 @@ class FourAryHeap : public KAryHeap {
   private:
     void sift_down(size_t hole) final;
     size_t parent(size_t i) const final;
+
+    /**
+     * @param i The parent node.
+     *
+     * @return The child node of i with the smallest cost.
+     */
     size_t smallest_child(size_t i) const;
 };
 

vpr/src/route/heap_type.h

@@ -96,116 +96,152 @@ class HeapStorage {
     size_t num_heap_allocated_;
 };
 
-// Interface to heap used for router optimization.
-//
-// Note: Objects used in instances of HeapInterface must always be allocated
-// and free'd using the HeapInterface::alloc and HeapInterface::free methods
-// of that instance.  Object pools are likely in use.
-//
-// As a general rule, any t_heap objects returned from this interface,
-// **must** be HeapInterface::free'd before destroying the HeapInterface
-// instance.  This ensure that no leaks are present in the users of the heap.
-// Violating this assumption may result in a assertion violation.
+/**
+ * @brief Interface to heap used for router optimization.
+ *
+ * @details
+ * Note: Objects used in instances of HeapInterface must always be allocated
+ * and free'd using the HeapInterface::alloc and HeapInterface::free methods
+ * of that instance.  Object pools are likely in use.<BR><BR>
+ * As a general rule, any t_heap objects returned from this interface,
+ * **must** be HeapInterface::free'd before destroying the HeapInterface
+ * instance. This ensure that no leaks are present in the users of the heap.
+ * Violating this assumption may result in a assertion violation.
+ */
 class HeapInterface {
   public:
     virtual ~HeapInterface() {}
 
-    // Allocate a heap item.
-    //
-    // This transfers ownership of the t_heap object from HeapInterface to the
-    // caller.
+    /**
+     * @brief Allocate a heap item.
+     *
+     * @details
+     * This transfers ownership of the t_heap object from HeapInterface to the
+     * caller.
+     */
     virtual t_heap* alloc() = 0;
 
-    // Free a heap item.
-    //
-    // HeapInterface::free can be called on objects returned from either
-    // HeapInterface::alloc or HeapInterface::get_heap_head.
+    /**
+     * @brief Free a heap item.
+     *
+     * @details
+     * HeapInterface::free can be called on objects returned from either
+     * HeapInterface::alloc or HeapInterface::get_heap_head.
+     *
+     * @param hptr The element to free.
+     */
     virtual void free(t_heap* hptr) = 0;
 
-    // Initializes heap storage based on the size of the device.
-    //
-    // Note: this method **must** be invoked at least once prior to the
-    // following methods being called:
-    //  - add_to_heap
-    //  - push_back
-    //  - get_heap_head
-    //  - is_empty_heap
-    //  - empty_heap
-    //  - build_heap
+    /**
+     * @brief Initializes heap storage based on the size of the device.
+     *
+     * @details
+     * Note: this method **must** be invoked at least once prior to the
+     * following methods being called:<BR>
+     *  - add_to_heap<BR>
+     *  - push_back<BR>
+     *  - get_heap_head<BR>
+     *  - is_empty_heap<BR>
+     *  - empty_heap<BR>
+     *  - build_heap<BR>
+     *
+     *  @param grid
+     */
     virtual void init_heap(const DeviceGrid& grid) = 0;
 
-    // Add t_heap to heap, preserving heap property.
-    //
-    // This transfers ownership of the t_heap object to HeapInterface from the
-    // called.
+    /**
+     * @brief Add t_heap to heap, preserving heap property.
+     *
+     * @details
+     * This transfers ownership of the t_heap object to HeapInterface from the
+     * called.
+     *
+     * @param hptr The element to add.
+     */
     virtual void add_to_heap(t_heap* hptr) = 0;
 
-    // Add t_heap to heap, however does not preserve heap property.
-    //
-    // This is useful if multiple t_heap's are being added in bulk.  Once
-    // all t_heap's have been added, HeapInterface::build_heap can be invoked
-    // to restore the heap property in an efficient way.
-    //
-    // This transfers ownership of the t_heap object to HeapInterface from the
-    // called.
+    /**
+     * @brief Add t_heap to heap, however does not preserve heap property.
+     *
+     * @details
+     * This is useful if multiple t_heap's are being added in bulk. Once
+     * all t_heap's have been added, HeapInterface::build_heap can be invoked
+     * to restore the heap property in an efficient way.<BR><BR>
+     * This transfers ownership of the t_heap object to HeapInterface from the
+     * called.
+     *
+     * @param hptr The element to insert.
+     */
     virtual void push_back(t_heap* const hptr) = 0;
 
-    // Restore the heap property.
-    //
-    // This is useful in conjunction with HeapInterface::push_back when adding
-    // multiple heap elements.
+    /**
+     * @brief Restore the heap property.
+     *
+     * @details
+     * This is useful in conjunction with HeapInterface::push_back when adding
+     * multiple heap elements.
+     */
     virtual void build_heap() = 0;
 
-    // Pop the head (smallest element) of the heap, and return it.
-    //
-    // This transfers ownership of the t_heap object from HeapInterface to the
-    // caller.
+    /**
+     * @brief Pop the head (smallest element) of the heap, and return it.
+     *
+     * @details
+     * This transfers ownership of the t_heap object from HeapInterface to the
+     * caller.
+     */
     virtual t_heap* get_heap_head() = 0;
 
-    // Is the heap empty?
+    /**
+     * @brief Is the heap empty?
+     */
     virtual bool is_empty_heap() const = 0;
 
-    // Is the heap valid?
+    /**
+     * @brief Is the heap valid?
+     */
     virtual bool is_valid() const = 0;
 
-    // Empty all items from the heap.
+    /**
+     * @brief Empty all items from the heap.
+     */
     virtual void empty_heap() = 0;
 
-    // Free all storage used by the heap.
-    //
-    // This returns all memory allocated by the HeapInterface instance. Only
-    // call this if the heap is no longer being used.
-    //
-    // Note: Only invoke this method if all objects returned from this
-    // HeapInterface instace have been free'd.
+    /**
+     * @brief Free all storage used by the heap.
+     *
+     * @details
+     * This returns all memory allocated by the HeapInterface instance. Only
+     * call this if the heap is no longer being used.<BR><BR>
+     * Note: Only invoke this method if all objects returned from this
+     * HeapInterface instance have been free'd.
+     */
     virtual void free_all_memory() = 0;
 
-    // Set maximum number of elements that the heap should contain
-    // (the prune_limit).  If the prune limit is hit, then the heap should
-    // kick out duplicate index entries.
-    //
-    // The prune limit exists to provide a maximum bound on memory usage in
-    // the heap.  In some pathological cases, the router may explore
-    // incrementally better paths, resulting in many duplicate entries for
-    // RR nodes.  To handle this edge case, if the number of heap items
-    // exceeds the prune_limit, then the heap will compacts itself.
-    //
-    // The heap compaction process simply means taking the lowest cost entry
-    // for each index (e.g. RR node).  All nodes with higher costs can safely
-    // be dropped.
-    //
-    // The pruning process is intended to bound the memory usage the heap can
-    // consume based on the prune_limit, which is expected to be a function of
-    // the graph size.
-    //
-    // max_index should be the highest index possible in the heap.
-    // prune_limit is the maximuming number of heap entries before pruning
-    // should take place.
-    //
-    // The prune_limit should always be higher than max_index, likely by a
-    // significant amount.  The pruning process has some overhead, so
-    // prune_limit should be ~2-4x the max_index to prevent excess pruning
-    // when not required.
+    /**
+     * @brief Set maximum number of elements that the heap should contain
+     * (the prune_limit). If the prune limit is hit, then the heap should
+     * kick out duplicate index entries.
+     *
+     * @details
+     * The prune limit exists to provide a maximum bound on memory usage in
+     * the heap. In some pathological cases, the router may explore
+     * incrementally better paths, resulting in many duplicate entries for
+     * RR nodes. To handle this edge case, if the number of heap items
+     * exceeds the prune_limit, then the heap will compacts itself.<BR><BR>
+     * The heap compaction process simply means taking the lowest cost entry
+     * for each index (e.g. RR node).  All nodes with higher costs can safely
+     * be dropped.<BR><BR>
+     * The pruning process is intended to bound the memory usage the heap can
+     * consume based on the prune_limit, which is expected to be a function of
+     * the graph size.
+     *
+     * @param max_index The highest index possible in the heap.
+     * @param prune_limit The maximum number of heap entries before pruning should
+     * take place. This should alwasy be higher than max_index, likely by a
+     * significant amount. The pruning process has some overhead, so prune_limit
+     * should be ~2-4x the max_index to prevent excess pruning when not required.
+     */
     virtual void set_prune_limit(size_t max_index, size_t prune_limit) = 0;
 };
 

vpr/src/route/k_ary_heap.cpp

@@ -60,7 +60,7 @@ void KAryHeap::empty_heap() {
 size_t KAryHeap::size() const { return heap_tail_ - 1; } // heap[0] is not valid element
 
 // runs in O(n) time by sifting down; the least work is done on the most elements: 1 swap for bottom layer, 2 swap for 2nd, ... lgn swap for top
-// 1*(n/2) + 2*(n/4) + 3*(n/8) + ... + lgn*1 = 2n (sum of i/2^i)
+// 1*(n/k^1) + 2*(n/k^2) + 3*(n/k^3) + ... + lgn*1 = k*n (sum of i/k^i)
 void KAryHeap::build_heap() {
     for (size_t i = parent(heap_tail_); i != 0; --i)
         sift_down(i);
@@ -74,7 +74,6 @@ void KAryHeap::set_prune_limit(size_t max_index, size_t prune_limit) {
     prune_limit_ = prune_limit;
 }
 
-// O(lgn) sifting up to maintain heap property after insertion (should sift down when building heap)
 void KAryHeap::sift_up(size_t leaf, heap_elem const& node) {
     while ((leaf > 1) && (node.cost < heap_[parent(leaf)].cost)) {
         // sift hole up
@@ -85,7 +84,6 @@ void KAryHeap::sift_up(size_t leaf, heap_elem const& node) {
     heap_[leaf] = node;
 }
 
-//expands heap by "realloc"
 void KAryHeap::expand_heap_if_full() {
     if (heap_tail_ >= heap_size_) { /* Heap is full */
         heap_size_ *= 2;

vpr/src/route/k_ary_heap.h

@@ -4,6 +4,16 @@
 #include "heap_type.h"
 #include <vector>
 
+/**
+ * @brief Abstract class whose children are HeapInterface implementations of a k-ary minheap.
+ *
+ * @details
+ * Currently, KAryHeap's two children are BinaryHeap and FourAryHeap. On small circuits, these
+ * heaps have negligible differences in runtime, but on larger heaps, runtime is lower when
+ * using FourAryHeap. On titan benchmarks, the runtime is ~1.8% better on FourAryHeap compared
+ * to BinaryHeap. This is likely because FourAryHeap is more cache friendly, as we can fit 5
+ * heap_elem on a cache line.
+ */
 class KAryHeap : public HeapInterface {
   public:
     KAryHeap();
@@ -25,23 +35,86 @@ class KAryHeap : public HeapInterface {
     virtual t_heap* get_heap_head() = 0;
 
   protected:
+    /**
+     * @brief The struct which the heap_ vector contains.
+     *
+     * @details
+     * Previously, heap_ was made of only t_heap pointers. This meant that
+     * all comparisons required dereferencing to attain the element's cost.
+     * Now, the cost is attained by dereferencing only once in add_to_heap().
+     * This resulted in a slightly larger memory footprint but a ~1.4% runtime
+     * improvement.
+     *
+     * @param elem_ptr A pointer to the t_heap struct which contains all
+     * the node's information.
+     * @param cost The cost of the node.
+     */
+    /* TODO: We are currently storing the node cost in two places (in elem_ptr->cost and cost). This might be fixed in two ways:
+     * 1. Don't store the cost in t_heap.
+     * 2. Instead of using pointers, use a 32-bit ID. If we do this, we can create a new 8-ary heap, which is likely to be even
+     * faster as we can fit more heap_elem on one cache line (currently, we can fit 5 as heap_elem is 12 bytes), even with more
+     * comparisons.*/
     struct heap_elem {
         t_heap* elem_ptr;
         float cost;
     };
 
+    /**
+     * @return The number of elements in the heap.
+     */
     size_t size() const;
+
+    /**
+     * @brief Sift node up until it satisfies minheap property.
+     *
+     * @details
+     * O(lgn) sifting up to maintain heap property after insertion (should sift
+     * own when building heap)
+     *
+     * @param leaf The heap leaf where node currently resides.
+     * @param node The node to be sifted up.
+     */
     void sift_up(size_t leaf, heap_elem const& node);
+
+    /**
+     * @brief Expands heap by 2 times if it is full.
+     */
     void expand_heap_if_full();
+
+    /**
+     * @brief If the size of the heap is greater than the prune limit, prune the heap.
+     *
+     * @return Whether the heap was pruned.
+     */
     bool check_prune_limit();
+
+    /**
+     * @brief Prune the heap.
+     */
     void prune_heap();
 
+    /**
+     * @brief Make a heap rooted at index hole by **sifting down** in O(lgn) time
+     *
+     * @param hole
+     */
     virtual void sift_down(size_t hole) = 0;
+
+    /**
+     * @param i Heap child node.
+     *
+     * @return Heap parent node.
+     */
     virtual size_t parent(size_t i) const = 0;
 
     HeapStorage storage_;
 
-    /* heap_ is indexed from [1..heap_size] */
+    /**
+     * heap_ is indexed from [1..heap_size]; the 0th element is unused. For BinaryHeap, this simplifies
+     * arithmetic in left() and parent() functions. Using a heap beginning at index 0 would simplify
+     * leftmost_child() and parent() functions in FourAryHeap, but this does not improve runtime.
+     */
+    /* TODO: If an 8-ary heap is implemented, experiment with starting at index 0 */
     std::vector<heap_elem> heap_;
 
     size_t heap_size_; /* Number of slots in the heap array */