pw_allocator: Add static polymorphism to Block

Different consumers have different priorities when it comes to
pw_allocator, which is reflected in different feature requests for its
central class, Block. For example, some have requested better debug info
during development by associating call site metadata, while others have
asked for the smallest possible overhead.

To be able to accommodate multiple use cases, the Block class needs to
become polymorphic. Given its central role, however, it must over the
overhead of vtables and dynamic dispatch. This CL accomplishes this by
decomposing Block into several largely orthognal "mix-in" types that
each use the CRTP:

 - BasicBlock describes how blocks are made of usable space with
   overhead.
 - ContiguousBlock describes how blocks can be split and merged.
 - Forward- and ReverseIterableBlock describe how to traverse from on
   block to its neighbors.
 - AllocatableBlock describes how blocks can be allocated and freed.
 - AlignableBlock describes how allocations can be constrained so that
   usable space falls on an alignment boundary.
 - PoisonableBlock describes how to detect use-after-frees by checking
   the usable space of free blocks.
 - BlockWithLayout describes how to retrieve the memory layout
   originally used to allocated an in-use block.

Each mix-in is stateless, and concrete implementations can inherit from
several or all of them. In the scope of this CL, they are used to
create `DetailedBlock`, which matches the existing legacy block.

Change-Id: Id07d9c98299da8c12adeca83b603ad9fdebb7844
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/232214
Reviewed-by: Wyatt Hepler <[email protected]>
Pigweed-Auto-Submit: Aaron Green <[email protected]>
Reviewed-by: Taylor Cramer <[email protected]>
Commit-Queue: Aaron Green <[email protected]>
Lint: Lint 🤖 <[email protected]>

docs/BUILD.gn

