replace "heap" with "dynamic allocation" in the documentation

[thestinger]

The documentation should be conveying the language semantics, not an inaccurate analogy of the implementation details. Rust never makes use of the dss section (aka the heap) by default as jemalloc prefers obtaining all memory via anonymous memory mappings. Stacks are dynamic allocations coming from the same operating system API as Box<T> and Rc<T>. It's all obtained via mmap and VirtualAlloc. The classical distinction between a static call stack and a dynamic heap doesn't really exist on modern operating systems since multi-threading means stacks are dynamic memory allocations.

[zwarich]

To be fair, the term heap is commonly used without confusion on platforms like OS X where the standard allocator uses the equivalent of anonymous mappings.

[bstrie]

I tend to agree, to me the idea of a "heap" conjures images of Java.

On the other hand, the "heap vs. stack" dichotomy, imagined or not, is quite popular. I'm leery of giving people the impression "lol rust allocates its stack on the HEAP? nah I'll go back to a real lang like c++ thx".

[thestinger]

On the other hand, the "heap vs. stack" dichotomy, imagined or not, is quite popular. I'm leery of giving people the impression "lol rust allocates its stack on the HEAP? nah I'll go back to a real lang like c++ thx".

You've put forward an argument against a different proposal than the one here. The term heap should be completely removed from the documentation because it distracts from the high level semantics and doesn't actually have a basis in reality. Rust doesn't use the data section referred to as the heap (dss) for either stacks or dynamic memory allocations. The dss section only exists for legacy reasons anyway.

[thestinger]

C and C++ don't mention the terms stack or heap at all. The language and library APIs are defined in terms of the high level semantics and the low-level details are left to the implementation. Those low-level details do not really include a distinction between dynamic allocations of stacks for new threads and other dynamic allocations.

[arielb1]

While I agree that a C-style language specification, if there was such a document, shouldn't talk about "the stack" and "the heap", the former is a significant component of almost all ABI-s, being the scratch space given to functions, and "heap" is just the short term for "memory managed by the process-global dynamic allocator" (I haven't seen anyone really claim that "the heap" means "the dss section"), so these are terms low-level developers are familiar with, and documentation aimed at these developers should talk about how Rust uses them.

[thestinger]

@arielb1: Stacks are dynamic allocations and come from the same OS API as other memory allocations. The usage of an allocator in between these allocations and the OS API is an implementation detail that's likely going to change soon. It doesn't make sense for Rust to call mmap and munmap directly or allow the POSIX thread API to call it because it increases memory fragmentation and decreases performance. It really only needs to deal directly with mprotect.

[thestinger]

are terms low-level developers are familiar with, and documentation aimed at these developers should talk about how Rust uses them

General purpose documentation should concentrate on semantics, not implementation details. Documentation of the implementation details or performance characteristics has no use case for familiar but inaccurate ways of describing the functionality.

[thestinger]

I haven't seen anyone really claim that "the heap" means "the dss section"

The term isn't used by C and C++ themselves because it's a platform-specific implementation detail. That's how the heap is defined by the Linux kernel and the userspace documentation. The way Rust's documentation uses the term is inaccurate, misleading and confusing. If you want to talk about implementation details, then lying about how it actually works isn't a great start.

For example, the glibc malloc implementation has a MMAP_THRESHOLD variable which it describes as the threshold where it switches from the heap (dss) to anonymous mappings. Rust uses anonymous mappings for all memory allocations.

[arielb1]

@thestinger

Of course, both the stack, the heap, static allocation, and manually mmaped zones are all regions of virtual memory that are used in the same way.

However, from within a function, memory from these areas certainly isn't allocated from the same API-s – stack allocations are a pointer bump, heap allocations are function calls, arena allocations via different function calls (which may eventually allocate from other regions) etc. (inside a function, there is also memory accessible via a reference, which can come from anywhere without the function needing to know about it).

Also, the MMAP_THRESHOLD documentation (at man 3 mallopt) does not really talk about heap=dss≠mmap (What it does talk about is the fact that over-threshold allocations aren't on the free-list, but that's a distinct concern, and also with glibc the free-list manages the dss segment, and mallopt is where implementation details are exposed).

[thestinger]

@arielb1: The documentation is quite clear that sbrk manages the heap, and it's explicitly referred to as [heap] in /proc/self/maps and elsewhere.

Normally, malloc() allocates memory from the heap, and adjusts the size of the heap as required, using sbrk(2). When allocating blocks of memory larger than MMAP_THRESHOLD bytes, the glibc malloc() implementation allocates the memory as a private anonymous mapping using mmap(2).

[thestinger]

However, from within a function, memory from these areas certainly isn't allocated from the same API-s – stack allocations are a pointer bump, heap allocations are function calls, arena allocations via different function calls (which may eventually allocate from other regions) etc. (inside a function, there is also memory accessible via a reference, which can come from anywhere without the function needing to know about it).

You're conflating the usage pattern of the memory after it's allocated with obtaining the memory allocation. Putting local variables on the stack or pushing elements to a vector with reserved capacity is not a memory allocation. The stack itself is a dynamic memory allocation and the call stack manages that memory as a stack data structure.

[thestinger]

Also, the MMAP_THRESHOLD documentation (at man 3 mallopt) does not really talk about heap=dss≠mmap (What it does talk about is the fact that over-threshold allocations aren't on the free-list, but that's a distinct concern, and also with glibc the free-list manages the dss segment, and mallopt is where implementation details are exposed).

The documentation is incredibly clear that there's a distinction between the heap (managed by sbrk) and anonymous memory mappings from mmap. It's difficult for me to understand where you're coming from when the language in the documentation is so clear about the distinction.

Allocating memory using mmap(2) has the significant advantage that the allocated memory blocks can always be independently released back to the system. (By contrast, the heap can be trimmed only if memory is freed at the top end.)

Another case where the term "heap" is mentioned:

When the amount of contiguous free memory at the top of the heap grows sufficiently large, free(3) employs sbrk(2) to release this memory back to the system.

Or just look in /proc/self/maps along with the Linux kernel API documentation / code and you'll see that mmap mappings != heap.

[thestinger]

What it does talk about is the fact that over-threshold allocations aren't on the free-list, but that's a distinct concern, and also with glibc the free-list manages the dss segment

This isn't true. It uses free lists for more than just managing memory in the heap (dss) because it will make secondary arenas with mmap and they aren't subject to trimming.

[arielb1]

I got this distinction from musl libc, which manages the malloc heap entirely with mmap, and also allocates large blocks in separately mmap-ed areas (for some not-particularly-clear reason, it adds a header to these large blocks, ensuring misalignment and wasted pages – but glibc also seems to do it), which are never stored on a free list, but rather free-d immediately.