embarkstudios / rpmalloc-rs

🐏 rpmalloc global memory allocator for Rust 🦀

🐏 rpmalloc-rs

Cross-platform Rust global memory allocator using rpmalloc.

Overview

See the rpmalloc README for a detailed description of how the allocator works, peforms, and compares with other allocators.

How to use

To use rpmalloc as the global allocator in your Rust binary crate, in Cargo.toml add:

[dependencies]
rpmalloc = "0.2.0"

And then in one of your .rs files:

#[global_allocator]
static ALLOC: rpmalloc::RpMalloc = rpmalloc::RpMalloc;

Configuration

It is also possible to configure how the allocator should be built through a set of feature flags that correspond to the rpmalloc C library ENABLE_x defines:

• Overall: statistics, validate_args, asserts, guards
• Cache: unlimited_cache, unlimited_global_cache, unlimited_thread_cache, global_cache, thread_cache, adaptive_thread_cache

Example usage:

[dependencies]
rpmalloc = { version = "0.2.0", features = ["guards", "statistics"] }

See rpmalloc README for detailed descriptions of the config options.

Note that all of these have not been tested together with this Rust crate.

Support

This crate has been tested to support the following platforms and Rust targets:

• x86_64-pc-windows-msvc
• x86_64-apple-darwin
• x86_64-unknown-linux-gnu

PRs to increase the amount of supported targets are welcome, but they should add CI verification and avoid adding additional dependencies.

Contributing

We welcome community contributions to this project.

Please read our Contributor Guide for more information on how to get started.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Note that the rpmalloc library this crate uses is under public domain, and can also be licensed under MIT.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

rpmalloc-rs's Issues

Compilation issue on ARM64 on Windows

I've submitted a fix-PR upstream here mjansson/rpmalloc#324 just making this issue so we can track this on this repo as well since that's how I ended up running into this in the first place.

Add support for ENABLE_OVERRIDE

To enable rpmalloc's overriding of C malloc/free functions, this enables rpmalloc to be used instead of the system allocator for C/C++ code dependencies as well, not just for Rust code.

Easy to enable (and should be a feature flag on the crates) but do have to make sure it links properly on all platforms and targets.

Configuration options as feature flags

rpmalloc supports quite a few defines to configure the cache behavior and other settings, would be nice to expose the relevant ones through feature flags on the crates.

Cache configuration options

Free memory pages are cached both per thread and in a global cache for all threads. The size of the thread caches is determined by an adaptive scheme where each cache is limited by a percentage of the maximum allocation count of the corresponding size class. The size of the global caches is determined by a multiple of the maximum of all thread caches. The factors controlling the cache sizes can be set by editing the individual defines in the rpmalloc.c source file for fine tuned control.

ENABLE_UNLIMITED_CACHE: By default defined to 0, set to 1 to make all caches infinite, i.e never release spans to global cache unless thread finishes and never unmap memory pages back to the OS. Highest performance but largest memory overhead.

ENABLE_UNLIMITED_GLOBAL_CACHE: By default defined to 0, set to 1 to make global caches infinite, i.e never unmap memory pages back to the OS.

ENABLE_UNLIMITED_THREAD_CACHE: By default defined to 0, set to 1 to make thread caches infinite, i.e never release spans to global cache unless thread finishes.

ENABLE_GLOBAL_CACHE: By default defined to 1, enables the global cache shared between all threads. Set to 0 to disable the global cache and directly unmap pages evicted from the thread cache.

ENABLE_THREAD_CACHE: By default defined to 1, enables the per-thread cache. Set to 0 to disable the thread cache and directly unmap pages no longer in use (also disables the global cache).

ENABLE_ADAPTIVE_THREAD_CACHE: Introduces a simple heuristics in the thread cache size, keeping 25% of the high water mark for each span count class.

Other configuration options

Detailed statistics are available if ENABLE_STATISTICS is defined to 1 (default is 0, or disabled), either on compile command line or by setting the value in rpmalloc.c. This will cause a slight overhead in runtime to collect statistics for each memory operation, and will also add 4 bytes overhead per allocation to track sizes.

Integer safety checks on all calls are enabled if ENABLE_VALIDATE_ARGS is defined to 1 (default is 0, or disabled), either on compile command line or by setting the value in rpmalloc.c. If enabled, size arguments to the global entry points are verified not to cause integer overflows in calculations.

Asserts are enabled if ENABLE_ASSERTS is defined to 1 (default is 0, or disabled), either on compile command line or by setting the value in rpmalloc.c.

Overwrite and underwrite guards are enabled if ENABLE_GUARDS is defined to 1 (default is 0, or disabled), either on compile command line or by settings the value in rpmalloc.c. This will introduce up to 64 byte overhead on each allocation to store magic numbers, which will be verified when freeing the memory block. The actual overhead is dependent on the requested size compared to size class limits.

Update to v0.3 of Embark's standard lints

Embark uses a standard set of lints across all repositories. We just upgraded
to version 0.3 of these lints, and this repository needs to be updated to
the new set of lints with any warnings fixed.

Steps

1. Copy the contents of the lints.rs file from
   EmbarkStudios/rust-ecosystem and replace the old list of lints in the
   src/lib.rs and/or src/main.rs files with the new list.
