mirror/zig
1
0
Fork 0
mirror of https://github.com/ziglang/zig.git synced 2025-12-06 06:13:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

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 committed by Alex Rønne Petersen
parent 30ec163d14
commit 52eb9e84fb
No known key found for this signature in database
1 changed files with 10 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
doc/langref.html.in
View File

@ -6277,10 +6277,6 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
</li>
<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>
<li>
Need to use the same allocator in multiple threads? Use one of your choice
wrapped around {#syntax#}std.heap.ThreadSafeAllocator{#endsyntax#}
</li>
<li>
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#}.
@ -6290,7 +6286,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
cyclical pattern (such as a video game main loop, or a web server request handler),
such that it would make sense to free everything at once at the end?
In this case, it is recommended to follow this pattern:
{#code|cli_allocation.zig#}
{#code|cli_allocation.zig#}
When using this kind of allocator, there is no need to free anything manually. Everything
gets freed at once with the call to {#syntax#}arena.deinit(){#endsyntax#}.
@ -6313,14 +6309,18 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
</li>
<li>
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#}
{#link|struct#} of configuration options and returns a type.
Generally, you will set up one {#syntax#}std.heap.GeneralPurposeAllocator{#endsyntax#} in
your main function, and then pass it or sub-allocators around to various parts of your
If you are in Debug mode, {#syntax#}std.heap.DebugAllocator{#endsyntax#} is available as a
function that takes a {#link|comptime#} {#link|struct#} of configuration options and returns a type.
Generally, you will set up exactly one in your main function, and
then pass it or sub-allocators around to various parts of your
application.
</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>
</ol>
{#header_close#}
@ -6355,17 +6355,6 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
<p>TODO: thread local variables</p>
{#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#}
<p>
Many programming languages choose to handle the possibility of heap allocation failure by