Generic intrusive linked list class.

This commit is the initial implementation of the intrusive linked list
class.  It includes the implementation in the header files, and unit
test.

The iterators are circular: incrementing end() gives begin() and
decrementing begin() gives end().  Also made it valid to
decrement end().

Expliticly defines move constructor and move assignment
- Visual Studio 2013 does not implicitly generate the move constructor or
  move assignments.  So they need to be explicit, otherwise it will try to
  use the copy constructor, which we explicitly deleted.
- Can't use "= default" either.
  Seems like VS2013 does not support explicitly using the default move
  constructors and move assignments, so I wrote them out.

source/util/ilist.h

@@ -0,0 +1,228 @@
+// Copyright (c) 2017 Google Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef LIBSPIRV_OPT_ILIST_H_
+#define LIBSPIRV_OPT_ILIST_H_
+
+#include <cassert>
+#include <type_traits>
+
+#include "ilist_node.h"
+
+namespace spvtools {
+namespace utils {
+
+// An IntrusiveList is a generic implementation of a doubly-linked list.  The
+// intended convention for using this container is:
+//
+//      class Node : public IntrusiveNodeBase<Node> {
+//        // Note that "Node", the class being defined is the template.
+//        // Must have a default constructor accessible to List.
+//        // Add whatever data is needed in the node
+//      };
+//
+//      using List = IntrusiveList<Node>;
+//
+// You can also inherit from IntrusiveList instead of a typedef if you want to
+// add more functionality.
+//
+// The condition on the template for IntrusiveNodeBase is there to add some type
+// checking to the container.  The compiler will still allow inserting elements
+// of type IntrusiveNodeBase<Node>, but that would be an error. This assumption
+// allows NextNode and PreviousNode to return pointers to Node, and casting will
+// not be required by the user.
+
+template <class NodeType>
+class IntrusiveList {
+ public:
+  static_assert(
+      std::is_base_of<IntrusiveNodeBase<NodeType>, NodeType>::value,
+      "The type from the node must be derived from IntrusiveNodeBase, with "
+      "itself in the template.");
+
+  // Creates an empty list.
+  inline IntrusiveList();
+
+  // Moves the contents of the given list to the list being constructed.
+  IntrusiveList(IntrusiveList&&);
+
+  // Destorys the list.  Note that the elements of the list will not be deleted,
+  // but they will be removed from the list.
+  ~IntrusiveList();
+
+  // Moves all of the elements in the list on the RHS to the list on the LHS.
+  IntrusiveList& operator=(IntrusiveList&&);
+
+  // Basetype for iterators so an IntrusiveList can be traversed like STL
+  // containers.
+  template <class T>
+  class iterator_template {
+   public:
+    iterator_template(const iterator_template& i) : node_(i.node_) {}
+
+    iterator_template& operator++() {
+      node_ = node_->next_node_;
+      return *this;
+    }
+
+    iterator_template& operator--() {
+      node_ = node_->previous_node_;
+      return *this;
+    }
+
+    iterator_template& operator=(const iterator_template& i) {
+      node_ = i.node_;
+      return *this;
+    }
+
+    T& operator*() const { return *node_; }
+    T* operator->() const { return node_; }
+
+    friend inline bool operator==(const iterator_template& lhs,
+                                  const iterator_template& rhs) {
+      return lhs.node_ == rhs.node_;
+    }
+    friend inline bool operator!=(const iterator_template& lhs,
+                                  const iterator_template& rhs) {
+      return !(lhs == rhs);
+    }
+
+   private:
+    iterator_template() = delete;
+    inline iterator_template(T* node) { node_ = node; }
+    T* node_;
+
+    friend IntrusiveList;
+  };
+
+  using iterator = iterator_template<NodeType>;
+  using const_iterator = iterator_template<const NodeType>;
+
+  // Various types of iterators for the start (begin) and one past the end (end)
+  // of the list.
+  //
+  // Decrementing |end()| iterator will give and iterator pointing to the last
+  // element in the list, if one exists.
+  //
+  // Incrementing |end()| iterator will give |begin()|.
+  //
+  // Decrementing |begin()| will give |end()|.
+  //
+  // TODO: Not marking these functions as noexcept because Visual Studio 2013
+  // does not support it.  When we no longer care about that compiler, we should
+  // mark these as noexcept.
+  iterator begin();
+  iterator end();
+  const_iterator begin() const;
+  const_iterator end() const;
+  const_iterator cbegin() const;
+  const_iterator cend() const;
+
+  // Appends |node| to the end of the list.  If |node| is already in a list, it
+  // will be removed from that list first.
+  void push_back(NodeType* node);
+
+ private:
+  // Doing a deep copy of the list does not make sense if the list does not own
+  // the data.  It is not clear who will own the newly created data.  Making
+  // copies illegal for that reason.
+  IntrusiveList(const IntrusiveList&) = delete;
+  IntrusiveList& operator=(const IntrusiveList&) = delete;
+
+  // A special node used to represent both the start and end of the list,
+  // without being part of the list.
+  NodeType sentinel_;
+};
+
+// Implementation of IntrusiveList
+
+template <class NodeType>
+inline IntrusiveList<NodeType>::IntrusiveList() : sentinel_() {
+  sentinel_.next_node_ = &sentinel_;
+  sentinel_.previous_node_ = &sentinel_;
+  sentinel_.is_sentinel_ = true;
+}
+
+template <class NodeType>
+IntrusiveList<NodeType>::IntrusiveList(IntrusiveList&& list) {
+  this->sentinel_ = list.sentinel_;
+  this->sentinel_.next_node_->previous_node_ = &this->sentinel_;
+  this->sentinel_.previous_node_->next_node_ = &this->sentinel_;
+
+  list.sentinel_.next_node_ = &list.sentinel_;
+  list.sentinel_.previous_node_ = &list.sentinel_;
+}
+
+template <class NodeType>
+IntrusiveList<NodeType>::~IntrusiveList() {
+  for (auto i : *this) i.RemoveFromList();
+}
+
+template <class NodeType>
+IntrusiveList<NodeType>& IntrusiveList<NodeType>::operator=(
+    IntrusiveList<NodeType>&& list) {
+  this->sentinel_ = list.sentinel_;
+  this->sentinel_.next_node_->previous_node_ = &this->sentinel_;
+  this->sentinel_.previous_node_->next_node_ = &this->sentinel_;
+
+  list.sentinel_.next_node_ = &list.sentinel_;
+  list.sentinel_.previous_node_ = &list.sentinel_;
+  return *this;
+}
+
+template <class NodeType>
+inline typename IntrusiveList<NodeType>::iterator
+IntrusiveList<NodeType>::begin() {
+  return iterator(sentinel_.next_node_);
+}
+
+template <class NodeType>
+inline typename IntrusiveList<NodeType>::iterator
+IntrusiveList<NodeType>::end() {
+  return iterator(&sentinel_);
+}
+
+template <class NodeType>
+inline typename IntrusiveList<NodeType>::const_iterator
+IntrusiveList<NodeType>::begin() const {
+  return const_iterator(sentinel_.next_node_);
+}
+
+template <class NodeType>
+inline typename IntrusiveList<NodeType>::const_iterator
+IntrusiveList<NodeType>::end() const {
+  return const_iterator(&sentinel_);
+}
+
+template <class NodeType>
+inline typename IntrusiveList<NodeType>::const_iterator
+IntrusiveList<NodeType>::cbegin() const {
+  return const_iterator(sentinel_.next_node_);
+}
+
+template <class NodeType>
+inline typename IntrusiveList<NodeType>::const_iterator
+IntrusiveList<NodeType>::cend() const {
+  return const_iterator(&sentinel_);
+}
+
+template <class NodeType>
+void IntrusiveList<NodeType>::push_back(NodeType* node) {
+  node->InsertBefore(&sentinel_);
+}
+
+}  // namespace utils
+}  // namespace spvtools
+
+#endif  // LIBSPIRV_OPT_ILIST_H_

