Skip to content

Commit 272d336

Browse files
daanxdaanx
committed
update aligned documentation
1 parent 20424db commit 272d336

File tree

6 files changed

+194
-221
lines changed

6 files changed

+194
-221
lines changed

‎doc/mimalloc-doc.h‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -571,20 +571,20 @@ void mi_subproc_add_current_thread(mi_subproc_id_t subproc);
571571
/// \defgroup aligned Aligned Allocation
572572
///
573573
/// Allocating aligned memory blocks.
574+
/// Note that `alignment` always follows `size` for consistency with the unaligned
575+
/// allocation API, but unfortunately this differs from `posix_memalign` and `aligned_alloc` in the C library.
574576
///
575577
/// \{
576578

577-
/// The maximum supported alignment size (currently 1MiB).
578-
#define MI_BLOCK_ALIGNMENT_MAX (1024*1024UL)
579-
580579
/// Allocate \a size bytes aligned by \a alignment.
581580
/// @param size number of bytes to allocate.
582-
/// @param alignment the minimal alignment of the allocated memory. Must be less than #MI_BLOCK_ALIGNMENT_MAX.
581+
/// @param alignment the minimal alignment of the allocated memory.
583582
/// @returns pointer to the allocated memory or \a NULL if out of memory.
584583
/// The returned pointer is aligned by \a alignment, i.e.
585584
/// `(uintptr_t)p % alignment == 0`.
586585
///
587586
/// Returns a unique pointer if called with \a size 0.
587+
/// @see [aligned_alloc](https://en.cppreference.com/w/c/memory/aligned_alloc) (in the standard C11 library, with switched arguments!)
588588
/// @see [_aligned_malloc](https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/aligned-malloc?view=vs-2017) (on Windows)
589589
/// @see [aligned_alloc](http://man.openbsd.org/reallocarray) (on BSD, with switched arguments!)
590590
/// @see [posix_memalign](https://linux.die.net/man/3/posix_memalign) (on Posix, with switched arguments!)

‎docs/group__aligned.html‎

Lines changed: 5 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -105,18 +105,11 @@
105105

