new allocator interface

[marler8997]

Related Issue: #4431 (Improve Allocator interface so client can avoid needless copying)

Replaces the current allocator interface with the following:

    /// Attempt to allocate at least `len` bytes aligned to `ptr_align`.
    ///
    /// If `len_align` is `0`, then the length returned MUST be exactly `len` bytes,
    /// otherwise, the length must be aligned to `len_align`.
    ///
    /// `len` must be greater than or equal to `len_align` and must be aligned by `len_align`.
    allocFn: fn (self: *Allocator, len: usize, ptr_align: u29, len_align: u29) Error![]u8,

    /// Attempt to expand or shrink memory in place. `buf.len` must equal the most recent
    /// length returned by `allocFn` or `resizeFn`.
    ///
    /// Passing a `new_len` of 0 frees and invalidates the buffer such that it can no
    /// longer be passed to `resizeFn`.
    ///
    /// error.OutOfMemory can only be returned if `new_len` is greater than `buf.len`.
    /// If `buf` cannot be expanded to accomodate `new_len`, then the allocation MUST be
    /// unmodified and error.OutOfMemory MUST be returned.
    ///
    /// If `len_align` is `0`, then the length returned MUST be exactly `len` bytes,
    /// otherwise, the length must be aligned to `len_align`.
    ///
    /// `new_len` must be greater than or equal to `len_align` and must be aligned by `len_align`.
    resizeFn: fn (self: *Allocator, buf: []u8, new_len: usize, len_align: u29) Error!usize,

This new interface makes 2 big changes. The first is that it provides a way for an allocator to report the full capacity of any allocation. This allows clients to take advantage of the entire memory space of any allocation.

The second change with the new interface is that it allows the caller to have more control over resizing and when/how to relocate memory. The previous interface had a reallocFn which would attempt to resize an allocation and would move and copy the entire buffer to a larger space when needed. The new interface allows clients to determine when memory should be moved and what data to preserve when doing so. The realloc implementation is now common between all allocators using a combination of function calls from the new interface.

[fengb]

If you can get this to work, I'm happy to redo my work for #4739

This change will make everything cleaner.

[marler8997]

@fengb yes I think I'll have it working soon.

[andrewrk]

Really nice work @marler8997. Thank you for your patience on what turned out to be a big project. I think this is very close to merge-ready.

@fengb and/or @kubkon would you mind providing a review on the changes to WasmPageAllocator?

[andrewrk]

Can you double check that this does not cause false positives with external tools such as valgrind? I'm concerned that valgrind would detect utilization of these extra bytes as writes to invalid memory addresses.

[marler8997]

TLDR; looks like valgrind shims malloc_usable_size to return the exact size originally requested from malloc.

Ok I verified valgrind handles this (at least on my linux box). Here's the program:

// zig build-exe leak.zig -lc
const std = @import("std");

pub fn main() !void {
    const allocator = std.heap.c_allocator;

    var i : usize = 1;
    while (i <= 100) : (i += 1) {
        const m = try allocator.callAllocFn(i, 1, 1);
        defer _ = allocator.callResizeFn(m, 0, 0) catch unreachable;
        std.debug.warn("alloc {} returned {}\n", .{i, m.len});
        //@memset(m.ptr, 0xbb, m.len + 1); // use this to cause an error
        @memset(m.ptr, 0xbb, m.len);
    }
}

Here we use the C allocator to make allocations, and utilize the full size (will call malloc_usable_size under the hood). When I run the binary by itself, I can see it usually returns more memory than I requested. However, when I run it with valgrind, it always returns the exact size requested. This is telling me that valgrind is shimming malloc_usable_size and causing it to always return the size originally requested in malloc. Kinda interesting.

I also verified that writing 1 byte over the size will cause valgrind to detect memory corruption (uncomment the bad @memset call).

[andrewrk]

Thanks for testing this out! This makes me feel comfortable with using malloc_usable_size.

[andrewrk]

Can you add doc comments to explain why this is needed rather than just using alignBackward?

Looks like it removes the restriction " /// The alignment must be a power of 2 and greater than 0. " ?

Is this necessary at the callsites? Or would it be appropriate to add that restriction to the callsites as well, and have them call alignBackward directly?

[marler8997]

This is necessary because allocating arrays require passing the element size for len_align which don't have to be powers of 2. When I was using alignBackwards originally, there were cases where array element sizes were not a power of 2 (i.e. I saw 56). I will add a doc comment explaining how the function differs from alignBackward.

[andrewrk]

The doc comments for the allocator say

/// Detects and asserts if the std.mem.Allocator interface is violated

Which looks to me like it's for testing implementations of the Allocator interface, rather than testing the usage of the Allocator high level API functions. In this case I don't think it makes sense to put the wrapper here, since for testing purposes we are not trying to test if the LeakCountAllocator code is correct, we are trying to test if the user code that is using the Allocator provided by the LeakCountAllocator is correct.

[marler8997]

ValidationAllocator validates both the usage of the allocator and the implementation.

i.e. for alloc, ValidationAllocator ensures len > 0, ptr_align is valid, len is aligned by len_align and len >= len_align. Once it returns, it validates that the len complies with the requested len_align and that the pointer is aligned by ptr_align.

Will update ddoc comment with:

/// Detects and asserts if the std.mem.Allocator interface is violated by the caller
/// or the allocator.

[daurnimator]

should this get moved to the std.c module as e.g. std.c.allocator?

[andrewrk]

no. std.c is for libc functions

[daurnimator]

Isn't it for things reliant on libc? (as this is)

[daurnimator]

could use aligned_alloc (C11+) or posix_memalign (older POSIX interface)

[andrewrk]

separate PR. we tried that before and it depends on libc versions. now that we have the ability to check, it's time to revisit, but that's out of scope of this changeset.

[marnix]

For the record, this also closed #4431.