turbo_tasks/vc/

resolved.rs

use std::{
    any::Any,
    fmt::Debug,
    future::IntoFuture,
    hash::{Hash, Hasher},
    marker::PhantomData,
    ops::Deref,
    slice,
};

use anyhow::Result;
use bincode::{Decode, Encode};
use serde::{Deserialize, Serialize};

#[cfg(debug_assertions)]
use crate::debug::{ValueDebug, ValueDebugFormat, ValueDebugFormatString};
use crate::{
    RawVc, Upcast, UpcastStrict, VcRead, VcTransparentRead, VcValueTrait, VcValueType,
    trace::{TraceRawVcs, TraceRawVcsContext},
    vc::Vc,
};

/// A "subtype" (via [`Deref`]) of [`Vc`] that represents a specific [`Vc::cell`]/`.cell()` or
/// [`ResolvedVc::cell`]/`.resolved_cell()` constructor call within [a task][macro@crate::function].
///
/// Unlike [`Vc`], `ResolvedVc`:
///
/// - Does not potentially refer to task-local information, meaning that it implements
///   [`NonLocalValue`], and can be used in any [`#[turbo_tasks::value]`][macro@crate::value].
///
/// - Has only one potential internal representation, meaning that it has a saner equality
///   definition.
///
/// - Points to a concrete value with a type, and is therefore [cheap to
///   downcast][ResolvedVc::try_downcast].
///
///
/// ## Construction
///
/// There are a few ways to construct a `ResolvedVc`, in order of preference:
///
/// 1. Given a [value][VcValueType], construct a `ResolvedVc` using [`ResolvedVc::cell`] (for
///    "transparent" values) or by calling the generated `.resolved_cell()` constructor on the value
///    type.
///
/// 2. Given an argument to a function using the [`#[turbo_tasks::function]`][macro@crate::function]
///    macro, change the argument's type to a `ResolvedVc`. The [rewritten external signature] will
///    still use [`Vc`], but when the function is called, the [`Vc`] will be resolved.
///
/// 3. Given a [`Vc`], use [`.to_resolved().await?`][Vc::to_resolved].
///
///
/// ## Reading a `ResolvedVc`
///
/// Even though a `Vc` may be resolved as a `ResolvedVc`, we must still use `.await?` to read it's
/// value, as the value could be invalidated or cache-evicted.
///
///
/// ## Equality & Hashing
///
/// Equality between two `ResolvedVc`s means that both have an identical in-memory representation
/// and point to the same cell. The implementation of [`Hash`] has similar behavior.
///
/// If `.await`ed at the same time, both would likely resolve to the same [`ReadRef`], though it is
/// possible that they may not if the cell is invalidated between `.await`s.
///
/// Because equality is a synchronous operation that cannot read the cell contents, even if the
/// `ResolvedVc`s are not equal, it is possible that if `.await`ed, both `ResolvedVc`s could point
/// to the same or equal values.
///
///
/// [`NonLocalValue`]: crate::NonLocalValue
/// [rewritten external signature]: https://turbopack-rust-docs.vercel.sh/turbo-engine/tasks.html#external-signature-rewriting
/// [`ReadRef`]: crate::ReadRef
#[derive(Serialize, Deserialize, Encode, Decode)]
#[serde(transparent, bound = "")]
#[bincode(bounds = "T: ?Sized")]
#[repr(transparent)]
pub struct ResolvedVc<T>
where
    T: ?Sized,
{
    pub(crate) node: Vc<T>,
}

impl<T> ResolvedVc<T>
where
    T: ?Sized,
{
    /// This function exists to intercept calls to Vc::to_resolved through dereferencing
    /// a ResolvedVc. Converting to Vc and re-resolving it puts unnecessary stress on
    /// the turbo tasks engine.
    #[deprecated(note = "No point in resolving a vc that is already resolved")]
    pub async fn to_resolved(self) -> Result<Self> {
        Ok(self)
    }
    #[deprecated(note = "No point in resolving a vc that is already resolved")]
    pub async fn resolve(self) -> Result<Vc<T>> {
        Ok(self.node)
    }
}

impl<T> Copy for ResolvedVc<T> where T: ?Sized {}

impl<T> Clone for ResolvedVc<T>
where
    T: ?Sized,
{
    fn clone(&self) -> Self {
        *self
    }
}

impl<T> Deref for ResolvedVc<T>
where
    T: ?Sized,
{
    type Target = Vc<T>;

    fn deref(&self) -> &Self::Target {
        &self.node
    }
}

