NFC: doc tweaks

src/aal/aal.h

@@ -195,9 +195,12 @@ namespace snmalloc
     static SNMALLOC_FAST_PATH CapPtr<T, BOut>
     capptr_bound(CapPtr<U, BIn> a, size_t size) noexcept
     {
-      // Impose constraints on bounds annotations.
-      static_assert(BIn::spatial >= capptr::dimension::Spatial::Chunk);
-      static_assert(capptr::is_spatial_refinement<BIn, BOut>());
+      static_assert(
+        BIn::spatial > capptr::dimension::Spatial::Alloc,
+        "Refusing to re-bound Spatial::Alloc CapPtr");
+      static_assert(
+        capptr::is_spatial_refinement<BIn, BOut>(),
+        "capptr_bound must preserve non-spatial CapPtr dimensions");
 
       UNUSED(size);
       return CapPtr<T, BOut>(a.template as_static<T>().unsafe_ptr());

src/backend/address_space_core.h

@@ -20,6 +20,16 @@ namespace snmalloc
    *
    * It cannot unreserve memory, so this does not require the
    * usual complexity of a buddy allocator.
+   *
+   * TODO: This manages pieces of memory smaller than (1U << MIN_CHUNK_BITS) to
+   * source Metaslab and LocalCache objects.  On CHERI, where ASLR and guard
+   * pages are not needed, it may be worth switching to a design where we
+   * bootstrap allocators with at least two embedded Metaslab-s that can be used
+   * to construct slabs for LocalCache and, of course, additional Metaslab
+   * objects.  That would let us stop splitting memory below that threshold
+   * here, and may reduce address space fragmentation or address space committed
+   * to Metaslab objects in perpetuity; it could also make {set,get}_next less
+   * scary.
    */
   class AddressSpaceManagerCore
   {

src/mem/localalloc.h

@@ -276,8 +276,10 @@ namespace snmalloc
         return;
       }
 
-      // Recheck what kind of dealloc we should do incase, the allocator we
-      // get from lazy_init is the originating allocator.
+      // Recheck what kind of dealloc we should do in case the allocator we get
+      // from lazy_init is the originating allocator.  (TODO: but note that this
+      // can't suddenly become a large deallocation; the only distinction is
+      // between being ours to handle and something to post to a Remote.)
       lazy_init(
         [&](CoreAlloc*, CapPtr<void, capptr::bounds::Alloc> p) {
           dealloc(p.unsafe_ptr()); // TODO don't double count statistics
@@ -602,9 +604,10 @@ namespace snmalloc
       // be implicit domestication through the `SharedStateHandle::Pagemap` or
       // we could just leave well enough alone.
 
-      // Note that this should return 0 for nullptr.
+      // Note that alloc_size should return 0 for nullptr.
       // Other than nullptr, we know the system will be initialised as it must
       // be called with something we have already allocated.
+      //
       // To handle this case we require the uninitialised pagemap contain an
       // entry for the first chunk of memory, that states it represents a
       // large object, so we can pull the check for null off the fast path.

src/mem/metaslab.h

@@ -15,7 +15,6 @@ namespace snmalloc
   };
 
   // The Metaslab represent the status of a single slab.
-  // This can be either a short or a standard slab.
   class alignas(CACHELINE_SIZE) Metaslab
   {
   public:
@@ -192,7 +191,7 @@ namespace snmalloc
    */
   class MetaEntry
   {
-    Metaslab* meta{nullptr};
+    Metaslab* meta{nullptr}; // may also be ChunkRecord*
 
     /**
      * A bit-packed pointer to the owning allocator (if any), and the sizeclass

src/mem/slaballocator.h

@@ -34,7 +34,7 @@ namespace snmalloc
    * Used to ensure the per slab meta data is large enough for both use cases.
    */
   static_assert(
-    sizeof(Metaslab) >= sizeof(ChunkRecord), "We conflat these two types.");
+    sizeof(Metaslab) >= sizeof(ChunkRecord), "We conflate these two types.");
 
   /**
    * This is the global state required for the chunk allocator.