🎨 Let intrusive_list be instantiated with incomplete types

Problem:
- `intrusive_list` and `forward_intrusive_list` cannot be instantiated with
  incomplete types in C++20, because the constraints do not allow it. Since
  these lists use pointers, it's often useful to declare them using incomplete
  types. Assuming that the types are complete before actually using the list,
  this should be fine.

Solution:
- Add `complete` concept and `is_complete_v` variable template.
- Allow use of incomplete types to instantiate `intrusive_list` and
  `intrusive_forward_list`.

Author: elbeno

docs/concepts.adoc

@@ -46,6 +46,18 @@ auto generic_lambda = [] (auto i) { return i + 1; };
 static_assert(stdx::callable<decltype(generic_lambda)>);
 ----
 
+=== `complete`
+
+`complete` is a concept modelled by complete types.
+
+[source,cpp]
+----
+struct incomplete; // not yet defined, not complete
+
+static_assert(not stdx::complete<incomplete>);
+static_assert(stdx::complete<int>);
+----
+
 === `has_trait`
 
 `has_trait` is used to turn a type trait (standard or otherwise) into a concept.

docs/intrusive_forward_list.adoc

@@ -31,3 +31,7 @@ bool b = l.empty();
 `intrusive_forward_list` supports the same
 xref:intrusive_list.adoc#_node_validity_checking[node validation policy]
 arguments as `intrusive_list`.
+
+Like `intrusive_list`, `intrusive_forward_list` requires its node type to have a
+`next` pointer of the appropriate type. But it can also be instantiated with an
+incomplete type.

docs/intrusive_list.adoc

@@ -33,6 +33,12 @@ l.clear();
 bool b = l.empty();
 ----
 
+NOTE: An `intrusive_list` requires its node type to have `prev` and `next`
+pointers of the appropriate type, and this is enforced by concept constraints
+after C++20. However, an `intrusive_list` can also be instantiated with an
+incomplete type. Of course the type must be complete at the point of using the
+list.
+
 === Node validity checking
 
 An `intrusive_list` has a second template parameter which is whether to operate

docs/type_traits.adoc

@@ -68,6 +68,19 @@ auto y = stdx::apply_sequence<L3>([&] <auto... Vs> () { y += V; });
 NOTE: If the function iterates the pack by folding over `operator,` then
 xref:type_traits.adoc#_template_for_each[`template_for_each`] is probably what you want.
 
+=== `is_complete_v`
+
+`is_complete_v` is a variable template that is true for complete types and false
+for incomplete types.
+
+[source,cpp]
+----
+struct incomplete; // not yet defined, not complete
+
+static_assert(not stdx::is_complete_v<incomplete>);
+static_assert(stdx::is_complete_v<int>);
+----
+
 === `is_function_object_v`
 
 `is_function_object_v` is a variable template that detects whether a type is a

include/stdx/concepts.hpp

@@ -108,6 +108,8 @@ constexpr auto has_trait = TypeTrait<T>::value;
 
 template <typename T> constexpr auto structural = is_structural_v<T>;
 
+template <typename T> constexpr auto complete = is_complete_v<T>;
+
 #else
 
 // After C++20, we can define concepts that are lacking in the library
@@ -194,6 +196,9 @@ concept has_trait = TypeTrait<T>::value;
 template <typename T>
 concept structural = is_structural_v<T>;
 
+template <typename T>
+concept complete = is_complete_v<T>;
+
 #endif
 
 } // namespace v1
@@ -234,6 +239,9 @@ concept same_as_unqualified =
 template <typename T>
 concept structural = is_structural_v<T>;
 
+template <typename T>
+concept complete = is_complete_v<T>;
+
 template <typename T, typename... Us>
 constexpr auto same_any = (... or same_as<T, Us>);
 

include/stdx/detail/list_common.hpp

@@ -2,6 +2,7 @@
 
 #include <stdx/concepts.hpp>
 #include <stdx/panic.hpp>
+#include <stdx/type_traits.hpp>
 
 #include <type_traits>
 #include <utility>
@@ -23,13 +24,13 @@ concept base_double_linkable = base_single_linkable<T> and requires(T node) {
 } // namespace detail
 
 template <typename T>
