Add an insertAtFront method to the list merger.

The existing insert method preserves insertion order, but the
atomic queue use case actually wants to *reverse* the natural
insertion order.

Author: rjmccall

include/swift/Basic/ListMerger.h

@@ -133,6 +133,99 @@ class ListMerger {
     setLastInsertionPoint(newNode, /*known last of equals*/ true);
   }
 
+  /// Add a single node to this merger's current list.
+  ///
+  /// The next reference of the node will be overwritten and does not
+  /// need to be meaningful.
+  ///
+  /// The relative order of nodes in the current list will not change,
+  /// and if there are nodes in the current list which compare equal
+  /// to the new node, it will be inserted *before* them.
+  ///
+  /// This is useful for the pattern where nodes are naturally encountered
+  /// in the opposite of their desired order in the final list and
+  /// need to be reversed.  It generally doesn't make any sense to mix
+  /// this with calls to insert or merge on the same merger.
+  void insertAtFront(Node newNode) {
+    assert(newNode && "inserting a null node");
+
+    auto insertBetween = [newNode, this](Node prev, Node next) {
+      if (prev) {
+        assert(NodeTraits::getNext(prev) == next);
+        assert(NodeTraits::compare(prev, newNode) < 0);
+        NodeTraits::setNext(prev, newNode);
+      } else {
+        assert(root == next);
+        root = newNode;
+      }
+
+      assert(!next || NodeTraits::compare(newNode, next) <= 0);
+      NodeTraits::setNext(newNode, next);
+      setLastInsertionPoint(prev, /*known last of equals*/ true);
+    };
+
+    Node prev = Node();
+    Node cur = root;
+
+    // If we have a previous insertion point, check for the presumed-common
+    // case that we're inserting something that should immediately follow it.
+    if (auto lastIP = lastInsertionPoint) {
+      lastIP = findLastOfEqualsFromLastIP(lastIP);
+
+      // Compare against the next node after lastIP, if it exists.
+      if (Node nextAfterLastIP = NodeTraits::getNext(lastIP)) {
+        int comparison = NodeTraits::compare(nextAfterLastIP, newNode);
+
+        // If the new node compares equal to the next node, insert here.
+        if (comparison == 0) {
+          insertBetween(lastIP, nextAfterLastIP);
+          return;
+        }
+
+        // If the new node should follow the next node, start scanning
+        // after it.
+        if (comparison < 0) {
+          prev = nextAfterLastIP;
+          cur = NodeTraits::getNext(nextAfterLastIP);
+        }
+
+        // Otherwise, we'll need to scan from the beginning.
+
+      // If there is no next node, compare against the previous.
+      } else {
+        int comparison = NodeTraits::compare(lastIP, newNode);
+
+        // If the new node should follow the last node, we can
+        // insert here.
+        if (comparison < 0) {
+          insertBetween(lastIP, Node());
+          return;
+        }
+
+        // Otherwise, we'll need to scan from the beginning.
+      }
+    }
+
+    assert(!prev || NodeTraits::compare(prev, newNode) < 0);
+
+    // Scan forward, looking for a node which the new node must be
+    // inserted prior to.
+    // Invariant: prev < newNode, if prev exists
+    while (cur) {
+      // Compare the new node against the current IP.
+      int comparison = NodeTraits::compare(cur, newNode);
+
+      // If the new node isn't strictly greater than cur, insert here.
+      if (comparison >= 0) break;
+
+      // Otherwise, continue.
+      prev = cur;
+      cur = NodeTraits::getNext(prev);
+    }
+
+    insertBetween(prev, cur);
+  }
+
   /// Add a sorted list of nodes to this merger's current list.
   /// The list must be well-formed (i.e. appropriately terminated).
   ///

utils/test-list-merger/TestListMerger.cpp

