DOCSEARCHbyAlgolia
Submit Docs

mimalloc

repository·main3·Indexed 11 days ago

https://github.com/microsoft/mimalloc

A high-performance general-purpose allocator developed by Microsoft designed for low latency and scalability. It features free list sharding, eager page purging, and a secure mode. Available in three version tracks: v3 (recommended), v2 (stable), and v1 (legacy). Supports drop-in replacement for malloc via LD_PRELOAD on Linux/BSD and redirection DLLs or the minject utility on Windows.

Tokens
6.7K
Snippets
24
Records
35
Agent score
96%

What's inside mimalloc

  1. Overview of mimalloc design and features

    main3

    mimalloc is a high-performance, general-purpose allocator designed for low latency and scalability. Key design features include:

    • Free list sharding: Uses many small free lists per "mimalloc page" (typically 64KiB) to reduce fragmentation and improve locality.
    • Free list multi-sharding: Implements multiple free lists per page (one for thread-local free operations and one for concurrent free operations) to minimize contention.
    • Eager page purging: Marks empty pages as unused to the OS to reduce memory pressure.
    • Secure mode: Can be built with guard pages, randomized allocation, and encrypted free lists to protect against heap vulnerabilities.
    • First-class heaps: Allows efficient creation of multiple heaps. In v3, these are true first-class heaps that can be allocated from any thread.
    • Bounded performance: Provides bounded worst-case allocation times and low space overhead (~0.2% metadata).

  2. Performance overview and benchmarking

    main3

    mimalloc is designed to perform well across a wide range of workloads, including real-world programs and synthetic benchmarks. It aims to provide high performance with a memory footprint similar to other leading allocators like jemalloc and tcmalloc.

    Key Performance Characteristics

    • Workload Versatility: Unlike many allocators that excel in specific scenarios but fail in others, mimalloc maintains consistent performance across diverse benchmarks.
    • Thread Locality: mimalloc often shows significant speedups in concurrent workloads (e.g., LeanN) due to better allocation locality.
    • Object Migration: It performs well in scenarios where objects are allocated in one thread and freed in another (e.g., larsonN, mstressN).
    • Asymmetric Workloads: In workloads where some threads only allocate and others only free (e.g., xmalloc-testN), mimalloc's sharded thread free lists provide a significant advantage.
    • Cache Efficiency: The design helps mitigate issues like passive false sharing of cache lines.

    For detailed technical analysis, refer to the mimalloc technical report. Automated benchmarks are available via mimalloc-bench.

  3. Choose the right mimalloc version

    main3

    mimalloc is maintained in three distinct version tracks:

    • v3 (Recommended): The latest development track. Features a simplified lock-free design, improved memory sharing between threads, true first-class heaps (allocatable from any thread), and more efficient heap-walking.
    • v2 (Stable): The stable version. Uses thread-local segments to reduce fragmentation.
    • v1 (Legacy): The initial design. Maintained for security and bug fixes. Use this only if required by legacy constraints.

  4. Enable guard pages to catch buffer overflows

    main3
    A guarded build can be used to place OS guard pages behind objects, allowing the system to catch buffer overflows as they occur. This is available in newer versions (starting from v1.8.9).

  5. Integrate mimalloc into a C/C++ project

    main3

    C Integration

    The preferred method is to include <mimalloc.h> and link against the shared or static library while using the mi_malloc API.

    Example linking with gcc:

    gcc -o myprogram -lmimalloc myfile.c

    CMake Integration

    If using CMake, use find_package to locate the installed library:

    find_package(mimalloc 1.8 REQUIRED)
target_link_libraries(myapp PUBLIC mimalloc)
# Or for static:
target_link_libraries(myapp PUBLIC mimalloc-static)

    C++ Integration

    For best performance in C++, it is recommended to override the global new and delete operators. You can do this easily by including mimalloc-new-delete.h in exactly one source file in your project.

    Additionally, mimalloc provides mi_stl_allocator, which implements the std::allocator interface for use with C++ Standard Library containers.

    find_package(mimalloc 1.8 REQUIRED)
