RFC: Allocator trait

active/0000-allocator-trait.md

@@ -0,0 +1,185 @@
+- Start Date: 2014-04-07
+- RFC PR #: (leave this empty)
+- Rust Issue #: (leave this empty)
+
+# Summary
+
+Rust is in need of a trait to generalize low-level memory allocators. This will enable a pluggable
+default allocator, along with the possibility of supporting per-container allocators with the option
+of statefulness.
+
+# Motivation
+
+Modern general purpose allocators are quite good, but need to make many design tradeoffs. There is
+no "best" global allocator so it should be a configurable feature of the standard library. In order
+for this to happen, an allocator interface needs to be defined.
+
+Some applications may also have a use case for cache aligned nodes with concurrent data structures
+to avoid contention, or very fast naive allocators (like a bump allocator) shared between data
+structures with related lifetimes.
+
+The basic `malloc`, `realloc` and `free` interface is quite lacking, since it's missing alignment
+and the ability to obtain an allocation's size. In order to have good support an alignment
+specification on types, it needs to be possible for types like `Vec<T>` to ask the allocator for an
+alignment.  This can be done inefficiently by building a wrapper around the `malloc` API, but many
+allocators have efficient support for this need built-in.
+
+# Detailed design
+
+Trait design:
+
+```rust
+pub trait Allocator {
+    /// Return a pointer to `size` bytes of memory.
+    ///
+    /// A null pointer may be returned if the allocation fails.
+    ///
+    /// Behavior is undefined if the requested size is 0 or the alignment is not a power of 2. The
+    /// alignment must be no larger than the largest supported page size on the platform.
+    unsafe fn alloc(&self, size: uint, align: u32) -> *mut u8;
+
+    /// Extend or shrink the allocation referenced by `ptr` to `size` bytes of memory.
+    ///
+    /// A null pointer may be returned if the allocation fails and the original memory allocation
+    /// will not be altered.
+    ///
+    /// Behavior is undefined if the requested size is 0 or the alignment is not a power of 2. The
+    /// alignment must be no larger than the largest supported page size on the platform.
+    ///
+    /// The `old_size` and `align` parameters are the parameters that were used to create the
+    /// allocation referenced by `ptr`. The `old_size` parameter may also be the value returned by
+    /// `usable_size` for the requested size.
+    unsafe fn realloc(&self, ptr: *mut u8, size: uint, align: u32, old_size: uint) -> *mut u8;
+
+    /// Deallocate the memory referenced by `ptr`.
+    ///
+    /// The `ptr` parameter must not be null.
+    ///
+    /// The `size` and `align` parameters are the parameters that were used to create the
+    /// allocation referenced by `ptr`. The `size` parameter may also be the value returned by
+    /// `usable_size` for the requested size.
+    unsafe fn dealloc(&self, ptr: *mut u8, size: uint, align: u32);
+
+    /// Return the usable size of an allocation created with the specified the `size` and `align`.
+    #[inline(always)]
+    #[allow(unused_variable)]
+    unsafe fn usable_size(&self, size: uint, align: u32) -> uint { size }
+}
+```
+
+The trait takes an `align` parameter alongside every `size` parameter in order to support large
+alignments without overhead for all allocations. For example, aligned AVX/AVX-512 vectors,
+cache-aligned memory for concurrent data structures or page-aligned memory for working with
+hardware.
+
+The `usable_size` method provides a way of asking for the real size/alignment the allocator will
+produce for a specific request. While it is possible for the `alloc` and `realloc` methods to
+return this dynamically, it adds complexity and does not seem to have a use case. There is no
+reason for it to return an alignment, since the dynamic alignment information is trivially
+obtainable from any pointer.
+
+The `realloc` and `dealloc` methods require passing in the size and alignment of the existing memory
+allocation. The alignment should be a known constant, so this will not place a burden on the caller.
+The *guarantee* of having a size permits much more optimization than simply *sometimes* being passed
+a size. It allows simple allocators to forgo storing a size altogether. For example, this permits an
+implementation of a free list for variable size types without metadata overhead. C++ allocators use
+this design, with the `deallocate` method always taking a size parameter.
+
+It is left up to the caller to choose how to handle zero-size allocations, such as the current
+wrapping done by the `rt::global_heap` allocator. Allocators like jemalloc do not provide a
+guarantee here, and some callers may want a null pointer while others will want a non-null
+sentinel pointing at a global.
+
+The alignment is given a reasonable restriction, by capping it at the largest huge page size on
+the system. It should never be dynamic, so this is easily satisfiable. This is to meet the
+requirement of allocators like jemalloc for the alignment to be satisfiable without overflow while
+still meeting every use case. It is given as 32-bit because LLVM uses a 32-bit integer for
+alignment.
+
+Sample default allocator:
+
+```rust
+extern crate libc;
+
+use std::intrinsics::cttz32;
+use libc::{c_int, c_void, size_t};
+
+#[link(name = "jemalloc")]
+extern {
+    fn nallocx(size: size_t, flags: c_int) -> size_t;
+    fn mallocx(size: size_t, flags: c_int) -> *mut c_void;
+    fn rallocx(ptr: *mut c_void, size: size_t, flags: c_int) -> *mut c_void;
+    fn dallocx(ptr: *mut c_void, flags: c_int);
+}
+
+pub struct DefaultAllocator;
+
+// MALLOCX_ALIGN(a) macro
+fn mallocx_align(a: u32) -> c_int { unsafe { cttz32(a as i32) as c_int } }
+
+impl Allocator for DefaultAllocator {
+    unsafe fn alloc(&self, size: uint, align: u32) -> *mut u8 {
+        mallocx(size as size_t, mallocx_align(align)) as *mut u8
+    }
+
+    unsafe fn realloc(&self, ptr: *mut u8, size: uint, align: u32, _: uint) -> *mut u8 {
+        rallocx(ptr as *mut c_void, size as size_t, mallocx_align(align)) as *mut u8
+    }
+
+    unsafe fn dealloc(&self, ptr: *mut u8, _: uint, align: u32) {
+        dallocx(ptr as *mut c_void, mallocx_align(align))
+    }
+
+    #[inline(always)]
+    unsafe fn usable_size(&self, size: uint, align: u32) -> uint {
+        nallocx(size as size_t, mallocx_align(align)) as uint
+    }
+}
+
+pub static default: DefaultAllocator = DefaultAllocator;
+```
+
+# Alternatives
+
+## Zeroed memory
+
+The `Allocator` trait does not provide a way to ask for zeroed memory.  Allocators based on
+mmap/mremap already pay this cost for large allocations but the tide is likely going to shift to
+new underlying APIs like the Linux vrange work. This optimization (`calloc`) is not currently
+used by anything in Rust, as it's quite hard to fit it into any generic code.
+
+The `alloc` and `realloc` functions could take a `zero: bool` parameter for leveraging the guarantee
+provided by functions like `mmap` and `mremap`. It would be possible to add support for this in an
+almost completely backwards compatible way by adding two new default methods with the parameter.
+
+## Sized reallocation/deallocation
+
+The old size passed to `realloc` and `dealloc` is an optional performance enhancement. There is some
+debate about whether this is worth having. I have included it because there is no drawback within
+the current language and standard libraries, so it's an obvious performance enhancement.
+
+In a future version of Rust, `~[T]` will be an owned slice stored as `(ptr, len)`. Converting from
+an owned slice to a `Vec<T>` will be a no-op. However, conversion from `Vec<T>` to `~[T]` can not be
+free due to the Option-like `enum` optimization for non-nullable pointers. There is a choice between
+calling `free` on zero-size allocations during the conversion, or branching in every `~[T]`
+destructor based on a comparison with the reserved sentinel address. If `dealloc` requires a size, a
+`shrink_to_fit()` call will be the minimum requirement.
+
+The niche for `~[T]` is not yet known, so it would be premature to sacrifice performance relative to
+C++ allocators to optimize one aspect of it. A vector should be left as `Vec<T>` to avoid losing
+track of excess capacity, and except in recursive data structures there is little cost for the
+capacity field.
+
+## Alignment parameter
+
+This parameter is required to be a power of 2, so it could take `log2(alignment)` instead. Either
+way, the standard library is going to need to expose a convenience function for retrieving this for
+a specific type.
+
+# Unresolved questions
+
+The finer details of the API for allocator support in containers is beyond the scope of this RFC. It
+only aims to define the `Allocator` trait for making Rust's default allocator configurable and
+building the foundation for containers. A sample design would be `Vec<T, A = DefaultAllocator>` with
+extra static methods taking an *instance* of the allocator type in order to support stateful
+allocators.