[NFC] Add a utility for handling sorted linked lists

We'll be using this in the default actor implementation.

Author: rjmccall

include/swift/Basic/ListMerger.h

@@ -0,0 +1,290 @@
+//===--- ListMerger.h - Merging sorted linked lists -------------*- C++ -*-===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2017 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+//
+// This file defines a class that helps with maintaining and merging a
+// sorted linked list.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef SWIFT_BASIC_LISTMERGER_H
+#define SWIFT_BASIC_LISTMERGER_H
+
+#include <assert.h>
+
+namespace swift {
+
+/// A class for building and merging sorted linked lists.
+///
+/// The `Node` type parameter represents a reference to a list node.
+/// Conceptually, a `Node` value is either null or a reference to an
+/// object with an abstract sort value and a `next` reference
+/// (another `Node` value).
+///
+/// A null reference can be created by explicitly default-constructing
+/// the `Node` type, e.g. with `Node()`.  Converting a `Node` value
+/// contextually to `bool` tests whether the node is a null reference.
+/// `Node` values can be compared with the `==` and `!=` operators,
+/// and equality with `Node()` is equivalent to a `bool` conversion.
+/// These conditions are designed to allow pointer types to be used
+/// directly, but they also permit other types.  `ListMerger` is not
+/// currently written to support smart pointer types efficiently,
+/// however.
+///
+/// The sort value and `next` reference are not accessed directly;
+/// instead, they are accessed with `static` functions on the
+/// `NodeTraits` type parameter:
+///
+/// ```
+///   /// Return the current value of the next reference.
+///   static Node getNext(Node n);
+///
+///   /// Set the current value of the next reference.
+///   static void setNext(Node n, Node next);
+///
+///   /// Compare the sort value of this node with that of another
+///   /// node, returning negative (<), zero (==), or positive (>).
+///   /// A node must compare equal to itself.  A sorted list obeys
+///   /// the condition that each node in the list compares <= the next.
+///   static int compare(Node lhs, Node rhs);
+/// ```
+///
+/// The merger holds a current list of nodes.  The sort value and
+/// next references of nodes must not be accessed after being added
+/// to the merger and before being released except by the merger.
+template <class Node, class NodeTraits>
+class ListMerger {
+  Node root;
+  Node lastInsertionPoint = Node();
+  bool lastInsertionPointIsKnownLastOfEquals = false;
+public:
+  /// Construct a merger with the given sorted list as its current list.
+  ListMerger(Node initialList = Node())
+    : root(initialList) {}
+
+  /// 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 after them.
+  void insert(Node newNode) {
+    assert(newNode && "inserting a null node");
+
+    Node prev = Node();
+    Node cur = root;
+    Node stopper = Node();
+
+    // If we have a previous insertion point, compare against it.
+    if (Node lastIP = lastInsertionPoint) {
+      int comparison = NodeTraits::compare(lastIP, newNode);
+
+      // If it compares equal, put the new node immediately after the
+      // last in the sequence of equals that contains it.  This is a
+      // common fast path when we're adding many nodes that compare equal.
+      if (comparison == 0) {
+        lastIP = findLastOfEqualsFromLastIP(lastIP);
+        NodeTraits::setNext(newNode, NodeTraits::getNext(lastIP));
+        NodeTraits::setNext(lastIP, newNode);
+        setLastInsertionPoint(newNode, /*known last of equals*/ true);
+        return;
+
+      // If the new node must follow the last insertion node, we can
+      // at least start the search there.
+      } else if (comparison < 0) {
+        lastIP = findLastOfEqualsFromLastIP(lastIP);
+        prev = lastIP;
+        cur = NodeTraits::getNext(lastIP);
+
+      // Otherwise, we can at least end the search at the last inserted
+      // node.
+      } else {
+        stopper = lastIP;
+      }
+    }
+
+    // Invariants:
+    //   root     == [ ..., prev, cur, ... ]
+    //   prev <= newRoot
+
+    // Scan forward looking for either `end` or a node that strictly
+    // follows the new node.
+    while (cur != stopper && NodeTraits::compare(cur, newNode) <= 0) {
+      prev = cur;
+      cur = NodeTraits::getNext(cur);
+    }
+
+    NodeTraits::setNext(newNode, cur);
+    if (prev) {
+      NodeTraits::setNext(prev, newNode);
+    } else {
+      root = newNode;
+    }
+    setLastInsertionPoint(newNode, /*known last of equals*/ true);
+  }
+
+  /// Add a sorted list of nodes to this merger's current list.
+  /// The list must be well-formed (i.e. appropriately terminated).
+  ///
+  /// The relative order of nodes in both the current and the new list
+  /// will not change.  If there are nodes in the current list which
+  /// compare equal to nodes in the new list, they will appear before
+  /// the new nodes.
+  ///
+  /// For example, if the current list is `[1@A, 1@B, 2@C]`, and the new
+  /// list is `[0@D, 1@E, 2@F]`, the current list after the merge will
+  /// be `[0@D, 1@A, 1@B, 1@E, 2@C, 2@F]`.
+  void merge(Node rootOfNewList) {
+    if (!rootOfNewList) return;
+
+    Node prev = Node();
+    Node cur = root;
+    Node stopper = Node();
+
+    // If we have a previous insertion point, compare the new root
+    // against it.
+    if (Node lastIP = lastInsertionPoint) {
+      int comparison = NodeTraits::compare(lastIP, rootOfNewList);
+
+      // If it compares equal, we've got an insertion point where
+      // we can place rootOfNewList: the end of the sequence of
+      // equals that includes lastIP.  This is a common fast path
+      // when we have many nodes that compare equal.
+      if (comparison == 0) {
+        lastIP = findLastOfEqualsFromLastIP(lastIP);
+        prev = lastIP;
+        cur = NodeTraits::getNext(lastIP);
+        goto foundInsertionPoint; // seems to be the best option
+
+      // If the new node must follow the last insertion point, we can
+      // at least start the search there.
+      } else if (comparison < 0) {
+        lastIP = findLastOfEqualsFromLastIP(lastIP);
+        prev = lastIP;
+        cur = NodeTraits::getNext(lastIP);
+
+      // Otherwise, we can end the initial search at that position.
+      } else {
+        stopper = lastIP;
+      }
+    }
+
+    while (rootOfNewList) {
+      // Invariants:
+      //   root == [ ..., prev, cur, ... ]
+      //   prev <= rootOfNewList
+
+      // Check if the position between prev and cur is where we should
+      // insert the root of the new list.
+      if (cur != stopper && NodeTraits::compare(cur, rootOfNewList) <= 0) {
+        prev = cur;
+        cur = NodeTraits::getNext(cur);
+        continue;
+      }
+
+      // Place rootOfNewList at this position.  Note that this might not be
+      // a proper splice because there may be nodes following prev that
+      // are now no longer reflected in the existing list.
+      if (!prev) {
+        root = rootOfNewList;
+      } else {
+      foundInsertionPoint:
+        NodeTraits::setNext(prev, rootOfNewList);
+      }
+
+      // If we've run out of nodes in the existing list, it *is*
+      // a proper splice, and we're done.
+      if (!cur) {
+        assert(!stopper);
+        setLastInsertionPoint(rootOfNewList, /*known end of equals*/ false);
+        return;
+      }
+
+      // If not, scan forward in the new list looking for a node that
+      // cur should precede.
+      Node prevInNewList = rootOfNewList;
+      Node curInNewList = NodeTraits::getNext(rootOfNewList);
+      while (curInNewList && NodeTraits::compare(cur, curInNewList) > 0) {
+        prevInNewList = curInNewList;
+        curInNewList = NodeTraits::getNext(curInNewList);
+      }
+
+      // prevInNewList < cur <= curInNewList (if it exists)
+
+      // Turn this:
+      //   root           == [ ..., prev, cur, ... ]
+      //   rootOfNewList  == [ ..., prevInNewList, curInNewList, ... ]
+      // into:
+      //   root           == [ ..., prev, rootOfNewList, ..., prevInNewList,
+      //                       cur, ... ]
+      //   rootOfNewList' == [ curInNewList, ... ]
+      //
+      // Note that the next insertion point we'll check is *after* cur,
+      // since we know that cur <= curInNewList.
+
+      NodeTraits::setNext(prevInNewList, cur);
+      rootOfNewList = curInNewList;
+      prev = cur;
+      cur = NodeTraits::getNext(cur);
+
+      setLastInsertionPoint(prevInNewList, /*known end of equals*/ true);
+
+      // Any stopper we have was only known to exceed the original root
+      // node of the new list, which we've now inserted.  From now on,
+      // we'll need to scan to the end of the list.
+      stopper = Node();
+    }
+  }
+
+  /// Get the current list that's been built up, and clear the internal
+  /// state of this merger.
+  Node release() {
+    Node result = root;
+    root = Node();
+    lastInsertionPoint = Node();
+    return result;
+  }
+
+private:
+  /// Set the last point at which we inserted a node, and specify
+  /// whether we know it was the last in its sequence of equals.
+  void setLastInsertionPoint(Node lastIP, bool knownEndOfEquals) {
+    lastInsertionPoint = lastIP;
+    lastInsertionPointIsKnownLastOfEquals = knownEndOfEquals;
+  }
+
+  /// Given the value of lastInsertionPoint (passed in to avoid
+  /// reloading it), find the last node in the sequence of equals that
+  /// contains it.
+  Node findLastOfEqualsFromLastIP(Node lastIP) const {
+    assert(lastIP == lastInsertionPoint);
+    if (!lastInsertionPointIsKnownLastOfEquals)
+      return findLastOfEquals(lastIP);
+    return lastIP;
+  }
+
+  /// Find the last node in the sequence of equals that contains `node`.
+  static Node findLastOfEquals(Node node) {
+    while (Node next = NodeTraits::getNext(node)) {
+      int comparison = NodeTraits::compare(node, next);
+      assert(comparison <= 0 && "list is out of order");
+      if (comparison < 0) break;
+      node = next;
+    }
+    return node;
+  }
+};
+
+} // end namespace swift
+
+#endif

utils/test-list-merger/Makefile

@@ -0,0 +1,13 @@
+SWIFT_SRCROOT=${CURDIR}/../..
+SRCROOT=${SWIFT_SRCROOT}/..
+LLVM_SRCROOT=${SRCROOT}/llvm/
+LLVM_OBJROOT=${SRCROOT}/build/Ninja-DebugAssert/llvm-macosx-x86_64
+
+HEADERS=${SWIFT_SRCROOT}/include/swift/Basic/ListMerger.h
+
+CXXFLAGS=-Wall -std=c++17 -stdlib=libc++ -D__STDC_LIMIT_MACROS -D__STDC_CONSTANT_MACROS -I${OBJROOT}/include -I${SWIFT_SRCROOT}/include -I${LLVM_SRCROOT}/include -I${LLVM_OBJROOT}/include
+
+TestListMerger: TestListMerger.o
+	$(CXX) -L${LLVM_OBJROOT}/lib -lLLVMSupport $< -o $@
+
+TestListMerger.o: ${HEADERS}