Rust's core allocation library

This is the lowest level library through which allocation in Rust can be performed where the allocation is assumed to succeed. This library will trigger a task failure when allocation fails.

This library, like libcore, is not intended for general usage, but rather as a building block of other libraries. The types and interfaces in this library are reexported through the standard library, and should not be used through this library.

Currently, there are four major definitions in this library.

Owned pointers

The Box type is the core owned pointer type in rust. There can only be one owner of a Box, and the owner can decide to mutate the contents.

This type can be sent among tasks efficiently as the size of a Box value is just a pointer. Tree-like data structures are often built on owned pointers because each node often has only one owner, the parent.

Reference counted pointers

The Rc type is a non-threadsafe reference-counted pointer type intended for sharing memory within a task. An Rc pointer wraps a type, T, and only allows access to &T, a shared reference.

This type is useful when inherited mutability is too constraining for an application (such as using Box), and is often paired with the Cell or RefCell types in order to allow mutation.

Atomically reference counted pointers

The Arc type is the threadsafe equivalent of the Rc type. It provides all the same functionality of Rc, except it requires that the contained type T is shareable. Additionally, Arc<T> is itself sendable while Rc<T> is not.

This types allows for shared access to the contained data, and is often paired with synchronization primitives such as mutexes to allow mutation of shared resources.

Heap interfaces

The heap and libc_heap modules are the unsafe interfaces to the underlying allocation systems. The heap module is considered the default heap, and is not necessarily backed by libc malloc/free. The libc_heap module is defined to be wired up to the system malloc/free.