impl<T> PartialEq<ResolvedVc<T>> for ResolvedVc<T>
where
    T: ?Sized,
{
    fn eq(&self, other: &Self) -> bool {
        self.node == other.node
    }
}

impl<T> Eq for ResolvedVc<T> where T: ?Sized {}

impl<T> Hash for ResolvedVc<T>
where
    T: ?Sized,
{
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.node.hash(state);
    }
}

impl<T, Inner> Default for ResolvedVc<T>
where
    T: VcValueType<Read = VcTransparentRead<T, Inner>>,
    Inner: Any + Send + Sync + Default,
{
    fn default() -> Self {
        Self::cell(Default::default())
    }
}

macro_rules! into_future {
    ($ty:ty) => {
        impl<T> IntoFuture for $ty
        where
            T: VcValueType,
        {
            type Output = <Vc<T> as IntoFuture>::Output;
            type IntoFuture = <Vc<T> as IntoFuture>::IntoFuture;
            fn into_future(self) -> Self::IntoFuture {
                (*self).into_future()
            }
        }
    };
}

into_future!(ResolvedVc<T>);
into_future!(&ResolvedVc<T>);
into_future!(&mut ResolvedVc<T>);

impl<T> ResolvedVc<T>
where
    T: VcValueType,
{
    // called by the `.resolved_cell()` method generated by the `#[turbo_tasks::value]` macro
    #[doc(hidden)]
    pub fn cell_private(inner: <T::Read as VcRead<T>>::Target) -> Self {
        Self {
            node: Vc::<T>::cell_private(inner),
        }
    }
}

impl<T, Inner> ResolvedVc<T>
where
    T: VcValueType<Read = VcTransparentRead<T, Inner>>,
    Inner: Any + Send + Sync,
{
    pub fn cell(inner: Inner) -> Self {
        Self {
            node: Vc::<T>::cell(inner),
        }
    }
}

impl<T> ResolvedVc<T>
where
    T: ?Sized,
{
    /// Upcasts the given `ResolvedVc<T>` to a `ResolvedVc<Box<dyn K>>`.
    ///
    /// See also: [`Vc::upcast`].
    #[inline(always)]
    pub fn upcast<K>(this: Self) -> ResolvedVc<K>
    where
        T: UpcastStrict<K>,
        K: VcValueTrait + ?Sized,
    {
        Self::upcast_non_strict(this)
    }

    /// Upcasts the given `ResolvedVc<T>` to a `ResolvedVc<Box<dyn K>>`.
    ///
    /// This has a loose type constraint which would allow upcasting to the same type, prefer using
    /// [`ResolvedVc::upcast`] when possible. See also: [`Vc::upcast_non_strict`].  This is
    /// useful for extension traits and other more generic usecases.
    #[inline(always)]
    pub fn upcast_non_strict<K>(this: Self) -> ResolvedVc<K>
    where
        T: Upcast<K>,
        K: VcValueTrait + ?Sized,
    {
        ResolvedVc {
            node: Vc::upcast_non_strict(this.node),
        }
    }

    /// Upcasts the given `Vec<ResolvedVc<T>>` to a `Vec<ResolvedVc<K>>`.
    ///
    /// See also: [`Vc::upcast`].
    #[inline(always)]
    pub fn upcast_vec<K>(vec: Vec<Self>) -> Vec<ResolvedVc<K>>
    where
        T: UpcastStrict<K>,
        K: VcValueTrait + ?Sized,
    {
        debug_assert!(size_of::<ResolvedVc<T>>() == size_of::<ResolvedVc<K>>());
        debug_assert!(size_of::<Vec<ResolvedVc<T>>>() == size_of::<Vec<ResolvedVc<K>>>());
        let (ptr, len, capacity) = vec.into_raw_parts();
        // Safety: The memory layout of `ResolvedVc<T>` and `ResolvedVc<K>` is the same.
        unsafe { Vec::from_raw_parts(ptr as *mut ResolvedVc<K>, len, capacity) }
    }

    /// Cheaply converts a Vec of resolved Vcs to a Vec of Vcs.
    pub fn deref_vec(vec: Vec<ResolvedVc<T>>) -> Vec<Vc<T>> {
        debug_assert!(size_of::<ResolvedVc<T>>() == size_of::<Vc<T>>());
        let (ptr, len, capacity) = vec.into_raw_parts();
        // Safety: The memory layout of `ResolvedVc<T>` and `Vc<T>` is the same.
        unsafe { Vec::from_raw_parts(ptr as *mut Vc<T>, len, capacity) }
    }

    /// Cheaply converts a slice of resolved Vcs to a slice of Vcs.
    pub fn deref_slice(s: &[ResolvedVc<T>]) -> &[Vc<T>] {
        debug_assert!(size_of::<ResolvedVc<T>>() == size_of::<Vc<T>>());
        // Safety: The memory layout of `ResolvedVc<T>` and `Vc<T>` is the same.
        unsafe { slice::from_raw_parts(s.as_ptr() as *const Vc<T>, s.len()) }
    }
}

