Memory

    Like Zig, the C programming language has manual memory management. However, unlike Zig, C has a default allocator - , realloc, and free. When linking against libc, Zig exposes this allocator with std.heap.c_allocator. However, by convention, there is no default allocator in Zig. Instead, functions which need to allocate accept an *Allocator parameter. Likewise, data structures such as std.ArrayList accept an *Allocator parameter in their initialization functions:

    allocator.zig

    1. $ zig test allocator.zig
    2. Test 1/1 using an allocator...OK
    3. All tests passed.

    In the above example, 100 bytes of stack memory are used to initialize a FixedBufferAllocator, which is then passed to a function. As a convenience there is a global FixedBufferAllocator available for quick tests at std.debug.global_allocator, however it is deprecated and should be avoided in favor of directly using a FixedBufferAllocator as in the example above.

    Currently Zig has no general purpose allocator, but there is one under active development. Once it is merged into the Zig standard library it will become available to import with std.heap.default_allocator. However, it will still be recommended to follow the guide.

    What allocator to use depends on a number of factors. Here is a flow chart to help you decide:

    • Are you making a library? In this case, best to accept an as a parameter and allow your library's users to decide what allocator to use.
    • Is the maximum number of bytes that you will need bounded by a number known at comptime? In this case, use std.heap.FixedBufferAllocator or std.heap.ThreadSafeFixedBufferAllocator depending on whether you need thread-safety or not.
    • Is your program a command line application which runs from start to end without any fundamental 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: cli_allocation.zig
    1. $ zig build-exe cli_allocation.zig
    2. $ ./cli_allocation
    3. ptr=i32@7f01f88d7020

    When using this kind of allocator, there is no need to free anything manually. Everything gets freed at once with the call to arena.deinit().

    • Are the allocations part of a cyclical pattern such as a video game main loop, or a web server request handler? If the allocations can all be freed at once, at the end of the cycle, for example once the video game frame has been fully rendered, or the web server request has been served, then std.heap.ArenaAllocator is a great candidate. As demonstrated in the previous bullet point, this allows you to free entire arenas at once. Note also that if an upper bound of memory can be established, then std.heap.FixedBufferAllocator can be used as a further optimization.
    • Are you writing a test, and you want to make sure error.OutOfMemory is handled correctly? In this case, use std.debug.FailingAllocator.
    • Finally, if none of the above apply, you need a general purpose allocator. Zig does not yet have a general purpose allocator in the standard library, . You can also consider Implementing an Allocator.

    Where are the bytes?

    String literals such as "foo" are in the global constant data section. This is why it is an error to pass a string literal to a mutable slice, like this: 

    1. $ zig test test.zig
    2. /home/andy/dev/zig/docgen_tmp/test.zig:4:9: error: expected type '[]u8', found '[5]u8'
    3.         ^

    However if you make the slice constant, then it works:

    strlit.zig

    1. $ zig test strlit.zig
    2. Test 1/1 string literal to constant slice...OK
    3. All tests passed.

    Just like string literals, const declarations, when the value is known at , are stored in the global constant data section. Also Compile Time Variables are stored in the global constant data section.

    var declarations inside functions are stored in the function's stack frame. Once a function returns, any to variables in the function's stack frame become invalid references, and dereferencing them becomes unchecked Undefined Behavior.

    var declarations at the top level or in declarations are stored in the global data section.

    The location of memory allocated with allocator.alloc or allocator.create is determined by the allocator's implementation.

    TODO: thread local variables

    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 reallocFn and a shrinkFn.

    Heap Allocation Failure

    Many programming languages choose to handle the possibility of heap allocation failure by unconditionally crashing. By convention, Zig programmers do not consider this to be a satisfactory solution. Instead, error.OutOfMemory represents heap allocation failure, and Zig libraries return this error code whenever heap allocation failure prevented an operation from completing successfully.

    Some have argued that because some operating systems such as Linux have memory overcommit enabled by default, it is pointless to handle heap allocation failure. There are many problems with this reasoning:

    • Only some operating systems have an overcommit feature.
      • Linux has it enabled by default, but it is configurable.
      • Windows does not overcommit.
      • Embedded systems do not have overcommit.
      • Hobby operating systems may or may not have overcommit.
    • For real-time systems, not only is there no overcommit, but typically the maximum amount of memory per application is determined ahead of time.
    • Although some software has grown to depend on overcommit being enabled, its existence is the source of countless user experience disasters. When a system with overcommit enabled, such as Linux on default settings, comes close to memory exhaustion, the system locks up and becomes unusable. At this point, the OOM Killer selects an application to kill based on heuristics. This non-deterministic decision often results in an important process being killed, and often fails to return the system back to working order.

    Recursion is a fundamental tool in modeling software. However it has an often-overlooked problem: unbounded memory allocation.

    Recursion is an area of active experimentation in Zig and so the documentation here is not final. You can read a summary of recursion status in the 0.3.0 release notes.

    The short summary is that currently recursion works normally as you would expect. Although Zig code is not yet protected from stack overflow, it is planned that a future version of Zig will provide such protection, with some degree of cooperation from Zig code required.

    Lifetime and Ownership

    It is the Zig programmer's responsibility to ensure that a is not accessed when the memory pointed to is no longer available. Note that a slice is a form of pointer, in that it references other memory.

    In order to prevent bugs, there are some helpful conventions to follow when dealing with pointers. In general, when a function returns a pointer, the documentation for the function should explain who "owns" the pointer. This concept helps the programmer decide when it is appropriate, if ever, to free the pointer.

    For example, the function's documentation may say "caller owns the returned memory", in which case the code that calls the function must have a plan for when to free that memory. Probably in this situation, the function will accept an *Allocator parameter.

    The API documentation for functions and data structures should take great care to explain the ownership and lifetime semantics of pointers. Ownership determines whose responsibility it is to free the memory referenced by the pointer, and lifetime determines the point at which the memory becomes inaccessible (lest occur).