Commit 52eb9e84fb5b06581cff626051d1f09be3de8eb8 | zig

author	Andrew Kelley <andrew@ziglang.org> 2025-09-06 11:50:59-07:00
committer	Alex Rønne Petersen <alex@alexrp.com> 2025-09-12 02:30:20+02:00
log	52eb9e84fb5b06581cff626051d1f09be3de8eb8
tree	59ac4bdc76474703630d6eb993260d5b2c6229aa
parent	30ec163d14245ac392ccb3cc65220a89cded8576
signature	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

doc/langref.html.in+10-21

 @@ -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#}
+              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.
           </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