Improve commentary

src/ds/helpers.h

@@ -7,7 +7,8 @@ namespace snmalloc
 {
   /*
    * In some use cases we need to run before any of the C++ runtime has been
-   * initialised.  This singleton class is design to not depend on the runtime.
+   * initialised.  This singleton class is designed to not depend on the
+   * runtime.
    */
   template<class Object, Object init() noexcept>
   class Singleton

src/mem/alloc.h

@@ -98,6 +98,9 @@ namespace snmalloc
     template<class MP>
     friend class AllocPool;
 
+    /**
+     * Allocate memory of a statically known size.
+     */
     template<
       size_t size,
       ZeroMem zero_mem = NoZero,
@@ -118,7 +121,6 @@ namespace snmalloc
 
       stats().alloc_request(size);
 
-      // Allocate memory of a statically known size.
       if constexpr (sizeclass < NUM_SMALL_CLASSES)
       {
         return small_alloc<zero_mem, allow_reserve>(size);
@@ -137,6 +139,9 @@ namespace snmalloc
 #endif
     }
 
+    /**
+     * Allocate memory of a dynamically known size.
+     */
     template<ZeroMem zero_mem = NoZero, AllowReserve allow_reserve = YesReserve>
     SNMALLOC_FAST_PATH ALLOCATOR void* alloc(size_t size)
     {
@@ -151,7 +156,6 @@ namespace snmalloc
 #else
       stats().alloc_request(size);
 
-      // Allocate memory of a dynamically known size.
       // Perform the - 1 on size, so that zero wraps around and ends up on
       // slow path.
       if (likely((size - 1) <= (sizeclass_to_size(NUM_SMALL_CLASSES - 1) - 1)))
@@ -186,6 +190,10 @@ namespace snmalloc
 #endif
     }
 
+    /*
+     * Free memory of a statically known size. Must be called with an
+     * external pointer.
+     */
     template<size_t size>
     void dealloc(void* p)
     {
@@ -198,8 +206,6 @@ namespace snmalloc
 
       handle_message_queue();
 
-      // Free memory of a statically known size. Must be called with an
-      // external pointer.
       if (sizeclass < NUM_SMALL_CLASSES)
       {
         Superslab* super = Superslab::get(p);
@@ -227,6 +233,10 @@ namespace snmalloc
 #endif
     }
 
+    /*
+     * Free memory of a dynamically known size. Must be called with an
+     * external pointer.
+     */
     void dealloc(void* p, size_t size)
     {
 #ifdef USE_MALLOC
@@ -235,8 +245,6 @@ namespace snmalloc
 #else
       handle_message_queue();
 
-      // Free memory of a dynamically known size. Must be called with an
-      // external pointer.
       sizeclass_t sizeclass = size_to_sizeclass(size);
 
       if (sizeclass < NUM_SMALL_CLASSES)
@@ -266,14 +274,16 @@ namespace snmalloc
 #endif
     }
 
+    /*
+     * Free memory of an unknown size. Must be called with an external
+     * pointer.
+     */
     SNMALLOC_FAST_PATH void dealloc(void* p)
     {
 #ifdef USE_MALLOC
       return free(p);
 #else
 
-      // Free memory of an unknown size. Must be called with an external
-      // pointer.
       uint8_t size = chunkmap().get(address_cast(p));
 
       Superslab* super = Superslab::get(p);
@@ -311,7 +321,7 @@ namespace snmalloc
         RemoteAllocator* target = slab->get_allocator();
 
         // Reading a remote sizeclass won't fail, since the other allocator
-        // can't reuse the slab, as we have no yet deallocated this pointer.
+        // can't reuse the slab, as we have not yet deallocated this pointer.
         sizeclass_t sizeclass = slab->get_sizeclass();
 
         if (target == public_state())
@@ -442,9 +452,20 @@ namespace snmalloc
   private:
     using alloc_id_t = typename Remote::alloc_id_t;
 
+    /*
+     * A singly-linked list of Remote objects, supporting append and
+     * take-all operations.  Intended only for the private use of this
+     * allocator; the Remote objects here will later be taken and pushed
+     * to the inter-thread message queues.
+     */
     struct RemoteList
     {
+      /*
+       * A stub Remote object that will always be the head of this list;
+       * never taken for further processing.
+       */
       Remote head;
+
       Remote* last;
 
       RemoteList()

src/mem/allocconfig.h

@@ -113,7 +113,7 @@ namespace snmalloc
   static constexpr size_t MIN_ALLOC_BITS = bits::is64() ? 4 : 3;
   static constexpr size_t MIN_ALLOC_SIZE = 1 << MIN_ALLOC_BITS;
 
-  // Slabs are 64 kb.
+  // Slabs are 64 KiB unless constrained to 16 KiB.
   static constexpr size_t SLAB_BITS = ADDRESS_SPACE_CONSTRAINED ? 14 : 16;
   static constexpr size_t SLAB_SIZE = 1 << SLAB_BITS;
   static constexpr size_t SLAB_MASK = ~(SLAB_SIZE - 1);

src/mem/remoteallocator.h

@@ -8,6 +8,11 @@
 
 namespace snmalloc
 {
+  /*
+   * A region of memory destined for a remote allocator's dealloc() via the
+   * message passing system.  This structure is placed at the beginning of
+   * the allocation itself when it is queued for sending.
+   */
   struct Remote
   {
     using alloc_id_t = size_t;

src/mem/threadalloc.h

@@ -188,7 +188,7 @@ namespace snmalloc
 
 #ifdef SNMALLOC_USE_THREAD_CLEANUP
   /**
-   * Entry point the allows libc to call into the allocator for per-thread
+   * Entry point that allows libc to call into the allocator for per-thread
    * cleanup.
    */
   extern "C" void _malloc_thread_cleanup()