Struct Thread 

pub struct Thread { /* private fields */ }

GC Mutator.

By using this structure you can allocate, synchronize with GC and insert write barriers.

Implementations

impl Thread

pub fn safepoint_offset() -> usize

pub fn mark_queue_offset() -> usize

pub fn satb_buffer_offset() -> usize

pub fn satb_index_offset() -> usize

pub fn cm_in_progress_offset() -> usize

pub fn mark_ctx_offset() -> usize

pub fn mark_bitmap_offset() -> usize

pub fn tlab_start_offset() -> usize

pub fn tlab_top_offset() -> usize

pub fn tlab_end_offset() -> usize

pub fn tlab_bitmap_offset() -> usize

pub unsafe fn satb_mark_queue(&self) -> &LocalSSB

pub unsafe fn satb_mark_queue_mut(&mut self) -> &mut LocalSSB

pub fn allocate<T: 'static + Allocation>(&mut self, value: T) -> Handle<T>

Allocates fixed sized object on the heap.

Examples found in repository

examples/binarytrees.rs (lines 43-47)

fn create_tree(thread: &mut Thread, depth: i64) -> Handle<TreeNode> {
    thread.safepoint();
    let node = if 0 < depth {
        let mut node = thread.allocate(TreeNode {
            item: 0,
            left: None,
            right: None,
        });

        thread.write_barrier(node);
        node.left = Some(create_tree(thread, depth - 1));
        thread.write_barrier(node);
        node.right = Some(create_tree(thread, depth - 1));

        node 
    } else {
        let node = TreeNode {
            item: 0,
            left: None,
            right: None,
        };

        thread.allocate(node)
    };
    
    node
}

pub fn allocate_varsize<T: 'static + Allocation>( &mut self, length: usize, ) -> Handle<MaybeUninit<T>>

Allocates variably sized object on the heap.

Note that length field is automatically written at Allocation::VARSIZE_OFFSETOF_CAPACITY.

pub unsafe fn allocate_raw(&mut self, size: usize) -> *mut u8

Allocates raw memory, unsafe to use outside of RSGC impl itself.

TODO

I should really update it to include all code to properly tell GC that we allocated something, right now it is done in allocate and allocate_varsize but it should be done here.

pub fn write_barrier<T: Object + ?Sized>(&mut self, handle: Handle<T>)

SATB write barrier. Ensures that object processes all references correctly. Must be inserted before write to handle.

Examples found in repository

examples/binarytrees.rs (line 49)

fn create_tree(thread: &mut Thread, depth: i64) -> Handle<TreeNode> {
    thread.safepoint();
    let node = if 0 < depth {
        let mut node = thread.allocate(TreeNode {
            item: 0,
            left: None,
            right: None,
        });

        thread.write_barrier(node);
        node.left = Some(create_tree(thread, depth - 1));
        thread.write_barrier(node);
        node.right = Some(create_tree(thread, depth - 1));

        node 
    } else {
        let node = TreeNode {
            item: 0,
            left: None,
            right: None,
        };

        thread.allocate(node)
    };
    
    node
}

pub fn write_barrier_no_filter<T: Object + ?Sized>(&mut self, handle: Handle<T>)

Same as write_barrier but does not filter marked objects, instead they are filtered when flushing SATB buffer to collector.

pub unsafe fn raw_write_barrier<const FILTER_SATB: bool>( &mut self, obj: *mut HeapObjectHeader, )

Raw implementation of write-barrier.

If SATB mode is used this code will do Yuasa deletion write barrier that captures writes to white objects. Note that this barrier is very conservative: it does not check colors of new values that are being written.

In Incremental Update mode uses Steele’s write barrier that captures black<-white writes. This barrier is very conservative as well. Note that with IU mode concurrent mark termination might take longer.

In passive mode does nothing.

pub fn flush_ssb(&mut self)

Flush SSB queue. This function is called when SSB queue is full.

Writes are pushed to global SATB queue. If object is already marked it is not pushed to SATB queue.

pub fn atomic_gc_state(&self) -> &AtomicI8

