mirrors/zig
1
0
Fork 0
mirror of https://codeberg.org/ziglang/zig.git synced 2025-12-06 13:54:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

langref: update "Choosing an Allocator" section

Browse source 
and delete "Implementing an Allocator" section because it is out of
scope.
This commit is contained in:
Andrew Kelley 2025-09-06 11:50:59 -07:00
parent 1a5cf072a8
commit 91b3769b03
1 changed files with 10 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
doc/langref.html.in
View file

@ -6277,10 +6277,6 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
</li> </li>
<li>Are you linking libc? In this case, {#syntax#}std.heap.c_allocator{#endsyntax#} is likely <li>Are you linking libc? In this case, {#syntax#}std.heap.c_allocator{#endsyntax#} is likely
the right choice, at least for your main allocator.</li> the right choice, at least for your main allocator.</li>
<li>
Need to use the same allocator in multiple threads? Use one of your choice
wrapped around {#syntax#}std.heap.ThreadSafeAllocator{#endsyntax#}
</li>
<li> <li>
Is the maximum number of bytes that you will need bounded by a number known at Is the maximum number of bytes that you will need bounded by a number known at
{#link|comptime#}? In this case, use {#syntax#}std.heap.FixedBufferAllocator{#endsyntax#}. {#link|comptime#}? In this case, use {#syntax#}std.heap.FixedBufferAllocator{#endsyntax#}.
@ -6313,14 +6309,18 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
</li> </li>
<li> <li>
Finally, if none of the above apply, you need a general purpose allocator. Finally, if none of the above apply, you need a general purpose allocator.
Zig's general purpose allocator is available as a function that takes a {#link|comptime#} If you are in Debug mode, {#syntax#}std.heap.DebugAllocator{#endsyntax#} is available as a
{#link|struct#} of configuration options and returns a type. function that takes a {#link|comptime#} {#link|struct#} of configuration options and returns a type.
Generally, you will set up one {#syntax#}std.heap.GeneralPurposeAllocator{#endsyntax#} in Generally, you will set up exactly one in your main function, and
your main function, and then pass it or sub-allocators around to various parts of your then pass it or sub-allocators around to various parts of your
application. application.
</li> </li>
<li> <li>
You can also consider {#link|Implementing an Allocator#}. If you are compiling in ReleaseFast mode, {#syntax#}std.heap.smp_allocator{#endsyntax#} is
a solid choice for a general purpose allocator.
</li>
<li>
You can also consider implementing an allocator.
</li> </li>
</ol> </ol>
{#header_close#} {#header_close#}
@ -6355,17 +6355,6 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
<p>TODO: thread local variables</p> <p>TODO: thread local variables</p>
{#header_close#} {#header_close#}
{#header_open|Implementing an Allocator#}
<p>Zig programmers can implement their own allocators by fulfilling the Allocator interface.
In order to do this one must read carefully the documentation comments in std/mem.zig and
then supply a {#syntax#}allocFn{#endsyntax#} and a {#syntax#}resizeFn{#endsyntax#}.
</p>
<p>
There are many example allocators to look at for inspiration. Look at std/heap.zig and
{#syntax#}std.heap.GeneralPurposeAllocator{#endsyntax#}.
</p>
{#header_close#}
{#header_open|Heap Allocation Failure#} {#header_open|Heap Allocation Failure#}
<p> <p>
Many programming languages choose to handle the possibility of heap allocation failure by Many programming languages choose to handle the possibility of heap allocation failure by