106106
<div class="header">
107107
<div class="summary">
108-
<a href="#define-members">Macros</a> &#124;
109108
<a href="#func-members">Functions</a> </div>
110109
<div class="headertitle"><div class="title">Aligned Allocation</div></div>
111110
</div><!--header-->
112111
<div class="contents">
113112
<table class="memberdecls">
114-
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="define-members" name="define-members"></a>
115-
Macros</h2></td></tr>
116-
<tr class="memitem:ga2e3fc59317bd730a71788c4d56ac8bff" id="r_ga2e3fc59317bd730a71788c4d56ac8bff"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga2e3fc59317bd730a71788c4d56ac8bff">MI_BLOCK_ALIGNMENT_MAX</a></td></tr>
117-
<tr class="memdesc:ga2e3fc59317bd730a71788c4d56ac8bff"><td class="mdescLeft">&#160;</td><td class="mdescRight">The maximum supported alignment size (currently 1MiB). <br /></td></tr>
118-
<tr class="separator:ga2e3fc59317bd730a71788c4d56ac8bff"><td class="memSeparator" colspan="2">&#160;</td></tr>
119-
</table><table class="memberdecls">
120113
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
121114
Functions</h2></td></tr>
122115
<tr class="memitem:ga69578ff1a98ca16e1dcd02c0995cd65c" id="r_ga69578ff1a98ca16e1dcd02c0995cd65c"><td class="memItemLeft" align="right" valign="top">void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga69578ff1a98ca16e1dcd02c0995cd65c">mi_malloc_aligned</a> (size_t size, size_t alignment)</td></tr>
@@ -139,24 +132,7 @@
139132
<tr class="separator:gad06dcf2bb8faadb2c8ea61ee5d24bbf6"><td class="memSeparator" colspan="2">&#160;</td></tr>
140133
</table>
141134
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
142-
<p>Allocating aligned memory blocks. </p>
143-
<h2 class="groupheader">Macro Definition Documentation</h2>
144-
<a id="ga2e3fc59317bd730a71788c4d56ac8bff" name="ga2e3fc59317bd730a71788c4d56ac8bff"></a>
145-
<h2 class="memtitle"><span class="permalink"><a href="#ga2e3fc59317bd730a71788c4d56ac8bff">&#9670;&#160;</a></span>MI_BLOCK_ALIGNMENT_MAX</h2>
146-
147-
<div class="memitem">
148-
<div class="memproto">
149-
<table class="memname">
150-
<tr>
151-
<td class="memname">#define MI_BLOCK_ALIGNMENT_MAX</td>
152-
</tr>
153-
</table>
154-
</div><div class="memdoc">
155-
156-
<p>The maximum supported alignment size (currently 1MiB). </p>
157-
158-
</div>
159-
</div>
135+
<p>Allocating aligned memory blocks. 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>
160136
<h2 class="groupheader">Function Documentation</h2>
161137
<a id="ga424ef386fb1f9f8e0a86ab53f16eaaf1" name="ga424ef386fb1f9f8e0a86ab53f16eaaf1"></a>
162138
<h2 class="memtitle"><span class="permalink"><a href="#ga424ef386fb1f9f8e0a86ab53f16eaaf1">&#9670;&#160;</a></span>mi_calloc_aligned()</h2>
@@ -238,12 +214,14 @@ <h2 class="memtitle"><span class="permalink"><a href="#ga69578ff1a98ca16e1dcd02c
238214
<dl class="params"><dt>Parameters</dt><dd>
239215
<table class="params">
240216
<tr><td class="paramname">size</td><td>number of bytes to allocate. </td></tr>
241-
<tr><td class="paramname">alignment</td><td>the minimal alignment of the allocated memory. Must be less than <a class="el" href="#ga2e3fc59317bd730a71788c4d56ac8bff" title="The maximum supported alignment size (currently 1MiB).">MI_BLOCK_ALIGNMENT_MAX</a>. </td></tr>
217+
<tr><td class="paramname">alignment</td><td>the minimal alignment of the allocated memory. </td></tr>
242218
</table>
243219
</dd>
244220
</dl>
245221
<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>
246-
<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-malloc?view=vs-2017">_aligned_malloc</a> (on Windows) </dd>
222+
<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>
223+
<dd>
224+
<a href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/aligned-malloc?view=vs-2017">_aligned_malloc</a> (on Windows) </dd>
247225
<dd>
248226
<a href="http://man.openbsd.org/reallocarray">aligned_alloc</a> (on BSD, with switched arguments!) </dd>
249227
<dd>

