Struct Gc

pub struct Gc<'gc, T>
where
    T: 'gc + ?Sized,
{ /* private fields */ }

A garbage collected pointer to a type T. Implements Copy, and is implemented as a plain machine pointer. You can only allocate Gc pointers through a &Mutation<'gc> inside an arena type, and through “generativity” such Gc pointers may not escape the arena they were born in or be stored inside TLS. This, combined with correct Collect implementations, means that Gc pointers will never be dangling and are always safe to access.

Implementations

impl<'gc, T> Gc<'gc, T>

where T: Collect + 'gc,

pub fn new(mc: &Mutation<'gc>, t: T) -> Gc<'gc, T>

Examples found in repository

examples/basic.rs (line 95)

fn get_running_project(xml: &str, system: Rc<StdSystem<C>>) -> EnvArena {
    EnvArena::new(|mc| {
        let parser = ast::Parser::default();
        let ast = parser.parse(xml).unwrap();
        assert_eq!(ast.roles.len(), 1); // this should be handled more elegantly in practice - for the sake of this example, we only allow one role

        let (bytecode, init_info, locs, _) = ByteCode::compile(&ast.roles[0]).unwrap();

        let mut proj = Project::from_init(mc, &init_info, Rc::new(bytecode), Settings::default(), system);
        proj.input(mc, Input::Start); // this is equivalent to clicking the green flag button

        Env { proj: Gc::new(mc, RefLock::new(proj)), locs }
    })
}

impl<'gc, T> Gc<'gc, T>

where T: 'gc,

pub unsafe fn cast<U>(this: Gc<'gc, T>) -> Gc<'gc, U>

where U: 'gc,

Cast the internal pointer to a different type.

SAFETY: It must be valid to dereference a *mut U that has come from casting a *mut T.

pub unsafe fn from_ptr(ptr: *const T) -> Gc<'gc, T>

Retrieve a Gc from a raw pointer obtained from Gc::as_ptr

SAFETY: The provided pointer must have been obtained from Gc::as_ptr, and the pointer must not have been collected yet.

impl<'gc, T> Gc<'gc, T>

where T: Unlock + 'gc + ?Sized,

pub fn unlock(self, mc: &Mutation<'gc>) -> &'gc <T as Unlock>::Unlocked

Shorthand for Gc::write(mc, self).unlock().

impl<'gc, T> Gc<'gc, T>

where T: 'gc + ?Sized,

pub fn as_ref(self) -> &'gc T

Obtains a long-lived reference to the contents of this Gc.

Unlike AsRef or Deref, the returned reference isn’t bound to the Gc itself, and will stay valid for the entirety of the current arena callback.

pub fn downgrade(this: Gc<'gc, T>) -> GcWeak<'gc, T>

pub fn write(mc: &Mutation<'gc>, gc: Gc<'gc, T>) -> &'gc Write<T>

Triggers a write barrier on this Gc, allowing for further safe mutation.

pub fn ptr_eq(this: Gc<'gc, T>, other: Gc<'gc, T>) -> bool

Returns true if two Gcs point to the same allocation.

Similarly to Rc::ptr_eq and Arc::ptr_eq, this function ignores the metadata of dyn pointers.

pub fn as_ptr(gc: Gc<'gc, T>) -> *const T

pub fn is_dead(_: &Finalization<'gc>, gc: Gc<'gc, T>) -> bool

Returns true when a pointer is dead during finalization. This is equivalent to GcWeak::is_dead for strong pointers.

Any strong pointer reachable from the root will never be dead, BUT there can be strong pointers reachable only through other weak pointers that can be dead.

pub fn resurrect(fc: &Finalization<'gc>, gc: Gc<'gc, T>)

Manually marks a dead Gc pointer as reachable and keeps it alive.

Equivalent to GcWeak::resurrect for strong pointers. Manually marks this pointer and all transitively held pointers as reachable, thus keeping them from being dropped this collection cycle.

impl<'gc, T> Gc<'gc, Lock<T>>

where T: Copy + 'gc,

pub fn get(self) -> T

pub fn set(self, mc: &Mutation<'gc>, t: T)

impl<'gc, T> Gc<'gc, RefLock<T>>

where T: 'gc + ?Sized,

pub fn borrow(self) -> Ref<'gc, T>

pub fn try_borrow(self) -> Result<Ref<'gc, T>, BorrowError>

pub fn borrow_mut(self, mc: &Mutation<'gc>) -> RefMut<'gc, T>

Examples found in repository

examples/basic.rs (line 140)

fn main() {
    // read in an xml file whose path is given as a command line argument
    let args = std::env::args().collect::<Vec<_>>();
    if args.len() != 2 {
        panic!("usage: {} [xml file]", &args[0]);
    }
    let mut xml = String::new();
    std::fs::File::open(&args[1]).expect("failed to open file").read_to_string(&mut xml).expect("failed to read file");

    // create a new shared clock and start a thread that updates it at our desired interval
    let clock = Arc::new(Clock::new(UtcOffset::UTC, Some(Precision::Medium)));
    let clock_clone = clock.clone();
    std::thread::spawn(move || loop {
        std::thread::sleep(CLOCK_INTERVAL);
        clock_clone.update();
    });

    // create a custom config for the system - in this simple example we just implement the say/think blocks to print to stdout
    let config = Config::<C, StdSystem<C>> {
        request: None,
        command: Some(Rc::new(|_mc, key, command, _proc| match command {
            Command::Print { style: _, value } => {
                if let Some(value) = value {
                    println!("{value:?}");
                }
                key.complete(Ok(())); // any request that you handle must be completed - otherwise the calling process will hang forever
                CommandStatus::Handled
            }
            _ => CommandStatus::UseDefault { key, command }, // anything you don't handle should return the key and command to invoke the default behavior instead
        })),
    };

    // initialize our system with all the info we've put together
    let system = Rc::new(StdSystem::new_sync(CompactString::new(BASE_URL), None, config, clock.clone()));
    let mut env = get_running_project(&xml, system);

    // begin running the code - these are some helpers to make things more efficient in terms of memory and cpu resources
    let mut idle_sleeper = IdleAction::new(YIELDS_BEFORE_SLEEP, Box::new(|| std::thread::sleep(IDLE_SLEEP_TIME)));
    let mut next_collect = clock.read(Precision::Medium) + COLLECT_INTERVAL;
    loop {
        env.mutate(|mc, env| {
            let mut proj = env.proj.borrow_mut(mc);
            for _ in 0..1024 {
                // step the virtual machine forward by one bytecode instruction
                let res = proj.step(mc);
                if let ProjectStep::Error { error, proc } = &res {
                    // if we get an error, we can generate an error summary including a stack trace - here we just print out the result
                    let trace = ErrorSummary::extract(error, proc, &env.locs);
                    println!("error: {error:?}\ntrace: {trace:?}");
                }
                // this takes care of performing thread sleep if we get a bunch of no-ops from proj.step back to back
                idle_sleeper.consume(&res);
            }
        });
        // if it's time for us to do garbage collection, do it and reset the next collection time
        if clock.read(Precision::Low) >= next_collect {
            env.collect_all();
            next_collect = clock.read(Precision::Medium) + COLLECT_INTERVAL;
        }
    }
}

pub fn try_borrow_mut( self, mc: &Mutation<'gc>, ) -> Result<RefMut<'gc, T>, BorrowMutError>

Trait Implementations

impl<'gc, T> AsRef<T> for Gc<'gc, T>

where T: 'gc + ?Sized,

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<'gc, T> Clone for Gc<'gc, T>

where T: 'gc + ?Sized,

fn clone(&self) -> Gc<'gc, T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'gc, T> Collect for Gc<'gc, T>

where T: 'gc + ?Sized,

fn trace(&self, cc: &Collection)

Must call Collect::trace on all held Gc pointers. If this type holds inner types that implement Collect, a valid implementation would simply call Collect::trace on all the held values to ensure this.

fn needs_trace() -> bool

where Self: Sized,

As an optimization, if this type can never hold a Gc pointer and trace is unnecessary to call, you may implement this method and return false. The default implementation returns true, signaling that Collect::trace must be called.

impl<'gc, T> Debug for Gc<'gc, T>

where T: Debug + 'gc + ?Sized,

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'gc, T> Deref for Gc<'gc, T>

where T: 'gc + ?Sized,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<'gc, T> Display for Gc<'gc, T>

where T: Display + 'gc + ?Sized,

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'gc, C: CustomTypes<S>, S: System<C>> From<Gc<'gc, RefLock<Closure<'gc, C, S>>>> for Value<'gc, C, S>

fn from(v: Gc<'gc, RefLock<Closure<'gc, C, S>>>) -> Self

Converts to this type from the input type.

impl<'gc, C: CustomTypes<S>, S: System<C>> From<Gc<'gc, RefLock<Entity<'gc, C, S>>>> for Value<'gc, C, S>

fn from(v: Gc<'gc, RefLock<Entity<'gc, C, S>>>) -> Self

Converts to this type from the input type.

impl<'gc, C: CustomTypes<S>, S: System<C>> From<Gc<'gc, RefLock<VecDeque<Value<'gc, C, S>>>>> for Value<'gc, C, S>

fn from(v: Gc<'gc, RefLock<VecDeque<Value<'gc, C, S>>>>) -> Self

Converts to this type from the input type.

impl<'gc, T> Hash for Gc<'gc, T>

where T: Hash + 'gc + ?Sized,

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'gc, T> Ord for Gc<'gc, T>

where T: Ord + 'gc + ?Sized,

fn cmp(&self, other: &Gc<'gc, T>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<'gc, T> PartialEq for Gc<'gc, T>

where T: PartialEq + 'gc + ?Sized,

fn eq(&self, other: &Gc<'gc, T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Gc<'gc, T>) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'gc, T> PartialOrd for Gc<'gc, T>

where T: PartialOrd + 'gc + ?Sized,

fn partial_cmp(&self, other: &Gc<'gc, T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn le(&self, other: &Gc<'gc, T>) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn lt(&self, other: &Gc<'gc, T>) -> bool

Tests less than (for self and other) and is used by the < operator.

fn ge(&self, other: &Gc<'gc, T>) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

fn gt(&self, other: &Gc<'gc, T>) -> bool

Tests greater than (for self and other) and is used by the > operator.

impl<'gc, T> Pointer for Gc<'gc, T>

where T: 'gc + ?Sized,

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'gc, T> Copy for Gc<'gc, T>

where T: 'gc + ?Sized,

impl<'gc, T> Eq for Gc<'gc, T>

where T: Eq + 'gc + ?Sized,