pw_allocator: Add multiple block implementations

Change-Id: Ibbaf19cd2d8debb9a4af29f0b1605e520e69fddd Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/264646 Commit-Queue: Aaron Green <[email protected]> Reviewed-by: Keir Mierle <[email protected]> Reviewed-by: Wyatt Hepler <[email protected]> Lint: Lint 🤖 <[email protected]>
google · Feb 21, 2025 · 61138fd · 61138fd
1 parent f432240
commit 61138fd
Show file tree

Hide file tree

Showing 25 changed files with 824 additions and 99 deletions.
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
@@ -173,6 +173,9 @@ _doxygen_input_files = [  # keep-sorted: start
   "$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/result.h",
+  "$dir_pw_allocator/block/public/pw_allocator/block/small_alignable_block.h",
+  "$dir_pw_allocator/block/public/pw_allocator/block/small_block.h",
+  "$dir_pw_allocator/block/public/pw_allocator/block/tiny_block.h",
   "$dir_pw_allocator/block/public/pw_allocator/block/with_layout.h",
   "$dir_pw_allocator/bucket/public/pw_allocator/bucket/base.h",
   "$dir_pw_allocator/bucket/public/pw_allocator/bucket/fast_sorted.h",

diff --git a/pw_allocator/BUILD.gn b/pw_allocator/BUILD.gn
@@ -451,7 +451,6 @@ pw_source_set("block_allocator_testing") {
   deps = [
     "$dir_pw_bytes:alignment",
     "$dir_pw_third_party/fuchsia:stdcompat",
-    "block:detailed_block",
     dir_pw_assert,
     dir_pw_status,
   ]
@@ -767,24 +766,39 @@ pw_size_diff("blocks_size_report") {
       base = "size_report:base"
       label = "DetailedBlock"
     },
+    {
+      target = "size_report:small_block_basic"
+      base = "size_report:base"
+      label = "SmallBlock"
+    },
+    {
+      target = "size_report:small_alignable_block"
+      base = "size_report:base"
+      label = "SmallAlignableBlock"
+    },
+    {
+      target = "size_report:tiny_block"
+      base = "size_report:base"
+      label = "TinyBlock"
+    },
   ]
 }
 
 pw_size_diff("hardening_size_report") {
   title = "Size impact of various levels of pw_allocator hardening"
   binaries = [
     {
-      target = "size_report:detailed_block_basic"
+      target = "size_report:small_block_basic"
       base = "size_report:base"
       label = "DetailedBlock with basic assertions enabled"
     },
     {
-      target = "size_report:detailed_block_robust"
+      target = "size_report:small_block_robust"
       base = "size_report:base"
       label = "DetailedBlock with robust assertions enabled"
     },
     {
-      target = "size_report:detailed_block_debug"
+      target = "size_report:small_block_debug"
       base = "size_report:base"
       label = "DetailedBlock with debug assertions enabled"
     },

diff --git a/pw_allocator/api.rst b/pw_allocator/api.rst
@@ -271,49 +271,49 @@ block to a derived type.
 
 .. TODO(b/378549332): Add a diagram of mix-in relationships.
 
-.. _module-pw_allocator-api-basic-block:
+.. _module-pw_allocator-api-basic_block:
 
 BasicBlock
 ----------
 .. doxygenclass:: pw::allocator::BasicBlock
    :members:
 
-.. _module-pw_allocator-api-contiguous-block:
+.. _module-pw_allocator-api-contiguous_block:
 
 ContiguousBlock
 ---------------
 .. doxygenclass:: pw::allocator::ContiguousBlock
    :members:
 
-.. _module-pw_allocator-api-allocatable-block:
+.. _module-pw_allocator-api-allocatable_block:
 
 AllocatableBlock
 ----------------
 .. doxygenclass:: pw::allocator::AllocatableBlock
    :members:
 
-.. _module-pw_allocator-api-alignable-block:
+.. _module-pw_allocator-api-alignable_block:
 
 AlignableBlock
 --------------
 .. doxygenclass:: pw::allocator::AlignableBlock
    :members:
 
-.. _module-pw_allocator-api-block-with-layout:
+.. _module-pw_allocator-api-block_with_layout:
 
 BlockWithLayout
 ---------------
 .. doxygenclass:: pw::allocator::BlockWithLayout
    :members:
 
-.. _module-pw_allocator-api-iterable-block:
+.. _module-pw_allocator-api-iterable_block:
 
 IterableBlock
 --------------------
 .. doxygenclass:: pw::allocator::IterableBlock
    :members:
 
-.. _module-pw_allocator-api-poisonable-block:
+.. _module-pw_allocator-api-poisonable_block:
 
 PoisonableBlock
 ---------------
@@ -334,6 +334,40 @@ Block implementations
 The following combine block mix-ins and provide both the methods they require as
 well as a concrete representation of the data those methods need.
 
+.. _module-pw_allocator-api-small_block:
+
+SmallBlock
+----------
+This implementation includes just enough mix-ins for fixed-alignment
+allocations.
+
+.. doxygenclass:: pw::allocator::SmallBlock
+   :members:
+
+.. _module-pw_allocator-api-small_alignable_block:
+
+SmallAlignableBlock
+-------------------
+This implementation includes just enough mix-ins for variable-alignment
+allocations.
+
+.. doxygenclass:: pw::allocator::SmallAlignableBlock
+   :members:
+
+.. _module-pw_allocator-api-tiny_block:
+
+TinyBlock
+---------
+This implementation is similar to :ref:`module-pw_allocator-api-small_block`,
+but packs its information into just 4 bytes of overhead per allocation. This
+constrains both its miniumum and maximum allocatable sizes, and incurs small
+code size and performance costs for packing and unpacking header information.
+
+.. doxygenclass:: pw::allocator::TinyBlock
+   :members:
+
+.. _module-pw_allocator-api-detailed_block:
+
 DetailedBlock
 -------------
 This implementation includes all block mix-ins. This makes it very flexible at

diff --git a/pw_allocator/block/BUILD.bazel b/pw_allocator/block/BUILD.bazel
@@ -30,6 +30,8 @@ cc_library(
     ],
 )
 
+# Block mixins
+
 cc_library(
     name = "alignable",
     hdrs = ["public/pw_allocator/block/alignable.h"],
@@ -121,6 +123,8 @@ cc_library(
     ],
 )
 
+# Block implementations
+
 cc_library(
     name = "detailed_block",
     hdrs = ["public/pw_allocator/block/detailed_block.h"],
@@ -141,6 +145,46 @@ cc_library(
     ],
 )
 
+cc_library(
+    name = "small_block_base",
+    hdrs = ["public/pw_allocator/block/small_block_base.h"],
+    strip_include_prefix = "public",
+    deps = [
+        ":allocatable",
+        ":basic",
+        ":contiguous",
+        ":iterable",
+        "//pw_allocator/bucket:fast_sorted",
+        "//pw_bytes",
+    ],
+)
+
+cc_library(
+    name = "small_block",
+    hdrs = ["public/pw_allocator/block/small_block.h"],
+    strip_include_prefix = "public",
+    deps = [":small_block_base"],
+)
+
+cc_library(
+    name = "small_alignable_block",
+    hdrs = ["public/pw_allocator/block/small_alignable_block.h"],
+    strip_include_prefix = "public",
+    deps = [
+        ":alignable",
+        ":small_block_base",
+    ],
+)
+
+cc_library(
+    name = "tiny_block",
+    hdrs = ["public/pw_allocator/block/tiny_block.h"],
+    strip_include_prefix = "public",
+    deps = [":small_block_base"],
+)
+
+# Testing
+
 cc_library(
     name = "testing",
     testonly = True,
@@ -176,12 +220,37 @@ pw_cc_test(
     deps = [
         ":detailed_block",
         ":testing",
-        "//pw_assert",
-        "//pw_bytes",
-        "//pw_bytes:alignment",
-        "//pw_span",
-        "//pw_status",
-        "//third_party/fuchsia:stdcompat",
+        "//pw_unit_test",
+    ],
+)
+
+pw_cc_test(
+    name = "small_block_test",
+    srcs = ["small_block_test.cc"],
+    deps = [
+        ":small_block",
+        ":testing",
+        "//pw_unit_test",
+    ],
+)
+
+pw_cc_test(
+    name = "small_alignable_block_test",
+    srcs = ["small_alignable_block_test.cc"],
+    deps = [
+        ":small_alignable_block",
+        ":testing",
+        "//pw_unit_test",
+    ],
+)
+
+pw_cc_test(
+    name = "tiny_block_test",
+    srcs = ["tiny_block_test.cc"],
+    deps = [
+        ":testing",
+        ":tiny_block",
+        "//pw_unit_test",
     ],
 )
 
@@ -196,6 +265,9 @@ filegroup(
         "public/pw_allocator/block/iterable.h",
         "public/pw_allocator/block/poisonable.h",
         "public/pw_allocator/block/result.h",
+        "public/pw_allocator/block/small_alignable_block.h",
+        "public/pw_allocator/block/small_block.h",
+        "public/pw_allocator/block/tiny_block.h",
         "public/pw_allocator/block/with_layout.h",
     ],
 )