turbo_tasks/vc/
local.rs

1use crate::{OperationVc, ResolvedVc, marker_trait::impl_auto_marker_trait};
2
3/// Marker trait indicating that a type does not contain any instances of [`Vc`] or references to
4/// [`Vc`]. It may contain [`ResolvedVc`] or [`OperationVc`].
5///
6/// This is referred to as "non-local", as a base [`Vc`] type may contain task-local references that
7/// are not valid after the contructing task finishes execution.
8///
9/// [`Vc`] can be thought of as containing a lifetime (`Vc<'task, T>`), and a [`NonLocalValue`] can
10/// be thought of as `'static` or ["owned"][ToOwned]. We don't currently use literal lifetimes for
11/// verbosity reasons, but safety is guaranteed through a combination of this trait and runtime
12/// assertions.
13///
14/// A future version of this trait may be implemented using a combination of [`auto_traits`] and
15/// [`negative_impls`], but [a derive macro][macro@NonLocalValue] is provided that avoids the need
16/// for these nightly-only features.
17///
18/// # Safety
19///
20/// This trait is marked as unsafe. You should not implement it yourself, but instead you should
21/// rely on [`#[turbo_tasks::value]`][macro@crate::value] or
22/// [`#[derive(NonLocalValue)]`][macro@NonLocalValue] to do it for you.
23///
24/// There may be a few rare cases (e.g. custom generic bounds) where you cannot use
25/// `#[turbo_tasks::value]`. In these cases, it is your responsibility to ensure that no fields can
26/// contain a [`Vc`] or a transitive reference to a [`Vc`].
27///
28/// There are currently runtime assertions in place as a fallback to ensure memory safety, but those
29/// assertions may become debug-only in the future if it significantly improves performance.
30///
31/// [`Vc`]: crate::Vc
32/// [`auto_traits`]: https://doc.rust-lang.org/beta/unstable-book/language-features/auto-traits.html
33/// [`negative_impls`]: https://doc.rust-lang.org/beta/unstable-book/language-features/negative-impls.html
34pub unsafe trait NonLocalValue {}
35
36unsafe impl<T: NonLocalValue + ?Sized> NonLocalValue for OperationVc<T> {}
37unsafe impl<T: NonLocalValue + ?Sized> NonLocalValue for ResolvedVc<T> {}
38
39impl_auto_marker_trait!(NonLocalValue);
40
41/// Implements [`NonLocalValue`] for a struct or enum by adding static (compile-time)
42/// assertions that every field implements [`NonLocalValue`].
43///
44/// Fields that do not contain [`Vc`] can be excluded from assertions using [`TraceRawVcs`]'s
45/// `#[turbo_tasks(trace_ignore)]` annotation. This can be useful for third-party library types
46/// that cannot implement [`NonLocalValue`] due to the orphan rules.
47///
48/// [`NonLocalValue`]: trait@NonLocalValue
49/// [`Vc`]: crate::Vc
50/// [`TraceRawVcs`]: crate::trace::TraceRawVcs
51pub use turbo_tasks_macros::NonLocalValue;
turbo_tasks/vc/local.rs

turbo_tasks/vc/
local.rs
