Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/js2xxx/ferroc

A lock-free memory allocator
https://github.com/js2xxx/ferroc

allocator malloc memory rust

Last synced: 2 months ago
JSON representation

A lock-free memory allocator

Awesome Lists containing this project

README 

        
# Ferroc: A Multithread Lock-free Memory Allocator



[![Build Status](https://img.shields.io/github/actions/workflow/status/js2xxx/ferroc/basic.yml?style=for-the-badge)](https://github.com/js2xxx/ferroc/actions)

[![Cargo](https://img.shields.io/crates/v/ferroc?style=for-the-badge)](https://crates.io/crates/ferroc)

[![Coverage](https://img.shields.io/codecov/c/github/js2xxx/ferroc?style=for-the-badge)](https://codecov.io/gh/js2xxx/ferroc)

[![Documentation](https://img.shields.io/docsrs/ferroc?style=for-the-badge)](https://docs.rs/ferroc)

[![License](https://img.shields.io/crates/l/ferroc?style=for-the-badge)](https://github.com/js2xxx/ferroc)



Ferroc (combined from "ferrum" and "malloc") is a lock-free concurrent memory allocator written in Rust, primarily inspired by [`mimalloc`](https://github.com/microsoft/mimalloc).



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.



## Examples



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



```rust

use ferroc::Ferroc;



#[global_allocator]

static FERROC: Ferroc = Ferroc;



fn main() {

    // Using the global allocator API.

    let _vec = vec![10; 100];



    // Manually allocate memory.

    let layout = std::alloc::Layout::new::();

    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:



```toml

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

```



```rust

#![feature(allocator_api)]



use core::pin::pin;

use ferroc::{

    arena::Arenas,

    heap::{Heap, Context},

    base::Mmap,

};



fn main() {

    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.

    let mut vec = Vec::new_in(&heap);

    vec.extend([1, 2, 3, 4]);

    assert_eq!(vec.iter().sum::(), 10);



    // Manually allocate memory.

    let layout = std::alloc::Layout::new::();

    let ptr = heap.allocate(layout).unwrap();

    unsafe { heap.deallocate(ptr.cast(), layout) }.unwrap();



    // Immediately run some delayed clean-up operations.

    heap.collect(/* force */false);

}

```



## Cargo Features



- Basic features: generic `Arenas`, `Context`s and `Heap`s;

- `"base-static"`: Base allocator `Static`;

- `"base-mmap"`: Base allocator `Mmap` based on os-specific virtual memory managers (`std` and `libc` required);

- `"global"`: Global allocator instantiation macros `config!` and `config_mod!` (inner thread local statics are leaked by default);

- `"libc"`: `libc` dependency (currently required by `pthread` option in `config*!` if you want a `pthread` thread-local destructor);

- `"default"`: The default global allocator `Ferroc` provided by `Mmap` and `pthread` 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 as `malloc/free` and `operator new/delete`, which can be useful for embedding Ferroc in a C/C++ project (see [this section](#building-process-for-cc-users) for more details);

- `"track-valgrind"`: Valgrind memory tracking support based on [`crabgrind`](https://github.com/2dav/crabgrind), 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.



## Environment variables



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.



## Building process for CMake users



1. Download and install the latest nightly Rust toolchain:



```bash

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs |\

    sh -- -y --toolchain nightly --profile minimal -c rust-src

```



2. Just `cmake` and `make` it:



```bash

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:



```bash

sudo make install

```



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



There are also some custom options (via `cmake -D`) you can enable:



- `FE_TRACK_VALGRIND`: See [`"track-valgrind"`](#cargo-features) above;

- `FE_FINER_GRAINED`: See [`"finer-grained"`](#cargo-features) 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 (see [the section above](#environment-variables)) can also be used to control the build.



## Benchmarks



Using a subset of [`mimalloc-bench`](https://github.com/daanx/mimalloc-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:



![Time consumed #1](./assets/time1.png)

![Time consumed #2](./assets/time2.png)



Memory consumed:



![Memory consumed #1](./assets/memory1.png)

![Memory consumed #2](./assets/memory2.png)



## Caveats



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



### License



Licensed under either of



* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))

* MIT license ([LICENSE-MIT](LICENSE-MIT))



at your option.