Repository files navigation

Ferroc (combined from "ferrum" and "malloc") is a lock-free concurrent memory allocator written in Rust, primarily inspired bymimalloc.

This memory allocator is designed to work as fast as other mainstream memory allocators while providing flexible configurations such as embedded/bare-metal environment integrations.

If you simply want to utilize another memory allocator, you can use Ferroc as the global allocator with default features:

use ferroc::Ferroc;#[global_allocator]staticFERROC:Ferroc =Ferroc;fnmain(){// Using the global allocator API.let _vec =vec![10;100];// Manually allocate memory.let layout = std::alloc::Layout::new::<u8>();let ptr =Ferroc.allocate(layout).unwrap();unsafe{Ferroc.deallocate(ptr, layout)};// Immediately run some delayed clean-up operations.Ferroc.collect(/* force */false);}

If you want more control over the allocator, you can disable the default features and enable the ones you need:

ferroc = {version ="*",default-features =false,features = ["base-mmap"]}

#![feature(allocator_api)]use core::pin::pin;use ferroc::{    arena::Arenas,    heap::{Heap,Context},    base::Mmap,};fnmain(){let arenas =Arenas::new(Mmap);// `Arenas` are `Send` & `Sync`...let cx =pin!(Context::new(&arenas));let heap =Heap::new(cx.as_ref());// ...while `Context`s and `Heap`s are not.// Using the allocator API.letmut vec =Vec::new_in(&heap);    vec.extend([1,2,3,4]);assert_eq!(vec.iter().sum::<i32>(),10);// Manually allocate memory.let layout = std::alloc::Layout::new::<u8>();let ptr = heap.allocate(layout).unwrap();unsafe{ heap.deallocate(ptr.cast(), layout)}.unwrap();// Immediately run some delayed clean-up operations.    heap.collect(/* force */false);}

• Basic features: genericArenas,Contexts andHeaps;
• "base-static": Base allocatorStatic;
• "base-mmap": Base allocatorMmap based on os-specific virtual memory managers (std andlibc required);
• "global": Global allocator instantiation macrosconfig! andconfig_mod! (inner thread local statics are leaked by default);
• "libc":libc dependency (currently required bypthread option inconfig*! if you want apthread thread-local destructor);
• "default": The default global allocatorFerroc provided byMmap andpthread thread-local destructor (consisting of all the features above);
• "c":fe_* C functions for C/C++ targets;
• "c-bindgen": A generated C/C++ header"ferroc.h" in the root directory;
• "c-override": Override default allocator functions such asmalloc/free andoperator new/delete, which can be useful for embedding Ferroc in a C/C++ project (seethis section for more details);
• "track-valgrind": Valgrind memory tracking support based oncrabgrind, which requires Valgrind's version of at least 3.22;
• "finer-grained": Add more object size types to small bins, decreasing fragmentation but also the minimal alignment from 16 to 8, potentially leading some programs that need SIMD to fail for misalignment.

There are several additional configurations that can be set via environment variables to control the behavior of Ferroc:

• FE_SLAB_SHIFT: Set the slab size (in bits) for all the data structures, a.k.a. the minimal allocation unit of arenas. Default is 22.
• FE_SHARD_SHIFT: Set the shard size (in bits) for all the data structures, a.k.a. the minimal allocation unit of slabs. Default is 16.

Those configurations are not exported as cargo features due to the requirement of additiveness.

1. Download and install the latest nightly Rust toolchain:

curl --proto'=https' --tlsv1.2 -sSf https://sh.rustup.rs|\    sh -- -y --toolchain nightly --profile minimal -c rust-src

2. Justcmake andmake it:

mkdir target&&cd target# Required to be `target`. Don't change it to `build` or other names.cmake ..&& make

3. If you want to install the library:

sudo make install

Common options like--install-prefix and--config are supported naturally by CMake.

There are also some custom options (viacmake -D) you can enable:

• FE_TRACK_VALGRIND: See"track-valgrind" above;
• FE_FINER_GRAINED: See"finer-grained" above.
• FE_PGO_GATHER: Enable PGO (Profile-Guided Optimization) gathering.
• FE_PGO_USE: Build with optimization from pre-gathered PGO data (which requires appending llvm-tools to the second line of step 1).

Additionally, environment variables (seethe section above) can also be used to control the build.

Using a subset ofmimalloc-bench for benchmarking. Running on my laptop with 16GB of RAM and an Intel i7-10750H CPU @ 2.60GHz. The process is repeated 10 times.

Time consumed:

Memory consumed:

This crate only supports the latest nightly Rust compiler currently and utilizes many unstable features. Use it with care.

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.