source/util/ilist_node.h

@@ -0,0 +1,135 @@
+// Copyright (c) 2017 Google Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef LIBSPIRV_OPT_ILIST_NODE_H_
+#define LIBSPIRV_OPT_ILIST_NODE_H_
+
+#include <cassert>
+
+namespace spvtools {
+namespace utils {
+
+template <class NodeType>
+class IntrusiveList;
+
+// IntrusiveNodeBase is the base class for nodes in an IntrusiveList.
+// See the comments in ilist.h on how to use the class.
+
+template <class NodeType>
+class IntrusiveNodeBase {
+ public:
+  // Creates a new node that is not in a list.
+  inline IntrusiveNodeBase();
+
+  // Returns the node that comes after the given node in the list, if one
+  // exists.  If the given node is not in a list or is at the end of the list,
+  // the return value is nullptr.
+  inline NodeType* NextNode() const;
+
+  // Returns the node that comes before the given node in the list, if one
+  // exists.  If the given node is not in a list or is at the start of the
+  // list, the return value is nullptr.
+  inline NodeType* PreviousNode() const;
+
+  // Inserts the given node immediately before |pos| in the list.
+  // If the given node is already in a list, it will first be removed
+  // from that list.
+  //
+  // It is assumed that the given node is of type NodeType.  It is an error if
+  // |pos| is not already in a list.
+  inline void InsertBefore(NodeType* pos);
+
+  // Inserts the given node immediately after |pos| in the list.
+  // If the given node is already in a list, it will first be removed
+  // from that list.
+  //
+  // It is assumed that the given node is of type NodeType.  It is an error if
+  // |pos| is not already in a list.
+  inline void InsertAfter(NodeType* pos);
+
+  // Removes the given node from the list.  It is assumed that the node is
+  // in a list.  Note that this does not free any storage related to the node.
+  inline void RemoveFromList();
+
+ private:
+  // The pointers to the next and previous nodes in the list.
+  // If the current node is not part of a list, then |next_node_| and
+  // |previous_node_| are equal to |nullptr|.
+  NodeType* next_node_;
+  NodeType* previous_node_;
+
+  // Only true for the sentinel node stored in the list itself.
+  bool is_sentinel_;
+
+  friend IntrusiveList<NodeType>;
+};
+
+// Implementation of IntrusiveNodeBase
+
+template <class NodeType>
+inline IntrusiveNodeBase<NodeType>::IntrusiveNodeBase()
+    : next_node_(nullptr), previous_node_(nullptr), is_sentinel_(false) {}
+
+template <class NodeType>
+inline NodeType* IntrusiveNodeBase<NodeType>::NextNode() const {
+  if (!next_node_->is_sentinel_) return next_node_;
+  return nullptr;
+}
+
+template <class NodeType>
+inline NodeType* IntrusiveNodeBase<NodeType>::PreviousNode() const {
+  if (!previous_node_->is_sentinel_) return previous_node_;
+  return nullptr;
+}
+
+template <class NodeType>
+inline void IntrusiveNodeBase<NodeType>::InsertBefore(NodeType* pos) {
+  assert(!this->is_sentinel_ && "Sentinel nodes cannot be moved around.");
+  assert(pos->previous_node_ != nullptr && "Pos should already be in a list.");
+  if (this->previous_node_ != nullptr) this->RemoveFromList();
+
+  this->next_node_ = pos;
+  this->previous_node_ = pos->previous_node_;
+  pos->previous_node_ = static_cast<NodeType*>(this);
+  this->previous_node_->next_node_ = static_cast<NodeType*>(this);
+}
+
+template <class NodeType>
+inline void IntrusiveNodeBase<NodeType>::InsertAfter(NodeType* pos) {
+  assert(!this->is_sentinel_ && "Sentinel nodes cannot be moved around.");
+  assert(pos->previous_node_ != nullptr && "Pos should already be in a list.");
+  if (this->previous_node_ != nullptr) this->RemoveFromList();
+
+  this->previous_node_ = pos;
+  this->next_node_ = pos->next_node_;
+  pos->next_node_ = static_cast<NodeType*>(this);
+  this->next_node_->previous_node_ = static_cast<NodeType*>(this);
+}
+
+template <class NodeType>
+inline void IntrusiveNodeBase<NodeType>::RemoveFromList() {
+  assert(!this->is_sentinel_ && "Sentinel nodes cannot be moved around.");
+  assert(this->next_node_ != nullptr && "Cannot remove a node from a list if it is not in a list.");
+  assert(this->previous_node_ != nullptr && "Cannot remove a node from a list if it is not in a list.");
+
+  this->next_node_->previous_node_ = this->previous_node_;
+  this->previous_node_->next_node_ = this->next_node_;
+  this->next_node_ = nullptr;
+  this->previous_node_ = nullptr;
+}
+
+}  // namespace utils
+}  // namespace spvtools
+
+#endif  // LIBSPIRV_OPT_ILIST_NODE_H_

