update docs

Author: daanx

doc/mimalloc-doc.h

@@ -281,8 +281,7 @@ void* mi_zalloc_small(size_t size);
 /// The returned size can be
 /// used to call \a mi_expand successfully.
 /// The returned size is always at least equal to the
-/// allocated size of \a p, and, in the current design,
-/// should be less than 16.7% more.
+/// allocated size of \a p.
 ///
 /// @see [_msize](https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/msize?view=vs-2017) (Windows)
 /// @see [malloc_usable_size](http://man7.org/linux/man-pages/man3/malloc_usable_size.3.html) (Linux)
@@ -307,7 +306,7 @@ size_t mi_good_size(size_t size);
 /// in very narrow circumstances; in particular, when a long running thread
 /// allocates a lot of blocks that are freed by other threads it may improve
 /// resource usage by calling this every once in a while.
-void   mi_collect(bool force);
+void mi_collect(bool force);
 
 /// Deprecated
 /// @param out Ignored, outputs to the registered output function or stderr by default.
@@ -540,6 +539,19 @@ bool  mi_manage_os_memory_ex(void* start, size_t size, bool is_committed, bool i
 /// @return The new heap or `NULL`.
 mi_heap_t* mi_heap_new_in_arena(mi_arena_id_t arena_id);
 
+/// @brief Create a new heap
+/// @param heap_tag       The heap tag associated with this heap; heaps only reclaim memory between heaps with the same tag.
+/// @param allow_destroy  Is \a mi_heap_destroy allowed?  Not allowing this allows the heap to reclaim memory from terminated threads.
+/// @param arena_id       If not 0, the heap will only allocate from the specified arena.
+/// @return A new heap or `NULL` on failure.
+///
+/// The \a arena_id can be used by runtimes to allocate only in a specified pre-reserved arena.
+/// This is used for example for a compressed pointer heap in Koka.
+///
+/// The \a heap_tag enables heaps to keep objects of a certain type isolated to heaps with that tag.
+/// This is used for example in the CPython integration.
+mi_heap_t* mi_heap_new_ex(int heap_tag, bool allow_destroy, mi_arena_id_t arena_id);
+
 /// A process can associate threads with sub-processes.
 /// A sub-process will not reclaim memory from (abandoned heaps/threads)
 /// other subprocesses.
@@ -578,12 +590,16 @@ void mi_subproc_add_current_thread(mi_subproc_id_t subproc);
 
 /// Allocate \a size bytes aligned by \a alignment.
 /// @param size  number of bytes to allocate.
-/// @param alignment  the minimal alignment of the allocated memory.
-/// @returns pointer to the allocated memory or \a NULL if out of memory.
-/// The returned pointer is aligned by \a alignment, i.e.
-/// `(uintptr_t)p % alignment == 0`.
-///
+/// @param alignment  the minimal alignment of the allocated memory.       
+/// @returns pointer to the allocated memory or \a NULL if out of memory,
+/// or if the alignment is not a power of 2 (including 0). The \a size is unrestricted
+/// (and does not have to be an integral multiple of the \a alignment).
+/// The returned pointer is aligned by \a alignment, i.e. `(uintptr_t)p % alignment == 0`.
 /// Returns a unique pointer if called with \a size 0.
+///
+/// Note that `alignment` always follows `size` for consistency with the unaligned
+/// allocation API, but unfortunately this differs from `posix_memalign` and `aligned_alloc` in the C library.
+///
 /// @see [aligned_alloc](https://en.cppreference.com/w/c/memory/aligned_alloc) (in the standard C11 library, with switched arguments!)
 /// @see [_aligned_malloc](https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/aligned-malloc?view=vs-2017) (on Windows)
 /// @see [aligned_alloc](http://man.openbsd.org/reallocarray) (on BSD, with switched arguments!)
@@ -598,11 +614,12 @@ void* mi_realloc_aligned(void* p, size_t newsize, size_t alignment);
 /// @param size  number of bytes to allocate.
 /// @param alignment  the minimal alignment of the allocated memory at \a offset.
 /// @param offset     the offset that should be aligned.
-/// @returns pointer to the allocated memory or \a NULL if out of memory.
-/// The returned pointer is aligned by \a alignment at \a offset, i.e.
-/// `((uintptr_t)p + offset) % alignment == 0`.
-///
+/// @returns pointer to the allocated memory or \a NULL if out of memory,
+/// or if the alignment is not a power of 2 (including 0). The \a size is unrestricted
+/// (and does not have to be an integral multiple of the \a alignment).
+/// The returned pointer is aligned by \a alignment, i.e. `(uintptr_t)p % alignment == 0`.
 /// Returns a unique pointer if called with \a size 0.
+///
 /// @see [_aligned_offset_malloc](https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/aligned-offset-malloc?view=vs-2017) (on Windows)
 void* mi_malloc_aligned_at(size_t size, size_t alignment, size_t offset);
 void* mi_zalloc_aligned_at(size_t size, size_t alignment, size_t offset);
@@ -841,6 +858,7 @@ typedef struct mi_heap_area_s {
   size_t used;        ///< bytes in use by allocated blocks
   size_t block_size;  ///< size in bytes of one block
   size_t full_block_size; ///< size in bytes of a full block including padding and metadata.
+  int    heap_tag;    ///< heap tag associated with this area (see \a mi_heap_new_ex)
 } mi_heap_area_t;
 
 /// Visitor function passed to mi_heap_visit_blocks()
@@ -865,8 +883,20 @@ typedef bool (mi_block_visit_fun)(const mi_heap_t* heap, const mi_heap_area_t* a
 /// @returns \a true if all areas and blocks were visited.
 bool mi_heap_visit_blocks(const mi_heap_t* heap, bool visit_all_blocks, mi_block_visit_fun* visitor, void* arg);
 
-/// Visit all areas and blocks in abandoned heaps.
-/// Note: requires the option `mi_option_allow_visit_abandoned` to be set
+/// @brief Visit all areas and blocks in abandoned heaps.
+/// @param subproc_id The sub-process id associated with the abandonded heaps.
+/// @param heap_tag Visit only abandoned memory with the specified heap tag, use -1 to visit all abandoned memory.
+/// @param visit_blocks If \a true visits all allocated blocks, otherwise
+///                         \a visitor is only called for every heap area.
+/// @param visitor This function is called for every area in the heap
+///                 (with \a block as \a NULL). If \a visit_all_blocks is
+///                 \a true, \a visitor is also called for every allocated
+///                 block in every area (with `block!=NULL`).
+///                 return \a false from this function to stop visiting early.
+/// @param arg extra argument passed to the \a visitor.
+/// @return \a true if all areas and blocks were visited.
+///
+/// Note: requires the option `mi_option_visit_abandoned` to be set
 /// at the start of the program.
 bool mi_abandoned_visit_blocks(mi_subproc_id_t subproc_id, int heap_tag, bool visit_blocks, mi_block_visit_fun* visitor, void* arg);
 

docs/functions.html

@@ -109,6 +109,7 @@
 <li>blocks&#160;:&#160;<a class="el" href="group__analysis.html#ae0085e6e1cf059a4eb7767e30e9991b8">mi_heap_area_t</a></li>
 <li>committed&#160;:&#160;<a class="el" href="group__analysis.html#ab47526df656d8837ec3e97f11b83f835">mi_heap_area_t</a></li>
 <li>full_block_size&#160;:&#160;<a class="el" href="group__analysis.html#ab53664e31d7fe2564f8d42041ef75cb3">mi_heap_area_t</a></li>
+<li>heap_tag&#160;:&#160;<a class="el" href="group__analysis.html#a2b7a0c92ece8daf46b558efc990ebdc1">mi_heap_area_t</a></li>
 <li>reserved&#160;:&#160;<a class="el" href="group__analysis.html#ae848a3e6840414891035423948ca0383">mi_heap_area_t</a></li>
 <li>used&#160;:&#160;<a class="el" href="group__analysis.html#ab820302c5cd0df133eb8e51650a008b4">mi_heap_area_t</a></li>
 </ul>

docs/functions_vars.html

@@ -109,6 +109,7 @@
 <li>blocks&#160;:&#160;<a class="el" href="group__analysis.html#ae0085e6e1cf059a4eb7767e30e9991b8">mi_heap_area_t</a></li>
 <li>committed&#160;:&#160;<a class="el" href="group__analysis.html#ab47526df656d8837ec3e97f11b83f835">mi_heap_area_t</a></li>
 <li>full_block_size&#160;:&#160;<a class="el" href="group__analysis.html#ab53664e31d7fe2564f8d42041ef75cb3">mi_heap_area_t</a></li>
+<li>heap_tag&#160;:&#160;<a class="el" href="group__analysis.html#a2b7a0c92ece8daf46b558efc990ebdc1">mi_heap_area_t</a></li>
 <li>reserved&#160;:&#160;<a class="el" href="group__analysis.html#ae848a3e6840414891035423948ca0383">mi_heap_area_t</a></li>
 <li>used&#160;:&#160;<a class="el" href="group__analysis.html#ab820302c5cd0df133eb8e51650a008b4">mi_heap_area_t</a></li>
 </ul>

docs/group__aligned.html

@@ -214,12 +214,14 @@ <h2 class="memtitle"><span class="permalink"><a href="#ga69578ff1a98ca16e1dcd02c
 <dl class="params"><dt>Parameters</dt><dd>
   <table class="params">
     <tr><td class="paramname">size</td><td>number of bytes to allocate. </td></tr>
-    <tr><td class="paramname">alignment</td><td>the minimal alignment of the allocated memory. </td></tr>
+    <tr><td class="paramname">alignment</td><td>the minimal alignment of the allocated memory. <br  />
+ </td></tr>
   </table>
   </dd>
 </dl>
-<dl class="section return"><dt>Returns</dt><dd>pointer to the allocated memory or <em>NULL</em> if out of memory. The returned pointer is aligned by <em>alignment</em>, i.e. <code>(uintptr_t)p % alignment == 0</code>.</dd></dl>
-<p>Returns a unique pointer if called with <em>size</em> 0. </p><dl class="section see"><dt>See also</dt><dd><a href="https://en.cppreference.com/w/c/memory/aligned_alloc">aligned_alloc</a> (in the standard C11 library, with switched arguments!) </dd>
+<dl class="section return"><dt>Returns</dt><dd>pointer to the allocated memory or <em>NULL</em> if out of memory, or if the alignment is not a power of 2 (including 0). The <em>size</em> is unrestricted (and does not have to be an integral multiple of the <em>alignment</em>). The returned pointer is aligned by <em>alignment</em>, i.e. <code>(uintptr_t)p % alignment == 0</code>. Returns a unique pointer if called with <em>size</em> 0.</dd></dl>
+<p>Note that <code>alignment</code> always follows <code>size</code> for consistency with the unaligned allocation API, but unfortunately this differs from <code>posix_memalign</code> and <code>aligned_alloc</code> in the C library.</p>
+<dl class="section see"><dt>See also</dt><dd><a href="https://en.cppreference.com/w/c/memory/aligned_alloc">aligned_alloc</a> (in the standard C11 library, with switched arguments!) </dd>
 <dd>
 <a href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/aligned-malloc?view=vs-2017">_aligned_malloc</a> (on Windows) </dd>
 <dd>
@@ -264,8 +266,8 @@ <h2 class="memtitle"><span class="permalink"><a href="#ga2022f71b95a7cd6cce1b6e0
   </table>
   </dd>
 </dl>
-<dl class="section return"><dt>Returns</dt><dd>pointer to the allocated memory or <em>NULL</em> if out of memory. The returned pointer is aligned by <em>alignment</em> at <em>offset</em>, i.e. <code>((uintptr_t)p + offset) % alignment == 0</code>.</dd></dl>
-<p>Returns a unique pointer if called with <em>size</em> 0. </p><dl class="section see"><dt>See also</dt><dd><a href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/aligned-offset-malloc?view=vs-2017">_aligned_offset_malloc</a> (on Windows) </dd></dl>
+<dl class="section return"><dt>Returns</dt><dd>pointer to the allocated memory or <em>NULL</em> if out of memory, or if the alignment is not a power of 2 (including 0). The <em>size</em> is unrestricted (and does not have to be an integral multiple of the <em>alignment</em>). The returned pointer is aligned by <em>alignment</em>, i.e. <code>(uintptr_t)p % alignment == 0</code>. Returns a unique pointer if called with <em>size</em> 0.</dd></dl>
+<dl class="section see"><dt>See also</dt><dd><a href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/aligned-offset-malloc?view=vs-2017">_aligned_offset_malloc</a> (on Windows) </dd></dl>
 
 </div>
 </div>

docs/group__analysis.html

@@ -185,6 +185,12 @@ <h2 class="memtitle"><span class="permalink"><a href="#structmi__heap__area__t">
 <td class="fielddoc">
 size in bytes of a full block including padding and metadata. </td></tr>
 <tr><td class="fieldtype">
+<a id="a2b7a0c92ece8daf46b558efc990ebdc1" name="a2b7a0c92ece8daf46b558efc990ebdc1"></a>int</td>
+<td class="fieldname">
+heap_tag</td>
+<td class="fielddoc">
+heap tag associated with this area (see <em>mi_heap_new_ex</em>) </td></tr>
+<tr><td class="fieldtype">
 <a id="ae848a3e6840414891035423948ca0383" name="ae848a3e6840414891035423948ca0383"></a>size_t</td>
 <td class="fieldname">
 reserved</td>
@@ -255,7 +261,18 @@ <h2 class="memtitle"><span class="permalink"><a href="#ga6a4865a887b2ec5247854af
 </div><div class="memdoc">
 
 <p>Visit all areas and blocks in abandoned heaps. </p>
-<p>Note: requires the option <code>mi_option_allow_visit_abandoned</code> to be set at the start of the program. </p>
+<dl class="params"><dt>Parameters</dt><dd>
+  <table class="params">
+    <tr><td class="paramname">subproc_id</td><td>The sub-process id associated with the abandonded heaps. </td></tr>
+    <tr><td class="paramname">heap_tag</td><td>Visit only abandoned memory with the specified heap tag, use -1 to visit all abandoned memory. </td></tr>
+    <tr><td class="paramname">visit_blocks</td><td>If <em>true</em> visits all allocated blocks, otherwise <em>visitor</em> is only called for every heap area. </td></tr>
+    <tr><td class="paramname">visitor</td><td>This function is called for every area in the heap (with <em>block</em> as <em>NULL</em>). If <em>visit_all_blocks</em> is <em>true</em>, <em>visitor</em> is also called for every allocated block in every area (with <code>block!=NULL</code>). return <em>false</em> from this function to stop visiting early. </td></tr>
+    <tr><td class="paramname">arg</td><td>extra argument passed to the <em>visitor</em>. </td></tr>
+  </table>
+  </dd>
+</dl>
+<dl class="section return"><dt>Returns</dt><dd><em>true</em> if all areas and blocks were visited.</dd></dl>
+<p>Note: requires the option <code>mi_option_visit_abandoned</code> to be set at the start of the program. </p>
 
 </div>
 </div>

docs/group__analysis.js

@@ -5,6 +5,7 @@ var group__analysis =
       [ "blocks", "group__analysis.html#ae0085e6e1cf059a4eb7767e30e9991b8", null ],
       [ "committed", "group__analysis.html#ab47526df656d8837ec3e97f11b83f835", null ],
       [ "full_block_size", "group__analysis.html#ab53664e31d7fe2564f8d42041ef75cb3", null ],
+      [ "heap_tag", "group__analysis.html#a2b7a0c92ece8daf46b558efc990ebdc1", null ],
       [ "reserved", "group__analysis.html#ae848a3e6840414891035423948ca0383", null ],
       [ "used", "group__analysis.html#ab820302c5cd0df133eb8e51650a008b4", null ]
     ] ],

docs/group__analysis_structmi__heap__area__t.js

@@ -4,6 +4,7 @@ var group__analysis_structmi__heap__area__t =
     [ "blocks", "group__analysis.html#ae0085e6e1cf059a4eb7767e30e9991b8", null ],
     [ "committed", "group__analysis.html#ab47526df656d8837ec3e97f11b83f835", null ],
     [ "full_block_size", "group__analysis.html#ab53664e31d7fe2564f8d42041ef75cb3", null ],
+    [ "heap_tag", "group__analysis.html#a2b7a0c92ece8daf46b558efc990ebdc1", null ],
     [ "reserved", "group__analysis.html#ae848a3e6840414891035423948ca0383", null ],
     [ "used", "group__analysis.html#ab820302c5cd0df133eb8e51650a008b4", null ]
 ];