authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-09-06 11:50:59-07:00
committergravatar for alex@alexrp.comAlex Rønne Petersen <alex@alexrp.com> 2025-09-12 02:30:20+02:00
log52eb9e84fb5b06581cff626051d1f09be3de8eb8
tree59ac4bdc76474703630d6eb993260d5b2c6229aa
parent30ec163d14245ac392ccb3cc65220a89cded8576
signaturebadge-check Signed by SSH key SHA256:7B/LJ7bpR1eX8aCXSr4mtd5M45VMPKcx9zY8e95b5QM

langref: update "Choosing an Allocator" section

and delete "Implementing an Allocator" section because it is out of scope.

1 files changed, 10 insertions(+), 21 deletions(-)

doc/langref.html.in+10-21
......@@ -6277,10 +6277,6 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
62776277 </li>
62786278 <li>Are you linking libc? In this case, {#syntax#}std.heap.c_allocator{#endsyntax#} is likely
62796279 the right choice, at least for your main allocator.</li>
6280 <li>
6281 Need to use the same allocator in multiple threads? Use one of your choice
6282 wrapped around {#syntax#}std.heap.ThreadSafeAllocator{#endsyntax#}
6283 </li>
62846280 <li>
62856281 Is the maximum number of bytes that you will need bounded by a number known at
62866282 {#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
62906286 cyclical pattern (such as a video game main loop, or a web server request handler),
62916287 such that it would make sense to free everything at once at the end?
62926288 In this case, it is recommended to follow this pattern:
6293 {#code|cli_allocation.zig#}
6289 {#code|cli_allocation.zig#}
62946290
62956291 When using this kind of allocator, there is no need to free anything manually. Everything
62966292 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
63136309 </li>
63146310 <li>
63156311 Finally, if none of the above apply, you need a general purpose allocator.
6316 Zig's general purpose allocator is available as a function that takes a {#link|comptime#}
6317 {#link|struct#} of configuration options and returns a type.
6318 Generally, you will set up one {#syntax#}std.heap.GeneralPurposeAllocator{#endsyntax#} in
6319 your main function, and then pass it or sub-allocators around to various parts of your
6312 If you are in Debug mode, {#syntax#}std.heap.DebugAllocator{#endsyntax#} is available as a
6313 function that takes a {#link|comptime#} {#link|struct#} of configuration options and returns a type.
6314 Generally, you will set up exactly one in your main function, and
6315 then pass it or sub-allocators around to various parts of your
63206316 application.
63216317 </li>
63226318 <li>
6323 You can also consider {#link|Implementing an Allocator#}.
6319 If you are compiling in ReleaseFast mode, {#syntax#}std.heap.smp_allocator{#endsyntax#} is
6320 a solid choice for a general purpose allocator.
6321 </li>
6322 <li>
6323 You can also consider implementing an allocator.
63246324 </li>
63256325 </ol>
63266326 {#header_close#}
......@@ -6355,17 +6355,6 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
63556355 <p>TODO: thread local variables</p>
63566356 {#header_close#}
63576357
6358 {#header_open|Implementing an Allocator#}
6359 <p>Zig programmers can implement their own allocators by fulfilling the Allocator interface.
6360 In order to do this one must read carefully the documentation comments in std/mem.zig and
6361 then supply a {#syntax#}allocFn{#endsyntax#} and a {#syntax#}resizeFn{#endsyntax#}.
6362 </p>
6363 <p>
6364 There are many example allocators to look at for inspiration. Look at std/heap.zig and
6365 {#syntax#}std.heap.GeneralPurposeAllocator{#endsyntax#}.
6366 </p>
6367 {#header_close#}
6368
63696358 {#header_open|Heap Allocation Failure#}
63706359 <p>
63716360 Many programming languages choose to handle the possibility of heap allocation failure by