Macro zerogc::unsafe_immutable_trace_iterable

macro_rules! unsafe_immutable_trace_iterable {
    ($target:ident, element = $element_type:ident) => { ... };
    ($target:ident<$($param:ident),*>; element = { $element_type:ty }) => { ... };
}

Unsafely implement ImmutableTrace for the specified iterable type, by iterating over the type to trace all objects.

You still have to implement the regular Trace and GcSafe traits by hand.

This macro is only useful for unsafe collections like Vec and HashMap who use raw pointers internally, since raw pointers can't have automatically derived tracing implementations. Otherwise, it's best to use an automatically derived implementation since that's always safe. In order to prevent ambiguity, this always requires the type of the element being traced.

Usage

unsafe_trace_iterable!(Vec, element = T);
unsafe_trace_iterable!(HashMap, element = { (&K, &V) }; K, V);
unsafe_trace_iterable!(HashSet, element = T);

Safety

Always prefer automatically derived implementations where possible, since they're just as fast and can never cause undefined behavior. This is basically an unsafe automatically derived implementation, to be used only when a safe automatically derived implementation isn't possible (like with Vec).

Undefined behavior if there could be garbage collected objects that are not reachable via iteration, since the macro only traces objects it can iterate over, and the garbage collector will free objects that haven't been traced. This usually isn't the case with collections and would be somewhat rare, but it's still a possibility that causes the macro to be unsafe.

This delegates to unsafe_gc_brand! to provide the GcBrand implementation, so that could also trigger undefined behavior.