@@ -154,10 +154,17 @@ group("third_party_docs") {
 # All sources with doxygen comment blocks.
 _doxygen_input_files = [  # keep-sorted: start
   "$dir_pw_alignment/public/pw_alignment/alignment.h",
+  "$dir_pw_allocator/block/public/pw_allocator/block/alignable.h",
+  "$dir_pw_allocator/block/public/pw_allocator/block/allocatable.h",
+  "$dir_pw_allocator/block/public/pw_allocator/block/basic.h",
+  "$dir_pw_allocator/block/public/pw_allocator/block/contiguous.h",
+  "$dir_pw_allocator/block/public/pw_allocator/block/detailed_block.h",
+  "$dir_pw_allocator/block/public/pw_allocator/block/iterable.h",
+  "$dir_pw_allocator/block/public/pw_allocator/block/poisonable.h",
+  "$dir_pw_allocator/block/public/pw_allocator/block/with_layout.h",
   "$dir_pw_allocator/public/pw_allocator/allocator.h",
   "$dir_pw_allocator/public/pw_allocator/allocator_as_pool.h",
   "$dir_pw_allocator/public/pw_allocator/best_fit_block_allocator.h",
-  "$dir_pw_allocator/public/pw_allocator/block.h",
   "$dir_pw_allocator/public/pw_allocator/block_allocator.h",
   "$dir_pw_allocator/public/pw_allocator/bucket.h",
   "$dir_pw_allocator/public/pw_allocator/bucket_allocator.h",

pw_allocator/BUILD.bazel

@@ -83,33 +83,15 @@ cc_library(
     ],
 )
 
-cc_library(
-    name = "block",
-    srcs = ["block.cc"],
-    hdrs = [
-        "public/pw_allocator/block.h",
-    ],
-    strip_include_prefix = "public",
-    deps = [
-        ":allocator",
-        ":buffer",
-        "//pw_assert",
-        "//pw_bytes",
-        "//pw_bytes:alignment",
-        "//pw_result",
-        "//pw_status",
-    ],
-)
-
 cc_library(
     name = "block_allocator",
     srcs = ["block_allocator.cc"],
     hdrs = ["public/pw_allocator/block_allocator.h"],
     strip_include_prefix = "public",
     deps = [
         ":allocator",
-        ":block",
         ":fragmentation",
+        "//pw_allocator/block:detailed_block",
         "//pw_assert",
         "//pw_bytes:alignment",
         "//pw_result",
@@ -130,6 +112,7 @@ cc_library(
         "//pw_assert",
         "//pw_function",
         "//pw_span",
+        "//third_party/fuchsia:stdcompat",
     ],
 )
 
@@ -161,16 +144,19 @@ cc_library(
     hdrs = [
         "public/pw_allocator/buddy_allocator.h",
     ],
+    implementation_deps = [
+        ":buffer",
+        "//pw_assert",
+        "//pw_bytes:alignment",
+        "//third_party/fuchsia:stdcompat",
+    ],
     strip_include_prefix = "public",
     deps = [
         ":allocator",
         ":bucket",
-        ":buffer",
-        "//pw_alignment",
-        "//pw_assert",
         "//pw_bytes",
-        "//pw_bytes:alignment",
         "//pw_containers:vector",
+        "//pw_status",
     ],
 )
 
@@ -213,13 +199,16 @@ cc_library(
     hdrs = [
         "public/pw_allocator/chunk_pool.h",
     ],
+    implementation_deps = [
+        ":buffer",
+        "//pw_assert",
+        "//pw_bytes:alignment",
+        "//third_party/fuchsia:stdcompat",
+    ],
     strip_include_prefix = "public",
     deps = [
-        ":buffer",
         ":pool",
-        "//pw_assert",
         "//pw_bytes",
-        "//pw_bytes:alignment",
         "//pw_result",
     ],
 )
@@ -296,8 +285,8 @@ cc_library(
     ],
     strip_include_prefix = "public",
     deps = [
-        ":block",
         ":bucket_allocator",
+        "//pw_allocator/block:detailed_block",
         "//pw_assert",
         "//pw_bytes",
         "//pw_preprocessor",
@@ -356,7 +345,6 @@ cc_library(
 cc_library(
     name = "pool",
     hdrs = ["public/pw_allocator/pool.h"],
-    includes = [":default_config"],
     strip_include_prefix = "public",
     deps = [
         ":deallocator",
@@ -427,11 +415,11 @@ cc_library(
     strip_include_prefix = "public",
     deps = [
         ":allocator",
-        ":block",
         ":buffer",
         ":first_fit_block_allocator",
         ":test_config",
         ":tracking_allocator",
+        "//pw_allocator/block:detailed_block",
         "//pw_assert",
         "//pw_bytes",
         "//pw_result",
@@ -441,23 +429,6 @@ cc_library(
     ],
 )
 
-cc_library(
-    name = "block_testing",
-    testonly = True,
-    hdrs = [
-        "public/pw_allocator/block_testing.h",
-    ],
-    strip_include_prefix = "public",
-    deps = [
-        ":block",
-        ":testing",
-        "//pw_assert",
-        "//pw_bytes:alignment",
-        "//pw_status",
-        "//third_party/fuchsia:stdcompat",
-    ],
-)
-
 cc_library(
     name = "block_allocator_testing",
     testonly = True,
@@ -467,13 +438,16 @@ cc_library(
     hdrs = [
         "public/pw_allocator/block_allocator_testing.h",
     ],
-    strip_include_prefix = "public",
-    deps = [
-        ":block_allocator",
-        ":block_testing",
+    implementation_deps = [
         "//pw_assert",
         "//pw_bytes:alignment",
         "//pw_status",
+        "//third_party/fuchsia:stdcompat",
+    ],
+    strip_include_prefix = "public",
+    deps = [
+        ":block_allocator",
+        "//pw_allocator/block:testing",
         "//pw_unit_test",
     ],
 )
@@ -549,18 +523,6 @@ pw_cc_test(
     ],
 )
 
-pw_cc_test(
-    name = "block_test",
-    srcs = [
-        "block_test.cc",
-    ],
-    deps = [
-        ":block_testing",
-        "//pw_span",
-        "//pw_unit_test",
-    ],
-)
-
 pw_cc_test(
     name = "bucket_allocator_test",
     srcs = ["bucket_allocator_test.cc"],
@@ -593,6 +555,7 @@ pw_cc_test(
         ":testing",
         "//pw_bytes",
         "//pw_result",
+        "//third_party/fuchsia:stdcompat",
     ],
 )
 
@@ -605,6 +568,7 @@ pw_cc_test(
         ":bump_allocator",
         ":testing",
         "//pw_unit_test",
+        "//third_party/fuchsia:stdcompat",
     ],
 )
 
@@ -650,6 +614,7 @@ pw_cc_test(
         ":buffer",
         ":first_fit_block_allocator",
         "//pw_unit_test",
+        "//third_party/fuchsia:stdcompat",
     ],
 )
 
@@ -669,10 +634,11 @@ pw_cc_test(
         "freelist_heap_test.cc",
     ],
     deps = [
-        ":block_testing",
         ":freelist_heap",
         ":testing",
+        "//pw_allocator/block:testing",
         "//pw_bytes:alignment",
+        "//third_party/fuchsia:stdcompat",
     ],
 )