test/CMakeLists.txt

@@ -183,4 +183,5 @@ add_subdirectory(comp)
 add_subdirectory(link)
 add_subdirectory(opt)
 add_subdirectory(stats)
+add_subdirectory(util)
 add_subdirectory(val)

test/util/CMakeLists.txt

@@ -0,0 +1,18 @@
+# Copyright (c) 2017 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+add_spvtools_unittest(TARGET util_intrusive_list
+  SRCS ilist_test.cpp
+  LIBS SPIRV-Tools-opt
+)

test/util/ilist_test.cpp

@@ -0,0 +1,267 @@
+// Copyright (c) 2017 Google Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <vector>
+
+#include "gmock/gmock.h"
+#include "gtest/gtest.h"
+
+#include "util/ilist.h"
+
+namespace {
+
+using ::testing::ElementsAre;
+using spvtools::utils::IntrusiveList;
+using spvtools::utils::IntrusiveNodeBase;
+using IListTest = ::testing::Test;
+
+class TestNode : public IntrusiveNodeBase<TestNode> {
+ public:
+  TestNode() : IntrusiveNodeBase<TestNode>() {}
+  int data;
+};
+
+class TestList : public IntrusiveList<TestNode> {
+ public:
+  TestList() = default;
+  TestList(TestList&& that) : IntrusiveList<TestNode>(std::move(that)) {}
+  TestList& operator=(TestList&& that) {
+    static_cast<IntrusiveList<TestNode>&>(*this) = static_cast<IntrusiveList<TestNode>&&>(that);
+    return *this;
+  }
+};
+
+// This test checks the push_back method, as well as using an iterator to
+// traverse the list from begin() to end().  This implicitly test the
+// PreviousNode and NextNode fucntions.
+TEST(IListTest, PushBack) {
+  TestList list;
+  TestNode nodes[10];
+  for (int i = 0; i < 10; i++) {
+    nodes[i].data = i;
+    list.push_back(&nodes[i]);
+  }
+
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_THAT(output, ElementsAre(0, 1, 2, 3, 4, 5, 6, 7, 8, 9));
+}
+
+// Returns a list containing the values 0 to n-1 using the first n elements of
+// nodes to build the list.
+TestList BuildList(TestNode nodes[], int n) {
+  TestList list;
+  for (int i = 0; i < n; i++) {
+    nodes[i].data = i;
+    list.push_back(&nodes[i]);
+  }
+  return list;
+}
+
+// Test decrementing begin()
+TEST(IListTest, DecrementingBegin) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 10);
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_EQ(--list.begin(), list.end());
+}
+
+// Test incrementing end()
+TEST(IListTest, IncrementingEnd1) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 10);
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_EQ((++list.end())->data, 0);
+}
+
+// Test incrementing end() should equal begin()
+TEST(IListTest, IncrementingEnd2) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 10);
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_EQ(++list.end(), list.begin());
+}
+
+// Test decrementing end()
+TEST(IListTest, DecrementingEnd) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 10);
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_EQ((--list.end())->data, 9);
+}
+
+// Test the move constructor for the list class.
+TEST(IListTest, MoveConstructor) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 10);
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_THAT(output, ElementsAre(0, 1, 2, 3, 4, 5, 6, 7, 8, 9));
+}
+
+// Using a const list so we can test the const_iterator.
+TEST(IListTest, ConstIterator) {
+  TestNode nodes[10];
+  const TestList list = BuildList(nodes, 10);
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_THAT(output, ElementsAre(0, 1, 2, 3, 4, 5, 6, 7, 8, 9));
+}
+
+// Uses the move assignement instead of the move constructor.
+TEST(IListTest, MoveAssignment) {
+  TestNode nodes[10];
+  TestList list;
+  list = BuildList(nodes, 10);
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_THAT(output, ElementsAre(0, 1, 2, 3, 4, 5, 6, 7, 8, 9));
+}
+
+// Test inserting a new element at the end of a list using the IntrusiveNodeBase
+// "InsertAfter" function.
+TEST(IListTest, InsertAfter1) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 5);
+
+  nodes[5].data = 5;
+  nodes[5].InsertAfter(&nodes[4]);
+
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_THAT(output, ElementsAre(0, 1, 2, 3, 4, 5));
+}
+
+// Test inserting a new element in the middle of a list using the IntrusiveNodeBase
+// "InsertAfter" function.
+TEST(IListTest, InsertAfter2) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 5);
+
+  nodes[5].data = 5;
+  nodes[5].InsertAfter(&nodes[2]);
+
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_THAT(output, ElementsAre(0, 1, 2, 5, 3, 4));
+}
+
+// Test moving an element already in the list in the middle of a list using the IntrusiveNodeBase
+// "InsertAfter" function.
+TEST(IListTest, MoveUsingInsertAfter1) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 6);
+
+  nodes[5].InsertAfter(&nodes[2]);
+
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_THAT(output, ElementsAre(0, 1, 2, 5, 3, 4));
+}
+
+// Move the element at the start of the list into the middle.
+TEST(IListTest, MoveUsingInsertAfter2) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 6);
+
+  nodes[0].InsertAfter(&nodes[2]);
+
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_THAT(output, ElementsAre(1, 2, 0, 3, 4, 5));
+}
+
+// Move an element in the middle of the list to the end.
+TEST(IListTest, MoveUsingInsertAfter3) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 6);
+
+  nodes[2].InsertAfter(&nodes[5]);
+
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_THAT(output, ElementsAre(0, 1, 3, 4, 5, 2));
+}
+
+// Removing an element from the middle of a list.
+TEST(IListTest, Remove1) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 6);
+
+  nodes[2].RemoveFromList();
+
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_THAT(output, ElementsAre(0, 1, 3, 4, 5));
+}
+
+// Removing an element from the beginning of the list.
+TEST(IListTest, Remove2) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 6);
+
+  nodes[0].RemoveFromList();
+
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_THAT(output, ElementsAre(1, 2, 3, 4, 5));
+}
+
+// Removing the last element of a list.
+TEST(IListTest, Remove3) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 6);
+
+  nodes[5].RemoveFromList();
+
+  std::vector<int> output;
+  for (auto i : list) output.push_back(i.data);
+
+  EXPECT_THAT(output, ElementsAre(0, 1, 2, 3, 4));
+}
+
+// Test that operator== and operator!= work properly for the iterator class.
+TEST(IListTest, IteratorEqual) {
+  TestNode nodes[10];
+  TestList list = BuildList(nodes, 6);
+
+  std::vector<int> output;
+  for( auto i = list.begin(); i != list.end(); ++i )
+    for( auto j = list.begin(); j != list.end(); ++j )
+      if (i == j)
+        output.push_back(i->data);
+
+  EXPECT_THAT(output, ElementsAre(0, 1, 2, 3, 4, 5));
+}
+
+}  // namespace