Struct std::alloc::System

[+] Show declaration

pub struct System;

[−] Expand description

The default memory allocator provided by the operating system.

This is based on malloc on Unix platforms and HeapAlloc on Windows, plus related functions.

This type implements the GlobalAlloc trait and Rust programs by default work as if they had this definition:

use std::alloc::System;

#[global_allocator]
static A: System = System;

fn main() {
    let a = Box::new(4); // Allocates from the system allocator.
    println!("{}", a);
}

You can also define your own wrapper around System if you'd like, such as keeping track of the number of all bytes allocated:

use std::alloc::{System, GlobalAlloc, Layout};
use std::sync::atomic::{AtomicUsize, Ordering::SeqCst};

struct Counter;

static ALLOCATED: AtomicUsize = AtomicUsize::new(0);

unsafe impl GlobalAlloc for Counter {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        let ret = System.alloc(layout);
        if !ret.is_null() {
            ALLOCATED.fetch_add(layout.size(), SeqCst);
        }
        return ret
    }

    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        System.dealloc(ptr, layout);
        ALLOCATED.fetch_sub(layout.size(), SeqCst);
    }
}

#[global_allocator]
static A: Counter = Counter;

fn main() {
    println!("allocated bytes before main: {}", ALLOCATED.load(SeqCst));
}

It can also be used directly to allocate memory independently of whatever global allocator has been selected for a Rust program. For example if a Rust program opts in to using jemalloc as the global allocator, System will still allocate memory using malloc and HeapAlloc.

Trait Implementations

impl Copy for System

impl Debug for System[+]

[+] Show hidden undocumented items

fn fmt(&self, f: &mut Formatter) -> Result[−]

Formats the value using the given formatter.

impl Clone for System[+]

[+] Show hidden undocumented items

fn clone(&self) -> System[−]

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)[−]

Performs copy-assignment from source.

impl Default for System[+]

[+] Show hidden undocumented items

fn default() -> System[−]

Returns the "default value" for a type.

impl GlobalAlloc for System[+]

[+] Show hidden undocumented items

unsafe fn alloc(&self, layout: Layout) -> *mut u8[−]

Allocate memory as described by the given layout.

unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8[−]

Behaves like alloc, but also ensures that the contents are set to zero before being returned.

unsafe fn dealloc(&self, ptr: *mut u8, _layout: Layout)[−]

Deallocate the block of memory at the given ptr pointer with the given layout.

unsafe fn realloc(
    &self,
    ptr: *mut u8,
    layout: Layout,
    new_size: usize
) -> *mut u8[−]

Shrink or grow a block of memory to the given new_size. The block is described by the given ptr pointer and layout.

impl Alloc for System[+]

[+] Show hidden undocumented items

unsafe fn alloc(&mut self, layout: Layout) -> Result<NonNull<u8>, AllocErr>[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Returns a pointer meeting the size and alignment guarantees of layout.

unsafe fn alloc_zeroed(
    &mut self,
    layout: Layout
) -> Result<NonNull<u8>, AllocErr>[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Behaves like alloc, but also ensures that the contents are set to zero before being returned.

unsafe fn dealloc(&mut self, ptr: NonNull<u8>, layout: Layout)[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Deallocate the memory referenced by ptr.

unsafe fn realloc(
    &mut self,
    ptr: NonNull<u8>,
    layout: Layout,
    new_size: usize
) -> Result<NonNull<u8>, AllocErr>[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Returns a pointer suitable for holding data described by a new layout with layout’s alignment and a size given by new_size. To accomplish this, this may extend or shrink the allocation referenced by ptr to fit the new layout.

fn usable_size(&self, layout: &Layout) -> (usize, usize)[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Returns bounds on the guaranteed usable size of a successful allocation created with the specified layout.

unsafe fn alloc_excess(&mut self, layout: Layout) -> Result<Excess, AllocErr>[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Behaves like alloc, but also returns the whole size of the returned block. For some layout inputs, like arrays, this may include extra storage usable for additional data.

unsafe fn realloc_excess(
    &mut self,
    ptr: NonNull<u8>,
    layout: Layout,
    new_size: usize
) -> Result<Excess, AllocErr>[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Behaves like realloc, but also returns the whole size of the returned block. For some layout inputs, like arrays, this may include extra storage usable for additional data.

unsafe fn grow_in_place(
    &mut self,
    ptr: NonNull<u8>,
    layout: Layout,
    new_size: usize
) -> Result<(), CannotReallocInPlace>[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Attempts to extend the allocation referenced by ptr to fit new_size.

unsafe fn shrink_in_place(
    &mut self,
    ptr: NonNull<u8>,
    layout: Layout,
    new_size: usize
) -> Result<(), CannotReallocInPlace>[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Attempts to shrink the allocation referenced by ptr to fit new_size.

fn alloc_one<T>(&mut self) -> Result<NonNull<T>, AllocErr>[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Allocates a block suitable for holding an instance of T.

unsafe fn dealloc_one<T>(&mut self, ptr: NonNull<T>)[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Deallocates a block suitable for holding an instance of T.

fn alloc_array<T>(&mut self, n: usize) -> Result<NonNull<T>, AllocErr>[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Allocates a block suitable for holding n instances of T.

unsafe fn realloc_array<T>(
    &mut self,
    ptr: NonNull<T>,
    n_old: usize,
    n_new: usize
) -> Result<NonNull<T>, AllocErr>[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Reallocates a block previously suitable for holding n_old instances of T, returning a block suitable for holding n_new instances of T.

unsafe fn dealloc_array<T>(
    &mut self,
    ptr: NonNull<T>,
    n: usize
) -> Result<(), AllocErr>[−]

🔬 This is a nightly-only experimental API. (allocator_api #32838)

Deallocates a block suitable for holding n instances of T.