‎docs/group__aligned.js‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
var group__aligned =
22
[
3-
[ "MI_BLOCK_ALIGNMENT_MAX", "group__aligned.html#ga2e3fc59317bd730a71788c4d56ac8bff", null ],
43
[ "mi_calloc_aligned", "group__aligned.html#ga424ef386fb1f9f8e0a86ab53f16eaaf1", null ],
54
[ "mi_calloc_aligned_at", "group__aligned.html#ga977f96bd2c5c141bcd70e6685c90d6c3", null ],
65
[ "mi_malloc_aligned", "group__aligned.html#ga69578ff1a98ca16e1dcd02c0995cd65c", null ],

‎docs/mimalloc-doc_8h_source.html‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -235,9 +235,7 @@
235235
<div class="line"><a id="l00568" name="l00568"></a><span class="lineno"> 568</span><span class="comment">// Aligned allocation</span></div>
236236
<div class="line"><a id="l00569" name="l00569"></a><span class="lineno"> 569</span><span class="comment">// ------------------------------------------------------</span></div>
237237
<div class="line"><a id="l00570" name="l00570"></a><span class="lineno"> 570</span> </div>
238-
<div class="line"><a id="l00576" name="l00576"></a><span class="lineno"> 576</span> </div>
239-
<div class="line"><a id="l00578" name="l00578"></a><span class="lineno"><a class="line" href="group__aligned.html#ga2e3fc59317bd730a71788c4d56ac8bff"> 578</a></span><span class="preprocessor">#define MI_BLOCK_ALIGNMENT_MAX (1024*1024UL)</span></div>
240-
<div class="line"><a id="l00579" name="l00579"></a><span class="lineno"> 579</span> </div>
238+
<div class="line"><a id="l00578" name="l00578"></a><span class="lineno"> 578</span> </div>
241239
<div class="line"><a id="l00592" name="l00592"></a><span class="lineno"><a class="line" href="group__aligned.html#ga69578ff1a98ca16e1dcd02c0995cd65c"> 592</a></span><span class="keywordtype">void</span>* <a class="code hl_function" href="group__aligned.html#ga69578ff1a98ca16e1dcd02c0995cd65c">mi_malloc_aligned</a>(<span class="keywordtype">size_t</span> size, <span class="keywordtype">size_t</span> alignment);</div>
242240
<div class="line"><a id="l00593" name="l00593"></a><span class="lineno"><a class="line" href="group__aligned.html#gaac7d0beb782f9b9ac31f47492b130f82"> 593</a></span><span class="keywordtype">void</span>* <a class="code hl_function" href="group__aligned.html#gaac7d0beb782f9b9ac31f47492b130f82">mi_zalloc_aligned</a>(<span class="keywordtype">size_t</span> size, <span class="keywordtype">size_t</span> alignment);</div>
243241
<div class="line"><a id="l00594" name="l00594"></a><span class="lineno"><a class="line" href="group__aligned.html#ga424ef386fb1f9f8e0a86ab53f16eaaf1"> 594</a></span><span class="keywordtype">void</span>* <a class="code hl_function" href="group__aligned.html#ga424ef386fb1f9f8e0a86ab53f16eaaf1">mi_calloc_aligned</a>(<span class="keywordtype">size_t</span> count, <span class="keywordtype">size_t</span> size, <span class="keywordtype">size_t</span> alignment);</div>

‎docs/navtreeindex0.js‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,14 @@ var NAVTREEINDEX0 =
88
"functions.html":[6,2,0],
99
"functions_vars.html":[6,2,1],
1010
"group__aligned.html":[5,2],
11-
"group__aligned.html#ga2022f71b95a7cd6cce1b6e07752ae8ca":[5,2,4],
12-
"group__aligned.html#ga2e3fc59317bd730a71788c4d56ac8bff":[5,2,0],
13-
"group__aligned.html#ga424ef386fb1f9f8e0a86ab53f16eaaf1":[5,2,1],
14-
"group__aligned.html#ga5d7a46d054b4d7abe9d8d2474add2edf":[5,2,5],
15-
"group__aligned.html#ga69578ff1a98ca16e1dcd02c0995cd65c":[5,2,3],
16-
"group__aligned.html#ga7c1778805ce50ebbf02ccbd5e39d5dba":[5,2,8],
17-
"group__aligned.html#ga977f96bd2c5c141bcd70e6685c90d6c3":[5,2,2],
18-
"group__aligned.html#gaac7d0beb782f9b9ac31f47492b130f82":[5,2,7],
19-
"group__aligned.html#gad06dcf2bb8faadb2c8ea61ee5d24bbf6":[5,2,6],
11+
"group__aligned.html#ga2022f71b95a7cd6cce1b6e07752ae8ca":[5,2,3],
12+
"group__aligned.html#ga424ef386fb1f9f8e0a86ab53f16eaaf1":[5,2,0],
13+
"group__aligned.html#ga5d7a46d054b4d7abe9d8d2474add2edf":[5,2,4],
14+
"group__aligned.html#ga69578ff1a98ca16e1dcd02c0995cd65c":[5,2,2],
15+
"group__aligned.html#ga7c1778805ce50ebbf02ccbd5e39d5dba":[5,2,7],
16+
"group__aligned.html#ga977f96bd2c5c141bcd70e6685c90d6c3":[5,2,1],
17+
"group__aligned.html#gaac7d0beb782f9b9ac31f47492b130f82":[5,2,6],
18+
"group__aligned.html#gad06dcf2bb8faadb2c8ea61ee5d24bbf6":[5,2,5],
2019
"group__analysis.html":[5,6],
2120
"group__analysis.html#a332a6c14d736a99699d5453a1cb04b41":[5,6,0,0],
2221
"group__analysis.html#ab47526df656d8837ec3e97f11b83f835":[5,6,0,2],

0 commit comments

Comments
 (0)