Struct Mutator 

pub struct Mutator {
    pub tid: u16,
    pub rec: Arc<ThreadRecord>,
    /* private fields */
}

Fields

tid: u16

rec: Arc<ThreadRecord>

Implementations

impl Mutator

pub fn new(rec: Arc<ThreadRecord>) -> Self

Creates the context for an already-registered thread.

pub fn set_young_alloc(&mut self, on: bool)

Whether new objects start young (see catallaxy_gc::LocalHeap::set_young_alloc).

pub fn sharing(other: &Mutator) -> Self

A second context for the same thread (a fiber): same heap and thread record, its own handle stack. Release it with Mutator::free_handles.

pub unsafe fn free_handles(&mut self)

Frees the handle stack of a context made by Mutator::sharing.

Safety

No root source may still reference the handles.

pub fn heap_ptr(&self) -> *mut LocalHeap

Raw pointer to the allocator, for registration with the collector.

pub fn release_pages(&mut self)

Returns the thread’s pages to the global pool (on thread exit, in native state).

pub fn scope<R>(&mut self, f: impl FnOnce(&mut Mutator) -> R) -> R

Runs f with a handle scope; handles rooted inside are released afterwards.

pub fn root(&mut self, v: Value) -> Handle

pub fn get(&self, h: Handle) -> Value

pub fn set(&mut self, h: Handle, v: Value)

pub fn handle_mark(&self) -> usize

The current depth of the handle stack, for Mutator::release_handles. Lets foreign code (the C API) manage scopes explicitly.

pub fn release_handles(&mut self, mark: usize)

Releases every handle rooted since mark.

pub fn handle_values(&self) -> &[Value]

Root values for the GC (called while this thread is stopped).

pub fn handles_ptr(&self) -> *const Vec<Value>

Pointer to the handle stack, for root sources that must not borrow the mutator.

pub fn alloc_raw(&mut self, size: usize, cls: &'static Class) -> *mut Header

pub fn alloc_instance(&mut self, cls: &'static Class) -> Value

pub fn alloc_str(&mut self, s: &str) -> Value

pub fn alloc_str_parts(&mut self, parts: &[&str]) -> Value

Allocates the concatenation of parts.

pub fn alloc_concat<'a>( &mut self, n: usize, part: impl Fn(usize) -> &'a StrObj, ) -> Value

Allocates the concatenation of n strings, part(i) being the ith, copying each once. The character count comes from the parts’ cached counts, so no byte is scanned twice.

pub fn try_alloc_str(&mut self, s: &str) -> RtResult<Value>

As Mutator::alloc_str, but a string the allocator refuses raises a MemoryError instead of aborting. A refusal first runs a collection and retries, so every value the caller holds must be rooted (as interpreter registers and native arguments are); s itself may point into a rooted string, since objects never move.

pub fn try_alloc_concat<'a>( &mut self, n: usize, part: impl Fn(usize) -> &'a StrObj, ) -> RtResult<Value>

As Mutator::alloc_concat, raising a MemoryError as Mutator::try_alloc_str does.

pub fn try_alloc_str_nogc(&mut self, s: &str) -> RtResult<Value>

As Mutator::try_alloc_str, but a refusal raises the MemoryError without collecting first, so the caller may hold values that nothing roots (the items of a list it is building, say).

pub fn collect_if_refused(&self)

For a native about to allocate much, holding no unrooted values yet: if the OS has refused memory since the last collection, collects now. Until a collection has looked again, the try_ allocations refuse small objects that need a new heap segment, and a native has no safepoint at which the collection it is waiting for could run.

pub fn try_vec_collecting<T>(&self, n: usize) -> RtResult<Vec<T>>

An empty vector with room for exactly n items. If the allocator refuses, collects (garbage may hold the memory) and tries once more, then raises a MemoryError. For natives that hold no unrooted values yet: their arguments are rooted.

pub fn int_from_big(&mut self, b: BigInt) -> Value

Allocates a big integer, or returns a small int if it fits.

pub fn int(&mut self, i: i64) -> Value

pub fn alloc_list(&mut self, items: Vec<Value>) -> Value

A list holding items, which takes over the vector’s allocation (and capacity). Small lists copy the items into the list object instead (see ListObj).

pub fn try_alloc_list(&mut self, items: Vec<Value>) -> RtResult<Value>

As Mutator::alloc_list, but raises a MemoryError if the list’s buffer cannot be had. Nothing roots items, so there is no collection and retry.

pub fn alloc_list_from_slice(&mut self, items: &[Value], cap: usize) -> Value

A list holding a copy of items, with room for at least cap of them.

pub fn try_alloc_list_from_slice( &mut self, items: &[Value], cap: usize, ) -> RtResult<Value>

As Mutator::alloc_list_from_slice, but raises a MemoryError if the list’s buffer cannot be had (without collecting: items may hold values nothing else roots).

pub fn alloc_dict(&mut self, table: DictTable) -> Value

pub fn alloc_set(&mut self, table: DictTable) -> Value

pub fn alloc_tuple(&mut self, items: &[Value]) -> Value

pub fn alloc_closure(&mut self, func: u32, caps: &[Value]) -> Value

pub fn alloc_cell(&mut self, v: Value) -> Value

pub fn alloc_string_builder(&mut self, s: String) -> Value

pub fn alloc_mutex(&mut self, v: Value) -> Value

pub fn alloc_atomic(&mut self, v: Value) -> Value

pub fn alloc_channel(&mut self, capacity: usize) -> Value

pub fn alloc_thread(&mut self) -> Value

pub fn alloc_native(&mut self, data: Box<dyn NativeData>) -> Value

pub fn alloc_native_frozen(&mut self, data: Box<dyn NativeData>) -> Value

Allocates a frozen native handle: one whose data is immutable or synchronizes itself, so it may be stored in frozen objects and used from any thread (NativeHandle in the prelude).

pub fn alloc_range( &mut self, first: Value, last: Value, exclusive: bool, ) -> Value

Trait Implementations

impl Send for Mutator