rust_cc

Trait Trace

Source
pub unsafe trait Trace: Finalize {
    // Required method
    fn trace(&self, ctx: &mut Context<'_>);
}
Expand description

Trait to trace cycle-collectable objects.

This trait is unsafe to implement, but can be safely derived using the Trace derive macro, which calls the trace method on every field:

#[derive(Trace)]
struct Foo<A: Trace + 'static, B: Trace + 'static> {
    a_field: Cc<A>,
    another_field: Cc<B>,
}

This trait is already implemented for common types from the standard library.

§Safety

The implementations of this trait must uphold the following invariants:

  • The trace implementation can trace (maximum once) every Cc instance exclusively owned by self. No other Cc instance can be traced.
  • It’s always safe to panic.
  • During the same tracing phase (see below), two different trace calls on the same value must behave the same, i.e. they must trace the same Cc instances.
    If a panic happens during the second of such trace calls but not in the first one, then the Cc instances traced during the second call must be a subset of the Cc instances traced in the first one.
    Tracing can be detected using the state::is_tracing function. If it never returned false between two trace calls on the same value, then they are part of the same tracing phase.
  • The trace implementation must not create, clone, move, dereference or drop any Cc.
  • If the implementing type implements Drop, then the Drop::drop implementation must not create, clone, move, dereference, drop or call any method on any Cc instance.

§Implementation tips

It is almost always preferable to use the derive macro #[derive(Trace)], but in case a manual implementation is needed the following suggestions usually apply:

  • If a field’s type implements Trace, then call its trace method.
  • Try to avoid panicking if not strictly necessary, since it may lead to memory leaks.
  • Avoid mixing Ccs with other shared-ownership smart pointers like Rc (a Cc contained inside an Rc cannot be traced, since it’s not owned exclusively).
  • Never tracing a field is always safe.
  • If you need to perform any clean up actions, you should do them in the Finalize::finalize implementation (instead of inside Drop::drop) or using a cleaner.

§Derive macro compatibility

In order to improve the Trace derive macro usability and error messages, it is suggested to avoid implementing this trait for references or raw pointers (also considering that no pointed Cc may be traced, since a reference doesn’t own what it refers to).

Required Methods§

Source

fn trace(&self, ctx: &mut Context<'_>)

Traces the contained Ccs. See Trace for more information.

Implementations on Foreign Types§

Source§

impl Trace for bool

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for char

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for f32

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for f64

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for i8

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for i16

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for i32

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for i64

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for i128

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for isize

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for str

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for u8

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for u16

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for u32

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for u64

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for u128

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for ()

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for usize

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for CString

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for String

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for CStr

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for AtomicBool

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for AtomicI8

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for AtomicI16

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for AtomicI32

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for AtomicI64

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for AtomicIsize

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for AtomicU8

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for AtomicU16

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for AtomicU32

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for AtomicU64

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for AtomicUsize

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for OsStr

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for OsString

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for Path

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for PathBuf

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for NonZeroI8

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for NonZeroI16

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for NonZeroI32

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for NonZeroI64

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for NonZeroI128

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for NonZeroIsize

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for NonZeroU8

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for NonZeroU16

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for NonZeroU32

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for NonZeroU64

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for NonZeroU128

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl Trace for NonZeroUsize

Source§

fn trace(&self, _: &mut Context<'_>)

Source§

impl<A> Trace for (A,)
where A: Trace,

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<A, B> Trace for (A, B)
where A: Trace, B: Trace,

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<A, B, C> Trace for (A, B, C)
where A: Trace, B: Trace, C: Trace,

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<A, B, C, D> Trace for (A, B, C, D)
where A: Trace, B: Trace, C: Trace, D: Trace,

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<A, B, C, D, E> Trace for (A, B, C, D, E)
where A: Trace, B: Trace, C: Trace, D: Trace, E: Trace,

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<A, B, C, D, E, F> Trace for (A, B, C, D, E, F)
where A: Trace, B: Trace, C: Trace, D: Trace, E: Trace, F: Trace,

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<A, B, C, D, E, F, G> Trace for (A, B, C, D, E, F, G)
where A: Trace, B: Trace, C: Trace, D: Trace, E: Trace, F: Trace, G: Trace,

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<A, B, C, D, E, F, G, H> Trace for (A, B, C, D, E, F, G, H)
where A: Trace, B: Trace, C: Trace, D: Trace, E: Trace, F: Trace, G: Trace, H: Trace,

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<A, B, C, D, E, F, G, H, I> Trace for (A, B, C, D, E, F, G, H, I)
where A: Trace, B: Trace, C: Trace, D: Trace, E: Trace, F: Trace, G: Trace, H: Trace, I: Trace,

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<A, B, C, D, E, F, G, H, I, J> Trace for (A, B, C, D, E, F, G, H, I, J)
where A: Trace, B: Trace, C: Trace, D: Trace, E: Trace, F: Trace, G: Trace, H: Trace, I: Trace, J: Trace,

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<A, B, C, D, E, F, G, H, I, J, K> Trace for (A, B, C, D, E, F, G, H, I, J, K)
where A: Trace, B: Trace, C: Trace, D: Trace, E: Trace, F: Trace, G: Trace, H: Trace, I: Trace, J: Trace, K: Trace,

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<A, B, C, D, E, F, G, H, I, J, K, L> Trace for (A, B, C, D, E, F, G, H, I, J, K, L)
where A: Trace, B: Trace, C: Trace, D: Trace, E: Trace, F: Trace, G: Trace, H: Trace, I: Trace, J: Trace, K: Trace, L: Trace,

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<R: Trace, E: Trace> Trace for Result<R, E>

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<T: Trace> Trace for Option<T>

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<T: Trace> Trace for [T]

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<T: Trace> Trace for Vec<T>

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<T: Trace> Trace for AssertUnwindSafe<T>

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<T: Trace, const N: usize> Trace for [T; N]

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<T: ?Sized + Trace> Trace for Box<T>

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

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

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<T: ?Sized + Trace> Trace for ManuallyDrop<T>

Source§

fn trace(&self, ctx: &mut Context<'_>)

Source§

impl<T: ?Sized> Trace for PhantomData<T>

Source§

fn trace(&self, _: &mut Context<'_>)

Implementors§

Source§

impl Trace for Cleanable

Available on crate feature cleaners only.
Source§

impl Trace for Cleaner

Available on crate feature cleaners only.
Source§

impl<T: ?Sized + Trace> Trace for Cc<T>

Source§

impl<T: ?Sized + Trace> Trace for Weak<T>

Available on crate feature weak-ptrs only.