@@ -12,12 +12,53 @@ static int compare_unsigned(unsigned lhs, unsigned rhs) {
 }
 
 namespace {
+enum EntryOrder {
+  creationOrder,
+  reverseCreationOrder
+};
+
 struct Entry {
   unsigned id;
   unsigned value;
   Entry *next;
 };
 
+class EntryFactory {
+  std::vector<std::unique_ptr<Entry>> entries;
+  unsigned nextID = 0;
+public:
+  Entry *create(unsigned value) {
+    auto entry = new Entry{nextID++, value, nullptr};
+    entries.emplace_back(entry);
+    return entry;
+  }
+
+  /// Sort the entries in this list.
+  ///
+  /// \param reverseCreationOrder - if true, then order equal-value
+  ///   nodes in the reverse of creation order; otherwise
+  ///   creator order of creation order
+  void sort(EntryOrder order) {
+    std::sort(entries.begin(), entries.end(),
+              [=](const std::unique_ptr<Entry> &lhs,
+                  const std::unique_ptr<Entry> &rhs) {
+      if (lhs->value != rhs->value) return lhs->value < rhs->value;
+      return order == creationOrder
+               ? lhs->id < rhs->id
+               : lhs->id > rhs->id;
+    });
+  }
+
+  void checkSameAs(Entry *list) {
+    for (auto &entry: entries) {
+      std::cout << "  " << list->value << " (" << list->id << ")\n";
+      assert(list == entry.get());
+      list = list->next;
+    };
+    assert(list == nullptr);
+  }
+};
+
 struct EntryListTraits {
   static Entry *getNext(Entry *e) { return e->next; }
   static void setNext(Entry *e, Entry *next) { e->next = next; }
@@ -26,6 +67,8 @@ struct EntryListTraits {
   }
 };
 
+using EntryListMerger = ListMerger<Entry*, EntryListTraits>;
+
 enum Op {
   insert,
   beginMerge,
@@ -54,12 +97,12 @@ struct Instruction {
 
 template <class T>
 static std::ostream &operator<<(std::ostream &str, llvm::ArrayRef<T> list) {
-  str << "[";
+  str << "{";
   for (auto b = list.begin(), i = b, e = list.end(); i != e; ++i) {
     if (i != b) str << ", ";
     str << *i;
   }
-  str << "]";
+  str << "}";
   return str;
 }
 
@@ -68,12 +111,9 @@ static std::ostream &operator<<(std::ostream &str, const std::vector<T> &list) {
   return (str << llvm::makeArrayRef(list));
 }
 
-static void runTest(llvm::ArrayRef<Instruction> values) {
-  std::vector<std::unique_ptr<Entry>> entries;
-
-  ListMerger<Entry*, EntryListTraits> merger;
-
-  unsigned nextID = 0;
+static void runInsertAndMergeTest(llvm::ArrayRef<Instruction> values) {
+  EntryFactory entries;
+  EntryListMerger merger;
 
   // Between beginMerge and endMerge instructions, values don't get
   // inserted immediately: they build up into a separate list of items
@@ -86,8 +126,7 @@ static void runTest(llvm::ArrayRef<Instruction> values) {
     switch (inst.op) {
     case insert: {
       // Create the new entry.
-      Entry *entry = new Entry{nextID++, inst.value, nullptr};
-      entries.emplace_back(entry);
+      Entry *entry = entries.create(inst.value);
 
       // If we're building a merge list, append to the end of it.
       if (lastMergeEntry) {
@@ -121,38 +160,48 @@ static void runTest(llvm::ArrayRef<Instruction> values) {
   }
   assert(!lastMergeEntry && "ended while still building a merge list");
 
-  // Do a stable sort of the entries.
-  std::stable_sort(entries.begin(), entries.end(),
-                   [](const std::unique_ptr<Entry> &lhs,
-                      const std::unique_ptr<Entry> &rhs) {
-                     return (lhs->value < rhs->value);
-                   });
-
-  // Make sure that we end up with the same list.
-  auto list = merger.release();
-  for (auto &entry : entries) {
-    std::cout << "  " << list->value << " (" << list->id << ")\n";
-    assert(list == entry.get());
-    list = list->next;
+  entries.sort(creationOrder);
+  entries.checkSameAs(merger.release());
+}
+
+static void runInsertAtFrontTest(llvm::ArrayRef<unsigned> values) {
+  EntryFactory entries;
+  EntryListMerger merger;
+  for (auto value: values) {
+    merger.insertAtFront(entries.create(value));
   }
-  assert(list == nullptr);
+  entries.sort(reverseCreationOrder);
+  entries.checkSameAs(merger.release());
 }
 
-int main() {
-  runTest({ 5, 0, 3, 0, 1, 0, 7 });
+static void runConcreteTests() {
+  runInsertAndMergeTest({ 5, 0, 3, 0, 1, 0, 7 });
+}
 
+namespace {
+struct TestConfig {
+  unsigned numTests;
+  unsigned numEntries;
+  unsigned maxValue;
+};
+
+}
+
+static void runInsertAndMergeTests(const TestConfig &config) {
   std::random_device randomDevice;
   std::default_random_engine e(randomDevice());
-  std::uniform_int_distribution<unsigned> dist(0, 20);
+  std::uniform_int_distribution<unsigned> valueDist(0, config.maxValue);
+  // Chance of entering or exiting a merge.
+  std::uniform_int_distribution<unsigned> mergeDist(0, 20);
 
   std::vector<Instruction> ins;
-  for (unsigned testN = 0; testN < 1000; ++testN) {
+  for (unsigned testN = 0; testN < config.numTests; ++testN) {
     ins.clear();
 
     const size_t noMerge = -1;
     size_t mergeStart = noMerge;
-    for (unsigned i = 0; i < 2000 || mergeStart != noMerge; ++i) {
-      if (dist(e) == 0) {
+    for (unsigned i = 0; i < config.numEntries || mergeStart != noMerge; ++i) {
+      if (mergeDist(e) == 0) {
         if (mergeStart != noMerge) {
           std::sort(ins.begin() + mergeStart, ins.end(),
                     [](const Instruction &lhs, const Instruction &rhs) {
@@ -165,11 +214,39 @@ int main() {
           mergeStart = ins.size();
         }
       } else {
-        ins.push_back(dist(e));
+        ins.push_back(valueDist(e));
       }
     }
 
-    std::cout << ins << std::endl;
-    runTest(ins);
+    std::cout << "runInsertAndMergeTest(" << ins << ");" << std::endl;
+    runInsertAndMergeTest(ins);
+  }
+}
+
+static void runInsertAtFrontTests(const TestConfig &config) {
+  std::random_device randomDevice;
+  std::default_random_engine e(randomDevice());
+  std::uniform_int_distribution<unsigned> valueDist(0, config.maxValue);
+
+  std::vector<unsigned> ins;
+  for (unsigned testN = 0; testN < config.numTests; ++testN) {
+    ins.clear();
+    for (unsigned i = 0; i < config.numEntries; ++i) {
+      ins.push_back(valueDist(e));
+    }
+
+    std::cout << "runInsertAtFrontTest(" << ins << ");" << std::endl;
+    runInsertAtFrontTest(ins);
   }
 }
+
+int main() {
+  TestConfig config = {
+    .numTests = 1000,
+    .numEntries = 2000,
+    .maxValue = 3
+  };
+  runConcreteTests();
+  runInsertAndMergeTests(config);
+  runInsertAtFrontTests(config);
+}