Doxygen and rename methods in allocation_pool.

src/mem/allocation_pool.cpp

@@ -11,7 +11,7 @@ namespace mem {
         allocation_table::pos_in_fragment pos = find_suitable_fragment(bytes, alignment);
         if (not pos) {
             // Try to allocate a new one of size bytes + alignment - 1 (to satisfy alignment)
-            if (allocate_new_chunk(bytes + alignment - 1)) {
+            if (reserve_new_chunk(bytes + alignment - 1)) {
                 // Try again to find the chunk, now it must be successful
                 pos = find_suitable_fragment(bytes, alignment);
                 if (not pos) {
@@ -28,10 +28,10 @@ namespace mem {
         mark_free(c);
     }
 
-    bool allocation_pool::allocate_new_chunk(std::size_t bytes) {
+    bool allocation_pool::reserve_new_chunk(std::size_t bytes) {
         // Use the end address of the last chunk as a place where to allocate (try to keep at least part of the mem
         // contiguous)
-        if (mapped<chunk> mchunk = do_allocate_chunk(bytes, allocation_end_address()); mchunk) {
+        if (mapped<chunk> mchunk = do_reserve_chunk(bytes, reservation_end_address()); mchunk) {
             _tot_pool_size += mchunk.size();
             mark_free(mchunk.chunk());
             _chunks.emplace_back(std::move(mchunk));

src/mem/allocation_pool.h

@@ -10,20 +10,47 @@
 namespace mem {
 
 
+    /** @brief Abstract class that bridges between a mapped memory allocator and a memory resource.
+     * Users of this class will ask to allocate a certain amount of bytes under some alignment constraint. This class
+     * keeps track of which contiguous portions of memory are reserved for allocation, and if necessary asks the
+     * subclasses to reserve a chunk of memory of a certain size. It will then use that to serve the allocation request.
+     * The subclasses may allocate chunks of memory anywhere and with any alignment or size, as long as they are big
+     * enough.
+     * @note By implementation, currently the memory chunks are stored as @ref mem::mapped objects. That means that
+     * as per the destructor of @ref mem::mapped, the memory will be unmapped upon destruction or freeing. It is
+     * possible to extend this class to remove this constraints by e.g. templating or assigning the deallocator.
+     * @see allocation_table
+     * @see do_reserve_chunk
+     */
     class allocation_pool : private allocation_table {
         std::vector<mapped<chunk>> _chunks;
         std::size_t _tot_pool_size;
 
-        bool allocate_new_chunk(std::size_t bytes);
+        /** @brief Tries to reserve a new chunk of size at least @p bytes.
+         * @return True if the reservation succeeded.
+         * @see do_reserve_chunk
+         */
+        bool reserve_new_chunk(std::size_t bytes);
 
-        [[nodiscard]] inline void *allocation_end_address() const;
+        /** @brief Returns the first free address that is beyond any allocated chunks.
+         * This is the best position where to reserve to contiguously reserve a new chunk.
+         */
+        [[nodiscard]] inline void *reservation_end_address() const;
 
     protected:
 
-        virtual mapped<chunk> do_allocate_chunk(std::size_t bytes, void *hint) = 0;
+        /** @brief Reserves a raw chunk of memory of size at least @p bytes.
+         * Subclasses may reserve memory of any size, as long as it's at least @p bytes, with any alignment. They may
+         * try to reserve memory exactly at @p hint. If it is not possible to reserve, return an empty mapped object.
+         * @param bytes Size in bytes to reserve (minimum)
+         * @param hint Preferred position for reservation
+         */
+        virtual mapped<chunk> do_reserve_chunk(std::size_t bytes, void *hint) = 0;
 
     public:
 
+        /** @brief Constructs an empty allocation pool.
+         */
         inline allocation_pool() : allocation_table{}, _tot_pool_size{0} {}
 
         allocation_pool(allocation_pool const &) = delete;
@@ -33,12 +60,31 @@ namespace mem {
         using allocation_table::num_fragments;
         using allocation_table::largest_fragment_size;
 
+        /** @brief Tries to release chunks of memory that are reserved but unused.
+         * Loops through all the chunks that were ever reserved by @ref do_reserve_chunk and if they are currently
+         * unused, releases them for other usages.
+         * @return The total amounts of bytes from the allocation pool that were freed for other applications.
+         */
         std::size_t try_reduce_pool_size();
 
+        /** @brief Returns the total size of the pool in bytes.
+         * This is the total amount of memory reserve by @ref do_reserve_chunk upon request from @ref allocate.
+         */
         [[nodiscard]] inline std::size_t pool_size() const { return _tot_pool_size; }
+
+        /** @brief Returns the amount of memory that is currently in use (i.e. reserved and allocated).
+         */
         [[nodiscard]] inline std::size_t used_memory() const { return pool_size() - available_memory(); }
 
+        /** @brief Allocate a chunk of memory of size @p bytes bytes and with address aligned to @p alignment.
+         * This function may fail and return an empty chunk.
+         */
         chunk allocate(std::size_t bytes, std::size_t alignment = 1);
+
+        /** @brief Returns a chunk of memory to the pool for further allocations.
+         * @note No check is performed on @p c. The caller is respponsible to make sure that all chunks are consistently
+         * returned.
+         */
         void deallocate(chunk const &c);
 
         inline bool operator==(allocation_pool const &other) const { return _chunks == other._chunks; }
@@ -47,7 +93,7 @@ namespace mem {
 
 
 
-    void *allocation_pool::allocation_end_address() const {
+    void *allocation_pool::reservation_end_address() const {
         if (_chunks.empty()) {
             return nullptr;
         }

src/mem/resident_allocator.cpp

@@ -29,7 +29,7 @@ namespace mem {
         allocation_pool::deallocate({p, bytes});
     }
 
-    mapped<chunk> resident_memory_resource::do_allocate_chunk(std::size_t bytes, void *hint) {
+    mapped<chunk> resident_memory_resource::do_reserve_chunk(std::size_t bytes, void *hint) {
         static const std::size_t page_size = get_page_size();
         // Round up to the next multiple of a page number
         bytes = page_size * ((bytes + page_size - 1) / page_size);

src/mem/resident_allocator.h

@@ -16,7 +16,7 @@ namespace mem {
         void *do_allocate(std::size_t bytes, std::size_t alignment) override;
         void do_deallocate(void *p, std::size_t bytes, std::size_t) override;
         [[nodiscard]] bool do_is_equal(std::experimental::pmr::memory_resource const &other) const noexcept override;
-        mapped<chunk> do_allocate_chunk(std::size_t bytes, void *hint) override;
+        mapped<chunk> do_reserve_chunk(std::size_t bytes, void *hint) override;
     public:
         using allocation_pool::pool_size;
         using allocation_pool::used_memory;