2. Run cargo clippy
3. Update and fix any code that now triggers a new warning.

Update to use latest upstream release version 1.4.4?

Hey, I'd like to say thank for creating this crate in the first place. :)

That said, it seems this crate is getting out of sync from the upstream rpmalloc release a bit?:

https://github.com/mjansson/rpmalloc/releases/tag/1.4.4

I'd take the blame of being that guy to nudge busy you... But is there any possibility for the update of this crate or would such pr be accepted from community timely if i did?

A bit of context is that it seems that rpmalloc is certainly fast as talked elsewhere in the case of our workload as well. So, I'm in the process of evaluating it and just want to use the latest and greatest one.

Heap grows linearly over time / the allocator seems to leak memory

When I use rpmalloc as global allocator, my application seems to allocate increasingly more memory linearly, aka it doesn't free memory when it should:

(And it grows further as time goes on..)

I'm not sure if this is intended to behave this way, but I think it can't be.
My application is very cyclic (frame-based), each frame uses the same types of same sizes that are allocated, thus it can't be that this linearly increasing allocation pattern is caused by allocating too many different sized blocks.

For comparison, when I don't use rpmalloc, but the default system allocator, the heap usage stays bounded, below like 80 MB:

This is on Win 8.1 btw.
The only change between both runs is that for the second one I removed this:

#[global_allocator]
static ALLOC: rpmalloc::RpMalloc = rpmalloc::RpMalloc;

rpmalloc-sys fails to build for wasm target on Windows: fatal error: 'unistd.h' file not found

Not sure if this allocator is intended to also work for wasm, but in my frontend I need speed more than size (it's a UI for a desktop application), so I thought I'd try it..
But it fails to build for wasm:

error: failed to run custom build command for `rpmalloc-sys v0.1.3`

--- stdout
TARGET = Some("wasm32-unknown-unknown")
HOST = Some("x86_64-pc-windows-msvc")
CC_wasm32-unknown-unknown = None
CC_wasm32_unknown_unknown = None
TARGET_CC = None
CC = None
CFLAGS_wasm32-unknown-unknown = None
CFLAGS_wasm32_unknown_unknown = None
TARGET_CFLAGS = None
CFLAGS = None
CRATE_CC_NO_DEFAULTS = None
DEBUG = Some("true")
running: "clang" "-O2" "-ffunction-sections" "-fdata-sections" "-fPIC" "-g" "-fno-omit-frame-pointer" "--target=wasm32-unknown-unknown" "-Wall" "-Wextra" "-DENABLE_PRELOAD=1" "-o" "D:\\project\\target\\wasm32-unknown-unknown\\debug\\build\\rpmalloc-sys-21068dcc5b7ecde5\\out\\rpmalloc.o" "-c" "C:\\Users\\me\\.cargo\\registry\\src\\github.com-1ecc6299db9ec823\\rpmalloc-sys-0.1.3\\rpmalloc\\rpmalloc\\rpmalloc.c"
cargo:warning=C:\Users\me\.cargo\registry\src\github.com-1ecc6299db9ec823\rpmalloc-sys-0.1.3\rpmalloc\rpmalloc\rpmalloc.c:122:12: fatal error: 'unistd.h' file not found
cargo:warning=#  include <unistd.h>
cargo:warning=           ^~~~~~~~~~
cargo:warning=1 error generated.
exit code: 1

--- stderr


error occurred: Command "clang" "-O2" "-ffunction-sections" "-fdata-sections" "-fPIC" "-g" "-fno-omit-frame-pointer" "--target=wasm32-unknown-unknown" "-Wall" "-Wextra" "-DENABLE_PRELOAD=1" "-o" "D:\\project\\target\\wasm32-unknown-unknown\\debug\\build\\rpmalloc-sys-21068dcc5b7ecde5\\out\\rpmalloc.o" "-c" "C:\\Users\\me\\.cargo\\registry\\src\\github.com-1ecc6299db9ec823\\rpmalloc-sys-0.1.3\\rpmalloc\\rpmalloc\\rpmalloc.c" with args "clang" did not execute successfully (status code exit code: 1).

Link issue on Windows

Currently running into some link issues with the malloc hooking which we should investigate and fix.

These are the link errors one gets. Happens both with LLD and MSVC's linker:

         lld-link: error: duplicate symbol: calloc in librpmalloc_sys-6320f0a329f3e257.rlib(rpmalloc.o) and in api-ms-win-crt-heap-l1-1-0.dll
         lld-link: error: duplicate symbol: free in librpmalloc_sys-6320f0a329f3e257.rlib(rpmalloc.o) and in api-ms-win-crt-heap-l1-1-0.dll
         lld-link: error: duplicate symbol: malloc in librpmalloc_sys-6320f0a329f3e257.rlib(rpmalloc.o) and in api-ms-win-crt-heap-l1-1-0.dll
         lld-link: error: duplicate symbol: realloc in librpmalloc_sys-6320f0a329f3e257.rlib(rpmalloc.o) and in api-ms-win-crt-heap-l1-1-0.dll

Upgrade to rpmalloc 1.4.1

https://github.com/mjansson/rpmalloc/releases/tag/1.4.1

Add support for aarch64-apple-darwin

Currently fails building rpmalloc.c on inline assembly