turbo_tasks/vc/
operation.rs

1use std::{
2    fmt::Debug,
3    future::Future,
4    hash::Hash,
5    marker::PhantomData,
6    pin::Pin,
7    task::{Context, Poll},
8};
9
10use anyhow::Result;
11use auto_hash_map::AutoSet;
12use bincode::{Decode, Encode};
13use serde::{Deserialize, Serialize};
14pub use turbo_tasks_macros::OperationValue;
15
16use crate::{
17    CollectiblesSource, RawVc, ReadVcFuture, ResolvedVc, TaskId, TaskInput, UpcastStrict, Vc,
18    VcValueTrait, VcValueTraitCast, VcValueType, marker_trait::impl_auto_marker_trait,
19    trace::TraceRawVcs, turbo_tasks,
20};
21
22/// A future returned by [`OperationVc::resolve`] that connects an [`OperationVc<T>`] and resolves
23/// it to a [`ResolvedVc<T>`].
24///
25/// Use [`.strongly_consistent()`][Self::strongly_consistent] to opt into strong consistency.
26#[must_use]
27pub struct ResolveOperationVcFuture<T>
28where
29    T: ?Sized,
30{
31    inner: super::ResolveVcFuture<T>,
32}
33
34impl<T: ?Sized> ResolveOperationVcFuture<T> {
35    /// Make the resolution strongly consistent.
36    pub fn strongly_consistent(mut self) -> Self {
37        self.inner.inner = self.inner.inner.strongly_consistent();
38        self
39    }
40}
41
42impl<T: ?Sized> Future for ResolveOperationVcFuture<T> {
43    type Output = anyhow::Result<ResolvedVc<T>>;
44
45    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
46        // SAFETY: we are not moving self
47        let this = unsafe { self.get_unchecked_mut() };
48        // ResolveVcFuture: Unpin, so Pin::new is safe
49        Pin::new(&mut this.inner)
50            .poll(cx)
51            .map(|r| r.map(|node| ResolvedVc { node }))
52    }
53}
54
55impl<T: ?Sized> Unpin for ResolveOperationVcFuture<T> {}
56
57/// A "subtype" (can be converted via [`.connect()`]) of [`Vc`] that
58/// represents a specific call (with arguments) to [a task][macro@crate::function].
59///
60/// Unlike [`Vc`], `OperationVc`:
61///
62/// - Does not potentially refer to task-local information, meaning that it implements
63///   [`NonLocalValue`], and can be used in any [`#[turbo_tasks::value]`][macro@crate::value].
64///
65/// - Has only one potential internal representation, meaning that it has a saner equality
66///   definition.
67///
68/// - Can be [reconnected][OperationVc::connect] to the strongly-consistent compilation graph after
69///   being placed inside of a [`State`].
70///
71/// - Makes sense with [collectibles][`CollectiblesSource`], as it represents a function call, and
72///   only function calls can have issues or side-effects.
73///
74///
75/// ## Equality & Hashing
76///
77/// Equality between two `OperationVc`s means that both have an identical in-memory representation
78/// and point to the same task function call. The implementation of [`Hash`] has similar behavior.
79///
80/// If [connected] and then `.await`ed at the same time, both would likely resolve to the same
81/// [`ReadRef`], though it is possible that they may not if the task or cell is invalidated between
82/// `.await`s.
83///
84/// Because equality is a synchronous operation that cannot read the cell contents, even if the
85/// `OperationVc`s are not equal, it is possible that if `.await`ed, both `OperationVc`s could point
86/// to the same or equal values.
87///
88/// [`.connect()`]: OperationVc::connect
89/// [reconnected]: OperationVc::connect
90/// [connected]: OperationVc::connect
91/// [`NonLocalValue`]: crate::NonLocalValue
92/// [`State`]: crate::State
93/// [`ReadRef`]: crate::ReadRef
94#[must_use]
95#[derive(Serialize, Deserialize, Encode, Decode)]
96#[bincode(bounds = "T: ?Sized")]
97pub struct OperationVc<T>
98where
99    T: ?Sized,
100{
101    task: TaskId,
102
103    _t: PhantomData<T>,
104}
105
106impl<T: ?Sized> OperationVc<T> {
107    /// Called by the `#[turbo_tasks::function]` macro.
108    ///
109    /// The macro ensures that the `Vc` is not a local task and it points to a single operation.
110    #[doc(hidden)]
111    #[deprecated = "This is an internal function. Use #[turbo_tasks::function(operation)] instead."]
112    pub fn cell_private(node: Vc<T>) -> Self {
113        let task = node.node.as_task_output().expect(
114            "OperationVc::cell_private must be called on the immediate return value of a task \
115             function",
116        );
117
118        Self {
119            task,
120            _t: PhantomData,
121        }
122    }
123
124    /// Marks this operation's underlying function call as a child of the current task, and returns
125    /// a [`Vc`] that can be [resolved][Vc::to_resolved] or read with `.await?`.
126    ///
127    /// By marking this function call as a child of the current task, turbo-tasks will re-run tasks
128    /// as-needed to achieve strong consistency at the root of the function call tree. This explicit
129    /// operation is needed as `OperationVc` types can be stored outside of the call graph as part
130    /// of [`State`][crate::State]s.
131    pub fn connect(self) -> Vc<T> {
132        let tt = turbo_tasks();
133        tt.connect_task(self.task);
134        Self::into_raw(self).into()
135    }
136
137    /// Returns the `RawVc` corresponding to this `OperationVc`.
138    /// inverse of [`RawVc::as_task_output`]
139    fn into_raw(vc: Self) -> RawVc {
140        RawVc::task_output(vc.task)
141    }
142
143    /// Upcasts the given `OperationVc<T>` to a `OperationVc<Box<dyn K>>`.
144    ///
145    /// This is also available as an `Into`/`From` conversion.
146    #[inline(always)]
147    pub fn upcast<K>(vc: Self) -> OperationVc<K>
148    where
149        T: UpcastStrict<K>,
150        K: VcValueTrait + ?Sized,
151    {
152        OperationVc {
153            task: vc.task,
154            _t: PhantomData,
155        }
156    }
157
158    /// [Connects the `OperationVc`][Self::connect] and resolves the reference until it points to a
159    /// cell directly.
160    ///
161    /// Resolving will wait for task execution to be finished, so that the returned [`ResolvedVc`]
162    /// points to a cell that stores a value.
163    ///
164    /// Resolving is necessary to compare identities of [`Vc`]s.
165    ///
166    /// Use [`.strongly_consistent()`][ResolveOperationVcFuture::strongly_consistent] to opt into
167    /// strong consistency.
168    pub fn resolve(self) -> ResolveOperationVcFuture<T> {
169        ResolveOperationVcFuture {
170            inner: self.connect().resolve(),
171        }
172    }
173
174    /// [Connects the `OperationVc`][Self::connect] and returns a [strongly
175    /// consistent][crate::ReadConsistency::Strong] read of the value.
176    ///
177    /// This ensures that all internal tasks are finished before the read is returned.
178    pub fn read_strongly_consistent(self) -> ReadVcFuture<T>
179    where
180        T: VcValueType,
181    {
182        self.connect().node.into_read().strongly_consistent().into()
183    }
184
185    /// [Connects the `OperationVc`][Self::connect] and returns a [strongly
186    /// consistent][crate::ReadConsistency::Strong] read of the value.
187    ///
188    /// This ensures that all internal tasks are finished before the read is returned.
189    pub fn read_trait_strongly_consistent(self) -> ReadVcFuture<T, VcValueTraitCast<T>>
190    where
191        T: VcValueTrait,
192    {
193        self.connect().into_trait_ref().strongly_consistent()
194    }
195}
196
197impl<T> Copy for OperationVc<T> where T: ?Sized {}
198
199impl<T> Clone for OperationVc<T>
200where
201    T: ?Sized,
202{
203    fn clone(&self) -> Self {
204        *self
205    }
206}
207
208impl<T> Hash for OperationVc<T>
209where
210    T: ?Sized,
211{
212    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
213        self.task.hash(state);
214    }
215}
216
217impl<T> PartialEq<OperationVc<T>> for OperationVc<T>
218where
219    T: ?Sized,
220{
221    fn eq(&self, other: &Self) -> bool {
222        self.task == other.task
223    }
224}
225
226impl<T> Eq for OperationVc<T> where T: ?Sized {}
227
228impl<T> Debug for OperationVc<T>
229where
230    T: ?Sized,
231{
232    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
233        f.debug_struct("OperationVc")
234            .field("task", &self.task)
235            .finish()
236    }
237}
238
239// NOTE: This uses the default implementation of `is_resolved` which returns `true` because we don't
240// want `OperationVc` arguments to get resolved when passed to a `#[turbo_tasks::function]`.
241impl<T> TaskInput for OperationVc<T>
242where
243    T: ?Sized + Send + Sync,
244{
245    fn is_transient(&self) -> bool {
246        self.task.is_transient()
247    }
248}
249
250impl<T> TryFrom<RawVc> for OperationVc<T>
251where
252    T: ?Sized,
253{
254    type Error = anyhow::Error;
255
256    fn try_from(raw: RawVc) -> Result<Self> {
257        let Some(task) = raw.as_task_output() else {
258            anyhow::bail!("Given RawVc {raw:?} is not a TaskOutput");
259        };
260        Ok(Self {
261            task,
262            _t: PhantomData,
263        })
264    }
265}
266
267impl<T> TraceRawVcs for OperationVc<T>
268where
269    T: ?Sized,
270{
271    fn trace_raw_vcs(&self, trace_context: &mut crate::trace::TraceRawVcsContext) {
272        Self::into_raw(*self).trace_raw_vcs(trace_context);
273    }
274}
275
276impl<T> CollectiblesSource for OperationVc<T>
277where
278    T: ?Sized,
279{
280    fn drop_collectibles<Vt: VcValueTrait>(self) {
281        let tt = turbo_tasks();
282        let map = tt.read_task_collectibles(self.task, Vt::get_trait_type_id());
283        tt.unemit_collectibles(Vt::get_trait_type_id(), &map);
284    }
285
286    fn take_collectibles<Vt: VcValueTrait>(self) -> AutoSet<ResolvedVc<Vt>> {
287        let tt = turbo_tasks();
288        let map = tt.read_task_collectibles(self.task, Vt::get_trait_type_id());
289        tt.unemit_collectibles(Vt::get_trait_type_id(), &map);
290        map.into_iter()
291            .filter_map(|(raw, count)| (count > 0).then_some(raw.try_into().unwrap()))
292            .collect()
293    }
294
295    fn peek_collectibles<Vt: VcValueTrait>(self) -> AutoSet<ResolvedVc<Vt>> {
296        let tt = turbo_tasks();
297        let map = tt.read_task_collectibles(self.task, Vt::get_trait_type_id());
298        map.into_iter()
299            .filter_map(|(raw, count)| (count > 0).then_some(raw.try_into().unwrap()))
300            .collect()
301    }
302}
303
304/// Indicates that a type does not contain any instances of [`Vc`] or [`ResolvedVc`]. It may contain
305/// [`OperationVc`].
306///
307/// # Safety
308///
309/// This trait is marked as unsafe. You should not derive it yourself, but instead you should rely
310/// on [`#[derive(OperationValue)]`][macro@OperationValue] to do it for you.
311pub unsafe trait OperationValue {}
312
313unsafe impl<T: ?Sized + Send> OperationValue for OperationVc<T> {}
314
315impl_auto_marker_trait!(OperationValue);
turbo_tasks/vc/operation.rs

turbo_tasks/vc/
operation.rs