-concept single_linkable = requires(T *node) {
+concept single_linkable = not complete<T> or requires(T *node) {
     requires detail::base_single_linkable<
         std::remove_cvref_t<decltype(node->next)>>;
 };
 
 template <typename T>
-concept double_linkable = requires(T *node) {
+concept double_linkable = not complete<T> or requires(T *node) {
     requires detail::base_double_linkable<
         std::remove_cvref_t<decltype(node->next)>>;
     requires detail::base_double_linkable<

include/stdx/type_traits.hpp

@@ -270,5 +270,10 @@ constexpr auto nth_v =
 #endif
 STDX_PRAGMA(diagnostic pop)
 #endif
+
+template <typename T, typename = void> constexpr auto is_complete_v = false;
+template <typename T>
+constexpr auto is_complete_v<T, detail::void_v<sizeof(T)>> = true;
+
 } // namespace v1
 } // namespace stdx

test/concepts.cpp

@@ -176,3 +176,9 @@ TEST_CASE("structural", "[type_traits]") {
     STATIC_REQUIRE(stdx::structural<int>);
     STATIC_REQUIRE(not stdx::structural<non_structural>);
 }
+
+TEST_CASE("complete", "[type_traits]") {
+    struct incomplete;
+    STATIC_REQUIRE(stdx::complete<int>);
+    STATIC_REQUIRE(not stdx::complete<incomplete>);
+}

test/intrusive_forward_list.cpp

@@ -111,7 +111,7 @@ TEST_CASE("begin", "[intrusive_forward_list]") {
     CHECK(std::cbegin(list)->value == 1);
 }
 
-TEST_CASE("front and back", "[intrusive_list]") {
+TEST_CASE("front and back", "[intrusive_forward_list]") {
     stdx::intrusive_forward_list<int_node> list{};
     int_node n1{1};
     int_node n2{2};
@@ -226,7 +226,8 @@ TEST_CASE("checked operation clears pointers on pop",
     CHECK(n1.next == nullptr);
 }
 
-TEST_CASE("checked operation clears pointers on clear", "[intrusive_list]") {
+TEST_CASE("checked operation clears pointers on clear",
+          "[intrusive_forward_list]") {
     stdx::intrusive_forward_list<int_node> list{};
     int_node n1{1};
     int_node n2{2};
@@ -265,7 +266,8 @@ struct injected_handler {
 template <> inline auto stdx::panic_handler<> = injected_handler{};
 
 #if __cplusplus >= 202002L
-TEST_CASE("checked panic when pushing populated node", "[intrusive_list]") {
+TEST_CASE("checked panic when pushing populated node",
+          "[intrusive_forward_list]") {
     stdx::intrusive_forward_list<int_node> list{};
     int_node n{5};
 
@@ -281,7 +283,8 @@ TEST_CASE("checked panic when pushing populated node", "[intrusive_list]") {
     CHECK(compile_time_calls == 1);
 }
 #else
-TEST_CASE("checked panic when pushing populated node", "[intrusive_list]") {
+TEST_CASE("checked panic when pushing populated node",
+          "[intrusive_forward_list]") {
     stdx::intrusive_forward_list<int_node> list{};
     int_node n{5};
 
@@ -298,7 +301,8 @@ TEST_CASE("checked panic when pushing populated node", "[intrusive_list]") {
 }
 #endif
 
-TEST_CASE("unchecked operation doesn't clear pointers", "[intrusive_list]") {
+TEST_CASE("unchecked operation doesn't clear pointers",
+          "[intrusive_forward_list]") {
     stdx::intrusive_forward_list<int_node, stdx::node_policy::unchecked> list{};
     int_node n1{1};
     int_node n2{2};
@@ -309,3 +313,18 @@ TEST_CASE("unchecked operation doesn't clear pointers", "[intrusive_list]") {
     CHECK(list.pop_front() == &n1);
     CHECK(n1.next == before);
 }
+
+TEST_CASE("intrusive_forward_list can be instantiated with incomplete types",
+          "[intrusive_forward_list]") {
+    struct incomplete_int_node;
+    stdx::intrusive_forward_list<incomplete_int_node> list{};
+
+    struct incomplete_int_node {
+        int value{};
+        incomplete_int_node *next{};
+    };
+
+    incomplete_int_node n1{1};
+    list.push_back(&n1);
+    CHECK(list.pop_front() == &n1);
+}

test/intrusive_list.cpp

@@ -517,3 +517,19 @@ TEST_CASE("insert use case", "[intrusive_list]") {
     ++it;
     CHECK(it == std::cend(list));
 }
+
+TEST_CASE("intrusive_list can be instantiated with incomplete types",
+          "[intrusive_list]") {
+    struct incomplete_int_node;
+    stdx::intrusive_list<incomplete_int_node> list{};
+
+    struct incomplete_int_node {
+        int value{};
+        incomplete_int_node *prev{};
+        incomplete_int_node *next{};
+    };
+
+    incomplete_int_node n1{1};
+    list.push_back(&n1);
+    CHECK(list.pop_front() == &n1);
+}