pub unsafe fn gc_state_set(&mut self, state: i8, old_state: i8) -> i8

pub unsafe fn set_last_sp(&mut self, sp: *mut u8)

pub unsafe fn state_save_and_set(&mut self, state: i8) -> i8

pub fn stack_start(&self) -> *mut u8

pub fn last_sp(&self) -> *mut u8

pub unsafe fn safepoint_page(&self) -> *mut u8

Returns pointer to safepoint page. When JITing your code you can directly inline safepoint poll into your code.

pub const fn is_conditional_safepoint() -> bool

Returns true if safepoints are conditional in this build of RSGC.

pub fn safepoint(&mut self)

Reads from polling page. If safepoint is disabled nothing happens but when safepoint is enabled this triggers page fault (SIGSEGV/SIGBUS on Linux/macOS/BSD) and goes into signal to suspend thread.

Note

Enable conditional-safepoint feature when running in LLDB/GDB, otherwise safepoint events will be treatened as segfault by debuggers.

Examples found in repository

examples/binarytrees.rs (line 41)

fn create_tree(thread: &mut Thread, depth: i64) -> Handle<TreeNode> {
    thread.safepoint();
    let node = if 0 < depth {
        let mut node = thread.allocate(TreeNode {
            item: 0,
            left: None,
            right: None,
        });

        thread.write_barrier(node);
        node.left = Some(create_tree(thread, depth - 1));
        thread.write_barrier(node);
        node.right = Some(create_tree(thread, depth - 1));

        node 
    } else {
        let node = TreeNode {
            item: 0,
            left: None,
            right: None,
        };

        thread.allocate(node)
    };
    
    node
}

pub fn is_registered(&self) -> bool

Returns true if thread is registered in a GC.

pub fn current() -> &'static mut Thread

Returns current thread.

Examples found in repository

examples/binarytrees.rs (line 91)

fn bench_parallel() {

    let mut n = 0;
    if let Some(arg) = std::env::args().skip(1).next() {
        if let Ok(x) = arg.parse::<usize>() {
            n = x;
        }
    }

    let min_depth = 4;
    let max_depth = if n < (min_depth + 2) {
        min_depth + 2
    } else {
        n 
    };

    let start = std::time::Instant::now();
    let stretch_depth = max_depth + 1;

    {
        println!(
            "stretch tree of depth {}\t check: {}",
            stretch_depth,
            create_tree(Thread::current(), stretch_depth as _)
                .as_ref()
                .check_tree()
        );
    }

    let long_lasting_tree = create_tree(Thread::current(), max_depth as _);
    use parking_lot::Mutex;
    let results = Arc::new(
        (0..(max_depth - min_depth) / 2 + 1)
            .map(|_| Mutex::new(String::new()))
            .collect::<Vec<_>>(),
    );
    rsgc::thread::scoped::scoped(|scope| {
        let mut d = min_depth;

        while d <= max_depth {
            let depth = d;
            let cloned = results.clone();
            scope.spawn(move || {
                let thread = Thread::current();
                let iterations = 1 << (max_depth - depth + min_depth);
                let mut check = 0;
                for _ in 1..=iterations {
                    let tree_node = create_tree(thread, depth as _);
                    check += tree_node.as_ref().check_tree();
                }

                *cloned[(depth - min_depth) / 2].lock() = format!(
                    "{}\t trees of depth {}\t check: {}",
                    iterations, depth, check
                );
            });

            d += 2;
        }
    });
    for result in results.iter() {
        println!("{}", *result.lock());
    }
    println!(
        "long lived tree of depth {}\t check: {}",
        max_depth,
        long_lasting_tree.as_ref().check_tree()
    );

    println!(
        "time: {}ms",
        start.elapsed().as_millis()
    );
}

pub unsafe fn get_registers(&self) -> (*mut u8, usize)

Returns registers for current thread. This is used by GC to trace current registers.

Safety

Can return invalid pointer or null. Must be used only by GC and only when roots are traced.

Should not be used outside of RSGC.