pw_allocator: Refactor Bucket

This CL adds flexibility to the Bucket class by making it statically
polymorphic, and adding subtypes such as CompactUnsortedBucket and
SortedBucket. The existing behavior is preserved with a LegacyBucket
subtype.

Change-Id: Ia505cba5186e8ba44b418468083e2cd2df0d8626
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/234815
Lint: Lint 🤖 <android-build-ayeaye@system.gserviceaccount.com>
Commit-Queue: Aaron Green <aarongreen@google.com>
Pigweed-Auto-Submit: Aaron Green <aarongreen@google.com>
Reviewed-by: Taylor Cramer <cramertj@google.com>

docs/BUILD.gn

@@ -163,11 +163,14 @@ _doxygen_input_files = [  # keep-sorted: start
   "$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/with_layout.h",
+  "$dir_pw_allocator/bucket/public/pw_allocator/bucket/fast_sorted.h",
+  "$dir_pw_allocator/bucket/public/pw_allocator/bucket/sequenced.h",
+  "$dir_pw_allocator/bucket/public/pw_allocator/bucket/sorted.h",
+  "$dir_pw_allocator/bucket/public/pw_allocator/bucket/unordered.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_allocator.h",
-  "$dir_pw_allocator/public/pw_allocator/bucket.h",
   "$dir_pw_allocator/public/pw_allocator/bucket_allocator.h",
   "$dir_pw_allocator/public/pw_allocator/buddy_allocator.h",
   "$dir_pw_allocator/public/pw_allocator/buffer.h",

pw_allocator/BUILD.bazel

@@ -107,23 +107,6 @@ cc_library(
     ],
 )
 
-cc_library(
-    name = "bucket",
-    srcs = [
-        "bucket.cc",
-    ],
-    hdrs = [
-        "public/pw_allocator/bucket.h",
-    ],
-    strip_include_prefix = "public",
-    deps = [
-        "//pw_assert",
-        "//pw_function",
-        "//pw_span",
-        "//third_party/fuchsia:stdcompat",
-    ],
-)
-
 cc_library(
     name = "bucket_allocator",
     hdrs = [
@@ -132,8 +115,8 @@ cc_library(
     strip_include_prefix = "public",
     deps = [
         ":block_allocator",
-        ":bucket",
         "//pw_allocator/block:detailed_block",
+        "//pw_allocator/bucket:unordered",
         "//pw_status",
     ],
 )
@@ -155,15 +138,15 @@ cc_library(
         "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",
+        "//pw_allocator/block:basic",
+        "//pw_allocator/bucket:unordered",
         "//pw_bytes",
         "//pw_containers:vector",
         "//pw_status",

pw_allocator/BUILD.gn

@@ -94,7 +94,6 @@ pw_source_set("block_allocator") {
   public = [ "public/pw_allocator/block_allocator.h" ]
   public_deps = [
     ":allocator",
-    ":bucket",
     ":fragmentation",
     "block:allocatable",
     "block:basic",
@@ -109,25 +108,13 @@ pw_source_set("block_allocator") {
   sources = [ "block_allocator.cc" ]
 }
 
-pw_source_set("bucket") {
-  public_configs = [ ":public_include_path" ]
-  public = [ "public/pw_allocator/bucket.h" ]
-  public_deps = [
-    "$dir_pw_third_party/fuchsia:stdcompat",
-    dir_pw_function,
-    dir_pw_span,
-  ]
-  deps = [ dir_pw_assert ]
-  sources = [ "bucket.cc" ]
-}
-
 pw_source_set("bucket_allocator") {
   public_configs = [ ":public_include_path" ]
   public = [ "public/pw_allocator/bucket_allocator.h" ]
   public_deps = [
     ":block_allocator",
-    ":bucket",
     "block:detailed_block",
+    "bucket:unordered",
     dir_pw_status,
   ]
 }
@@ -144,13 +131,13 @@ pw_source_set("buddy_allocator") {
   public = [ "public/pw_allocator/buddy_allocator.h" ]
   public_deps = [
     ":allocator",
-    ":bucket",
     "$dir_pw_containers:vector",
+    "block:basic",
+    "bucket:unordered",
     dir_pw_bytes,
     dir_pw_status,
   ]
   deps = [
-    ":buffer",
     "$dir_pw_bytes:alignment",
     "$dir_pw_third_party/fuchsia:stdcompat",
     dir_pw_assert,
@@ -655,6 +642,7 @@ pw_test_group("tests") {
   group_deps = [
     "benchmarks:tests",
     "block:tests",
+    "bucket:tests",
     "examples",
   ]
 }

pw_allocator/CMakeLists.txt

@@ -101,21 +101,6 @@ pw_add_library(pw_allocator.block_allocator STATIC
     block_allocator.cc
 )
 
-pw_add_library(pw_allocator.bucket STATIC
-  HEADERS
-    public/pw_allocator/bucket.h
-  PUBLIC_INCLUDES
-    public
-  PUBLIC_DEPS
-    pw_function
-    pw_span
-    pw_third_party.fuchsia.stdcompat
-  PRIVATE_DEPS
-    pw_assert
-  SOURCES
-    bucket.cc
-)
-
 pw_add_library(pw_allocator.bucket_allocator INTERFACE
   HEADERS
     public/pw_allocator/bucket_allocator.h
@@ -124,7 +109,7 @@ pw_add_library(pw_allocator.bucket_allocator INTERFACE
   PUBLIC_DEPS
     pw_allocator.block_allocator
     pw_allocator.block.detailed_block
-    pw_allocator.bucket
+    pw_allocator.bucket.unordered
     pw_status
 )
 
@@ -141,13 +126,12 @@ pw_add_library(pw_allocator.buddy_allocator STATIC
     public
   PUBLIC_DEPS
     pw_allocator.allocator
-    pw_allocator.bucket
+    pw_allocator.block.basic
+    pw_allocator.bucket.unordered
     pw_bytes
     pw_containers.vector
     pw_status
   PRIVATE_DEPS
-    pw_allocator.buffer
-    pw_bytes.alignment
     pw_assert
     pw_third_party.fuchsia.stdcompat
   SOURCES
@@ -725,4 +709,5 @@ pw_add_test(pw_allocator.worst_fit_block_allocator_test
 
 add_subdirectory(benchmarks)
 add_subdirectory(block)
+add_subdirectory(bucket)
 add_subdirectory(examples)

pw_allocator/api.rst

@@ -312,7 +312,39 @@ uses the mix-ins above.
 
 Bucket
 ======
-.. doxygenclass:: pw::allocator::Bucket
+Several block allocator implementations improve performance by managing buckets,
+which are data structures that track free blocks. Several bucket implementations
+are provided that trade off between performance and per-block space needed when
+free.
+
+FastSortedBucket
+----------------
+.. doxygenclass:: pw::allocator::FastSortedBucket
+   :members:
+
+ForwardSortedBucket
+-------------------
+.. doxygenclass:: pw::allocator::ForwardSortedBucket
+   :members:
+
+ReverseFastSortedBucket
+-----------------------
+.. doxygenclass:: pw::allocator::ReverseFastSortedBucket
+   :members:
+
+ReverseSortedBucket
+-------------------
+.. doxygenclass:: pw::allocator::ReverseSortedBucket
+   :members:
+
+SequencedBucket
+---------------
+.. doxygenclass:: pw::allocator::SequencedBucket
+   :members:
+
+UnorderedBucket
+---------------
+.. doxygenclass:: pw::allocator::UnorderedBucket
    :members:
 
 .. _module-pw_allocator-api-metrics_adapter: