Welcome to the Immix GC project! This project aims to provide a highly efficient and easily integrable immix garbage collector (GC) for all languages that use LLVM as their backend. Originally a part of the Pivot Lang project, this GC leverages LLVM's stackmap functionality to assist in stack scanning and supports both conservative and precise garbage collection.
- High Performance: Designed for high efficiency to minimize the overhead of garbage collection.
- Easy Integration: Simple to integrate with any LLVM-based language.
- Support for Conservative and Precise Collection: Flexible enough to work with both conservative and precise memory management paradigms.
- LLVM Stackmap Integration: Utilizes LLVM's stackmap feature for effective stack scanning.
- LLVM Passes and GC Strategy Plugins: Comes with built-in LLVM passes and corresponding GC strategy plugins to facilitate integration.
- Evacuation: Supports object evacuation to reduce fragmentation and improve memory locality.
- Linux amd64
- windows amd64
- macOS aarch64
The above 3 platforms are tested and supported, other platforms may work but are not officially supported.
Theoretically this GC should work on all amd64 and aarch64 platforms.
To build the Immix GC, you will need to have the following dependencies installed:
- LLVM 18.x
- CMake 3.10 or higher
- Rust 1.55 or higher
Once you have the dependencies installed, you can build the Immix GC by following these steps:
-
Clone the repository:
-
Build project with Cargo:
cargo build
don't forget to add the
--releaseflag if you want to build the release version.
Current GC's allocation fast path is implemented in raw LLVM IR, it only fallbacks to Rust allocation routine when 1. the allocation size is too large or 2. the current 'hole' is not large enough to hold the object.
The GC algorithm requires the allocated memory to be zeroed or initialized before next possible GC cycle, this is because the reused memory may contain object headers dead in previous GC cycles, which may leading to finding wrong object header during collection.
So if you are using the GC apart from the 'LLVM IR fast path', you should always zero or initialize the allocated memory just after allocation.
By the way, the LLVM IR fast path is implemented in alloc-*.ll files.
TODO
- Rewrote the allocation and collection logic to improve performance.
- Reimplement fast allocation path in raw LLVM IR to make the allocation process as fast as possible.
- Imporve the escape analysis to reduce the number of objects that need to be allocated on the heap.
TODO: Update usage docs
- Initial release of the Immix GC project.
We welcome contributions from the community! Here are some ways you can contribute:
- Submit bug reports and feature requests.
- Write documentation and tutorials.
- Improve the performance and capabilities of the GC.
- Integrate Immix GC with more languages and provide examples.
This project is licensed under the MIT License. See the LICENSE file for more details.
This project is inspired by the need for a performant garbage collection system in the Pivot Lang project and has evolved to become a stand-alone solution for all LLVM-based languages. Special thanks to all contributors and the LLVM community for their support.
Happy Coding!