Trait Scan 

pub unsafe trait Scan: GcSafe {
    // Required method
    fn scan(&self, scanner: &mut Scanner<'_>);
}

A trait capturing the ability of data to be scanned for references to data in a Gc.

This is unsafe, since a bad scan implementation can cause memory unsafety in two ways:

1. If scan scans data that this object does not own
2. If scan does anything other than scan data with a non-'static lifetime
3. If scan is non-deterministic about what owned data it scans

The importance of (1) is so that the collector does not collect data that is in use. The importance of (2) is so that data can still be scanned even after its lifetime has technically expired.

Regarding (1): Note that it’s okay to miss data that you own. Missing connected data can only cause memory leaks–not memory unsafety. Regarding (2): In particular, scan should not call anything but Scan on R and RMut. Even implicitly using the deref implementations on these structs is incorrect.

Importantly, any empty scan implementation is safe (assuming the GcSafe impl is correct)

NB: It’s important that scan only scans data that is truly owned. Rc/Arc cannot have sensible scan implementations, since each individual smart pointer doesn’t own the underlying data.

Examples

In practice you probably want to use the derive macro:

use shredder::Scan;

#[derive(Scan)]
struct Example {
    v: u32
}

This also comes with a #[shredder(skip_scan)] attribute, for when some data implements GcSafe but not Scan

use std::sync::Arc;
use shredder::Scan;

#[derive(Scan)]
struct Example {
    #[shredder(skip_scan)]
    v: Arc<u32>
}

This can work for any Send+ 'static data using GcSafeWrapper

use std::sync::Arc;

use shredder::marker::GcSafeWrapper;
use shredder::Scan;

struct SendDataButNotScan {
    i: u32
}

#[derive(Scan)]
#[shredder(cant_drop)] // <- To understand why we need this, read the docs of the derive itself
struct Example {
    #[shredder(skip_scan)]
    v: GcSafeWrapper<SendDataButNotScan>
}

In emergencies, you can break out #[shredder(unsafe_skip_gc_safe)], but this is potentially unsafe (the field you’re skipping MUST uphold invariants as-if it was GcSafe)

use std::sync::Arc;
use shredder::Scan;

struct NotEvenSendData {
    data: *mut u32
}

#[derive(Scan)]
#[shredder(cant_drop)] // <- To understand why we need this, read the docs of the derive itself
struct Example {
    #[shredder(unsafe_skip_gc_safe)]
    v: NotEvenSendData
}

IMPORTANT NOTE: You may have problems with the derive complaining your data is not-GcDrop. To find a resolution, read the documentation of the derive itself.

Required Methods

fn scan(&self, scanner: &mut Scanner<'_>)

scan should use the scanner to scan all of its directly owned data

Implementations on Foreign Types

impl Scan for bool

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for f32

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for f64

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for i8

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for i16

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for i32

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for i64

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for i128

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for isize

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for u8

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for u16

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for u32

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for u64

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for u128

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for usize

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for String

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for Duration

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for RandomState

fn scan(&self, _: &mut Scanner<'_>)

impl Scan for Instant

fn scan(&self, _: &mut Scanner<'_>)

impl<A: Scan, B: Scan> Scan for (A, B)

fn scan(&self, scanner: &mut Scanner<'_>)

impl<K: Scan, V: Scan> Scan for BTreeMap<K, V>

fn scan(&self, scanner: &mut Scanner<'_>)

impl<K: Scan, V: Scan, S: BuildHasher + GcSafe> Scan for HashMap<K, V, S>

fn scan(&self, scanner: &mut Scanner<'_>)

impl<T> Scan for &'static T

where &'static T: Send,

fn scan(&self, _: &mut Scanner<'_>)

impl<T: Copy + GcSafe + ?Sized> Scan for Cell<T>

fn scan(&self, _: &mut Scanner<'_>)

impl<T: Scan + ?Sized> Scan for RefCell<T>

fn scan(&self, scanner: &mut Scanner<'_>)

impl<T: Scan + ?Sized> Scan for Mutex<T>

fn scan(&self, scanner: &mut Scanner<'_>)

impl<T: Scan + ?Sized> Scan for RwLock<T>

fn scan(&self, scanner: &mut Scanner<'_>)

impl<T: Scan> Scan for Option<T>

fn scan(&self, scanner: &mut Scanner<'_>)

impl<T: Scan> Scan for BTreeSet<T>

fn scan(&self, scanner: &mut Scanner<'_>)

impl<T: Scan> Scan for Vec<T>

fn scan(&self, scanner: &mut Scanner<'_>)

impl<T: Scan, E: Scan> Scan for Result<T, E>

fn scan(&self, scanner: &mut Scanner<'_>)

impl<T: Scan, S: BuildHasher + GcSafe> Scan for HashSet<T, S>

fn scan(&self, scanner: &mut Scanner<'_>)

Implementors

impl<'a, T: ?Sized> Scan for R<'a, T>

impl<'a, T: ?Sized> Scan for RMut<'a, T>

impl<T: Scan + GcDeref + ?Sized> Scan for DerefGc<T>

impl<T: Scan + ?Sized> Scan for Gc<T>

impl<T: Scan> Scan for AtomicGc<T>