target_link_libraries(myapp PUBLIC mimalloc)

  6. Build mimalloc on Windows with CMake and Visual Studio

    main3

    Open a Visual Studio 2022 development prompt and use cmake with the appropriate generator and architecture.

    To build with the default generator:

    cmake ..\.. -G "Visual Studio 17 2022" -A x64 -DMI_OVERRIDE=ON

    Specify the build type during the build phase:

    cmake --build . --config=Release

    To build using the clang-cl compiler via the LLVM toolset:

    cmake ../.. -G "Visual Studio 17 2022" -T ClangCl
    cmake ..\.. -G "Visual Studio 17 2022" -A x64 -DMI_OVERRIDE=ON

  7. Build mimalloc on Linux, macOS, and BSD

    main3

    Use cmake to build the library. By default, this produces a shared library (.so or .dylib), a static library (.a), and a single object file (.o).

    To build the standard version:

    mkdir -p out/release
cd out/release
cmake ../..
make

    To install the library and headers to /usr/local/lib and /usr/local/include:

    sudo make install

    To build a Debug version (includes internal checks and detailed statistics):

    mkdir -p out/debug
cd out/debug
cmake -DCMAKE_BUILD_TYPE=Debug ../..
make

    (The shared library will be named libmimalloc-debug.so)

    To build a Secure version (uses guard pages, encrypted free lists, etc.):

    mkdir -p out/secure
cd out/secure
cmake -DMI_SECURE=ON ../..
make

    (The shared library will be named libmimalloc-secure.so)

    mkdir -p out/release
cd out/release
cmake ../..
make

  8. Build mimalloc in Debug Mode

    main3

    Building with -DCMAKE_BUILD_TYPE=Debug enables runtime checks to catch development errors:

    • Detailed Statistics: Statistics for each object size are maintained. View them by setting the environment variable MIMALLOC_SHOW_STATS=1.
    • Overflow Detection: All objects have padding at the end to detect byte-precise heap block overflows.
    • Error Detection: Detects double frees, freeing invalid heap pointers, corrupted free-lists, and some forms of use-after-free.
    cmake .. -DCMAKE_BUILD_TYPE=Debug

  9. Build mimalloc with Valgrind support

    main3

    To use mimalloc with Valgrind, build with -DMI_TRACK_VALGRIND=ON.

    If you are overriding malloc/free (rather than calling mi_malloc directly), you must tell Valgrind not to intercept those calls using the --soname-synonyms flag.

    # Build
cmake ../.. -DMI_TRACK_VALGRIND=ON

# Run with Valgrind (standard usage)
valgrind <myprogram>

# Run with Valgrind when overriding malloc/free
MIMALLOC_SHOW_STATS=1 valgrind --soname-synonyms=somalloc=*mimalloc* -- <myprogram>

# Run with Valgrind and LD_PRELOAD
valgrind --trace-children=yes --soname-synonyms=somalloc=*mimalloc* /usr/bin/env LD_PRELOAD=/usr/lib/libmimalloc.so -- <myprogram>

  10. Statically override standard malloc on Unix-like systems

    main3

    To override malloc statically on Unix-like systems, link the final program with the mimalloc single object file (mimalloc.o) as the first object file. This ensures linkers prefer mimalloc over standard library archives.

    gcc -o myprogram mimalloc.o myfile1.c ...

  11. Dynamically override standard malloc on Linux and BSD

    main3

    On ELF-based systems, preload the mimalloc shared library to resolve all standard malloc calls to mimalloc.

    To verify mimalloc is running, use MIMALLOC_VERBOSE=1. To see detailed statistics, use the debug version of the library with MIMALLOC_SHOW_STATS=1.

    # Standard dynamic override
env LD_PRELOAD=/usr/lib/libmimalloc.so myprogram

# Verify mimalloc is running
env MIMALLOC_VERBOSE=1 LD_PRELOAD=/usr/lib/libmimalloc.so myprogram

# Run debug version with statistics
env MIMALLOC_SHOW_STATS=1 LD_PRELOAD=/usr/lib/libmimalloc-debug.so myprogram

  12. Use Event Tracing for Windows (ETW) to profile mimalloc

    main3

    You can profile mimalloc allocation and free events on Windows using Event Tracing for Windows (ETW). The event manifest is defined in etw.man, which generates etw.h.

    To capture these events, use the Windows Performance Recorder (WPR) with the provided profile etw-mimalloc.wprp.

    1. Open an administrator prompt.
    2. Start the WPR session using the mimalloc profile.
    3. Run your program.
    4. Stop the session to generate an .etl file.
    5. Open the resulting .etl file in Windows Performance Analyzer (WPA) to inspect allocation (event 100) and free (event 101) activities.
    > wpr -start src\prim\windows\etw-mimalloc.wprp -filemode
> <my mimalloc program>
> wpr -stop test.etl