https://github.com/nickgeek/immix-rust

Immix GC implemnented in Rust and exposed as a Rust or C library. Forked from https://gitlab.anu.edu.au/mu/immix-rust
https://github.com/nickgeek/immix-rust

Last synced: 3 months ago
JSON representation

Immix GC implemnented in Rust and exposed as a Rust or C library. Forked from https://gitlab.anu.edu.au/mu/immix-rust

• Host: GitHub
• URL: https://github.com/nickgeek/immix-rust
• Owner: NickGeek
• License: apache-2.0
• Created: 2024-02-21T23:22:37.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2024-02-21T23:23:52.000Z (over 2 years ago)
• Last Synced: 2025-01-18T08:14:02.905Z (over 1 year ago)
• Language: Rust
• Size: 820 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
immix-rust

==========

> This is a fork of https://gitlab.anu.edu.au/mu/immix-rust, which does not compile with current Rust/deps.

> I have only tested that my changes work with the Rust API for this library, I may have accidentally broken the C API.

An Immix implementation written in Rust.

Features

--------

* Immix GC

    * thread local allocation

    * parallel GC

    * non generational, non moving, no defragment

* Free list allocation (as large object allocator)

    * linked list + malloc

    * no proper reclamation yet

    * will reimplement this part in near future

* Target platform

    * x86_64 (root tracing including stack scanning is target dependent)

Interface

--------------

`src/lib.rs` defines interface to use the GC. The interface is also

exposed as a C header `rust_c_interface/immix_rust.h`.

### Initialisation and Destroy

* Rust: `pub extern fn gc_init(immix_size: usize, lo_size: usize, n_gcthreads: usize)`

* C: `extern void gc_init(uint64_t immix_size, uint64_t lo_size, uint64_t n_gcthreads)`

   initialises the GC. First two parameters give sizes of immix space and

   large object space (in bytes), the 3rd parameter defines the number of

   GC threads (only used if multi-thread tracing is turned on via

   `--features mt-trace`)

* Rust: `pub extern fn new_mutator() -> Box`

* C: `extern struct Mutator* new_mutator()`

   creates a mutator. The user is responsible for storing the mutator at thread

   local storage.

* Rust: `pub extern fn drop_mutator(mutator: Box)`

* C: `extern void drop_mutator(struct Mutator* mutator)`

   destroys the mutator. After the call, `mutator` is no longer valid. This should

   only be useful when used in C (since Rust will identify the liveness of the mutator,

   and drop it when necessary).

* Rust: `extern "C" {pub fn set_low_water_mark();}`

* C: `extern void set_low_water_mark()`

   stores current stack pointer as a limit, so that conservative stack scanning

   will not traverse stack beyond this limit. Call this function after getting

   a new mutator.

### Allocation

* Rust: `pub extern fn alloc(mutator: &mut Box, size: usize, align: usize) -> ObjectReference`

* C: `inline uint64_t alloc(struct Mutator** mutator, uint64_t size, uint64_t align)`

  allocates an object in Immix space (thread local allocation).

  The object size should be smaller than one Immix line (256 bytes).

  Use large object allocation if the object size is larger than 256 bytes.

* Rust: `pub extern fn alloc_large(mutator: &mut Box, size: usize) -> ObjectReference`

* C: `extern uint64_t alloc_large(struct Mutator** mutator, uint64_t size)`

  allocates an object in large object space (global synchronisation involved).

  May later move the object size check into `alloc()` and deprecate this function.

* Rust: `pub extern fn yieldpoint(mutator: &mut Box)`

* C: `inline void yieldpoint(bool* take_yield, struct Mutator** m)`

  checks if current mutator should yield. GC won't be able to stop a mutator

  unless this function is put into code.

Note: `alloc` and `yieldpoint` are fast paths. They are provided in Rust,

and Rust compiler is able to inline them into Rust code. And they are

expressed in C code in the header file, so that C compiler is able to inline them.

Usage

-----

Install Rust and Cargo from https://www.rust-lang.org/.

Run `cargo build --release` under the repo directory to build the GC

(add `--features mt-trace` to turn on parallel GC), which

will generate a dynamic linked library under `target/release/`.

`rust_c_interface/test.c` gives an example on how to use the GC from

C code. Compile and link `test.c` with the library to test (it is an

infinite allocation loop).

Near Future Plan

------

* implementing a more efficient free list allocator

* removing `alloc_large()`, allocation in large object space will be triggered

in `alloc()` if the object size exceeds a threshold.