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
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

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>
<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#}.
@ -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), 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? such that it would make sense to free everything at once at the end?
In this case, it is recommended to follow this pattern: 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 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#}. 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>
<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