impl<T> ResolvedVc<T>
where
    T: VcValueTrait + ?Sized,
{
    /// Returns `None` if the underlying value type does not implement `K`.
    ///
    /// **Note:** if the trait `T` is required to implement `K`, use [`ResolvedVc::upcast`] instead.
    /// That method provides stronger guarantees, removing the need for a [`Option`] return type.
    pub fn try_sidecast<K>(this: Self) -> Option<ResolvedVc<K>>
    where
        K: VcValueTrait + ?Sized,
    {
        // Runtime assertion to catch K == T cases with a clear error message
        // This will be optimized away in release builds but helps during development
        // We use trait type IDs since T and K might be trait objects (?Sized)
        debug_assert!(
            <K as VcValueTrait>::get_trait_type_id() != <T as VcValueTrait>::get_trait_type_id(),
            "Attempted to cast a type {} to itself, which is pointless. Use the value directly \
             instead.",
            crate::registry::get_trait(<T as VcValueTrait>::get_trait_type_id())
                .ty
                .global_name
        );
        // `RawVc::TaskCell` already contains all the type information needed to check this
        // sidecast, so we don't need to read the underlying cell!
        let raw_vc = this.node.node;
        raw_vc
            .resolved_has_trait(<K as VcValueTrait>::get_trait_type_id())
            .then_some(ResolvedVc {
                node: Vc {
                    node: raw_vc,
                    _t: PhantomData,
                },
            })
    }

    /// Attempts to downcast the given `ResolvedVc<Box<dyn T>>` to a `ResolvedVc<K>`, where `K`
    /// is of the form `Box<dyn L>`, and `L` is a value trait.
    ///
    /// Returns `None` if the underlying value type is not a `K`.
    pub fn try_downcast<K>(this: Self) -> Option<ResolvedVc<K>>
    where
        K: UpcastStrict<T> + VcValueTrait + ?Sized,
    {
        // this is just a more type-safe version of a sidecast
        Self::try_sidecast(this)
    }

    /// Attempts to downcast the given `Vc<Box<dyn T>>` to a `Vc<K>`, where `K` is a value type.
    ///
    /// Returns `None` if the underlying value type is not a `K`.
    pub fn try_downcast_type<K>(this: Self) -> Option<ResolvedVc<K>>
    where
        K: UpcastStrict<T> + VcValueType,
    {
        let raw_vc = this.node.node;
        raw_vc
            .resolved_is_type(<K as VcValueType>::get_value_type_id())
            .then_some(ResolvedVc {
                node: Vc {
                    node: raw_vc,
                    _t: PhantomData,
                },
            })
    }
}

/// Generates an opaque debug representation of the [`ResolvedVc`] itself, but not the data inside
/// of it.
///
/// This is implemented to allow types containing [`ResolvedVc`] to implement the synchronous
/// [`Debug`] trait, but in most cases users should use the [`ValueDebug`] implementation to get a
/// string representation of the contents of the cell.
impl<T> Debug for ResolvedVc<T>
where
    T: ?Sized,
{
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_tuple("ResolvedVc").field(&self.node.node).finish()
    }
}

impl<T> TraceRawVcs for ResolvedVc<T>
where
    T: ?Sized,
{
    fn trace_raw_vcs(&self, trace_context: &mut TraceRawVcsContext) {
        TraceRawVcs::trace_raw_vcs(&self.node, trace_context);
    }
}

#[cfg(debug_assertions)]
impl<T> ValueDebugFormat for ResolvedVc<T>
where
    T: UpcastStrict<Box<dyn ValueDebug>> + Send + Sync + ?Sized,
{
    fn value_debug_format(&self, depth: usize) -> ValueDebugFormatString<'_> {
        self.node.value_debug_format(depth)
    }
}

impl<T> TryFrom<RawVc> for ResolvedVc<T>
where
    T: ?Sized,
{
    type Error = anyhow::Error;

    fn try_from(raw: RawVc) -> Result<Self> {
        if !matches!(raw, RawVc::TaskCell(..)) {
            anyhow::bail!("Given RawVc {raw:?} is not a TaskCell");
        }
        Ok(Self {
            node: Vc::from(raw),
        })
    }
}