"""
This module provides the infrastructure for creating and managing compile package
for torch.compile. We mainly have two abstractions here:
  - CompilePackage: Overarching data structure for store and lookup a list of compiled codes.
  - CodeCacheEntry: Data structure for a single code being compiled by torch.compile.
The caching behavior is always under user control explicitly so that a stronger guarantee can
be provided about cache hit for a specific compiled model. Users can load the compile package
from a different process or host.
"""

import abc
import ast
import contextlib
import dataclasses
import functools
import hashlib
import importlib
import inspect
import io
import itertools
import json
import logging
import os
import pickle
import platform
import shutil
import sys
import types
from collections.abc import Callable, Generator, Iterator
from contextlib import nullcontext
from typing import Any, IO, NewType, Optional, TYPE_CHECKING, Union
from typing_extensions import Never

import torch
from torch._dynamo.exc import PackageError
from torch._dynamo.graph_utils import _graph_device_types
from torch.utils.weak import WeakIdKeyDictionary

from .bytecode_transformation import (
    COMPILED_FN_PREFIX,
    get_code_keys,
    is_compiled_fn_name,
)
from .utils import CleanupHook, counters, dynamo_timed, increment_frame


logger = logging.getLogger(__name__)


if TYPE_CHECKING:
    from .guards import GuardManagerWrapper, GuardsState


_CODE_CACHE = WeakIdKeyDictionary()


def _code_cache(fn: Callable[..., Any]) -> Callable[..., Any]:
    def _(
        cls: type[Any], code: Union["SerializedCode", types.CodeType]
    ) -> Union["SerializedCode", types.CodeType]:
        if code in _CODE_CACHE:
            return _CODE_CACHE[code]
        res = fn(cls, code)
        _CODE_CACHE[code] = res
        return res

    return _


@dataclasses.dataclass(frozen=True)
class SerializedCode:
    co_argcount: int
    co_posonlyargcount: int
    co_kwonlyargcount: int
    co_nlocals: int
    co_stacksize: int
    co_flags: int
    co_code: bytes
    co_consts: tuple[Any, ...]
    co_names: tuple[str, ...]
    co_varnames: tuple[str, ...]
    co_filename: str
    co_name: str
    co_firstlineno: int
    co_cellvars: tuple[str, ...]
    co_freevars: tuple[str, ...]
    co_linetable: bytes | None = None
    co_qualname: str | None = None
    co_exceptiontable: bytes | None = None
    co_lnotab: str | None = None

    @classmethod
    @_code_cache
    def from_code_object(cls, code: types.CodeType) -> "SerializedCode":
        kwargs = {key: getattr(code, key) for key in get_code_keys()}
        kwargs["co_consts"] = tuple(
            cls.from_code_object(c) if isinstance(c, types.CodeType) else c
            for c in kwargs["co_consts"]
        )
        return cls(**kwargs)

    @classmethod
    @_code_cache
    def to_code_object(cls, serialized_code: "SerializedCode") -> types.CodeType:
        kwargs = {key: getattr(serialized_code, key) for key in get_code_keys()}
        kwargs["co_consts"] = tuple(
            cls.to_code_object(c) if isinstance(c, SerializedCode) else c
            for c in kwargs["co_consts"]
        )
        return types.CodeType(
            *kwargs.values(),
        )


class _Missing:
    def __init__(self, reason: str | None = None) -> None:
        self._reason = reason

    def __repr__(self) -> str:
        return f"_Missing({self._reason})"

    def __str__(self) -> str:
        return f"_Missing({self._reason})"

    # Sometimes _Missing object is used as the callable with functools.partial,
    # so we add a dummy __call__ here to bypass TypeError from partial().
    def __call__(self, *args: Any, **kwargs: Any) -> Any:
        return _Missing()


# The one persistent id a guards state may carry: a guards-state pickler emits it
# for a pruned value that the C pickler saves by type (an exact builtin
# container) without ever consulting reducer_override, and _GuardsStateUnpickler
# turns it back into _Missing. Any other persistent id in a guards state is a
# bug. An artifact is only ever read by the torch that wrote it (SystemInfo's
# check_compatibility runs before load_guards_state), so no reader from before
# this id existed sees one.
_PRUNED_VALUE_PID = "pruned"


class FunctionPicklerBase(pickle.Pickler):
    """Reducers for objects pickle cannot rebuild by reference: code objects,
    closure cells, python modules, bound methods, and functions rebuilt from
    their code object.

    GuardsStatePickler and AOTCompilePickler each keep their own dispatch and
    decide what a rebuilt function carries; this class fixes HOW it is rebuilt,
    so a fix here cannot be missed in one pickler.

    Defaults, kwdefaults, __doc__, __dict__, __annotations__ and __type_params__
    travel as pickle STATE, applied after memoization, so `wrapper.me = wrapper`
    cycles end. A closure cell and the globals snapshot are reduce ARGUMENTS: a
    function closing over itself, or stored in its own module snapshot, is
    reduced twice, and save_reduce's recursive-object fallback (present in both
    the C and the pure-Python pickler) drops the outer copy.
    """

    # The reducers stay classmethods: pickle reduces a bound classmethod to
    # getattr(owner, name), so an artifact names the subclass and resolves the
    # reducer through its MRO. A staticmethod would pickle by __qualname__ and
    # change the artifact.
    @classmethod
    def _unpickle_code(cls, serialized_code: SerializedCode) -> types.CodeType:
        return SerializedCode.to_code_object(serialized_code)

    @classmethod
    def _unpickle_python_module(cls, name: str) -> types.ModuleType:
        return importlib.import_module(name)

    @classmethod
    def _unpickle_bound_method(cls, func: Any, base: Any) -> types.MethodType:
        return types.MethodType(func, base)

    @classmethod
    def _unpickle_empty_cell(cls) -> types.CellType:
        return types.CellType()

    @classmethod
    def _set_cell_contents(cls, cell: types.CellType, state: tuple[Any]) -> None:
        # The contents travel wrapped in a 1-tuple: pickle skips the state step
        # entirely when the state object is None, and None is an ordinary cell
        # value that must not come back as an empty cell.
        cell.cell_contents = state[0]

    @classmethod
    def _build_function(
        cls,
        f_globals: dict[str, object],
        module: Any,
        code: types.CodeType,
        qualname: str,
        name: str,
        closure: tuple[types.CellType, ...] | None,
    ) -> types.FunctionType:
        fn = types.FunctionType(code, f_globals, name, None, closure)
        # FunctionType derives __module__ from f_globals["__name__"], which is
        # not what the live function had (functools.wraps copied it, a decorator
        # set it, or it is None), so restore the recorded value unconditionally
        # rather than relying on the scope. Only the stub objects to a non-str;
        # the runtime setter accepts any object.
        fn.__module__ = module  # type: ignore[assignment]
        fn.__qualname__ = qualname
        return fn

    @classmethod
    def _unpickle_fn_from_module(
        cls,
        scope: Any,
        module: Any,
        code: types.CodeType,
        qualname: str,
        name: str,
        closure: tuple[types.CellType, ...] | None,
    ) -> types.FunctionType:
        # `scope` is the __name__ of the module dict the code was compiled
        # against (fn.__globals__), which is what the body reads at call time;
        # `module` is fn.__module__, restored as an attribute. functools.wraps
        # copies __module__ from the wrappee, so the two differ for a wrapper
        # defined in another file, and a function whose __module__ is None still
        # has a scope. A pickler that guards __globals__ sends the snapshot
        # variant instead. Importing here runs that module's top-level code at
        # load if it is not loaded yet; for a wraps wrapper that is the
        # decorator's module, almost always already imported. A scope that only
        # existed in sys.modules at save (exec-created, transformers_modules.*)
        # comes back empty: safe on the guard-serialization path, which reads
        # attributes off the rebuilt function without calling it; a pickler
        # whose functions are CALLED after load (AOTCompilePickler) sees an
        # empty scope as a NameError at first call, not a load error. "__main__"
        # imports the LOADING process's __main__, as pickle's own by-reference
        # path does; a module that swapped a proxy into sys.modules
        # (torch.backends.cudnn) imports as that proxy, as the old import of
        # __module__ did.
        # Not every __name__ is importable: a <locals>/exec function can carry
        # None or "" (bare globals with no __name__), and a relative name
        # (".rel") or a module whose body raises fails import with something
        # other than ImportError. None of those should fail the load, so require
        # a non-empty str and swallow any Exception from the import into the
        # empty scope (a SystemExit or KeyboardInterrupt still propagates).
        f_globals: dict[str, object] = {}
        why: str | Exception = f"scope {scope!r} is not an importable name"
        if isinstance(scope, str) and scope:
            try:
                f_globals = importlib.import_module(scope).__dict__
            except Exception as e:
                why = e
        if not f_globals:
            logger.debug("rebuilding %s with an empty scope: %s", qualname, why)
        return cls._build_function(f_globals, module, code, qualname, name, closure)

    @classmethod
    def _unpickle_fn_from_snapshot(
        cls,
        scope: dict[str, object],
        module: Any,
        code: types.CodeType,
        qualname: str,
        name: str,
        closure: tuple[types.CellType, ...] | None,
    ) -> types.FunctionType:
        # The scope is a reduce ARGUMENT: every function rebuilt against one
        # module dict shares this one object, which pickle fills in as its items
        # load, so a function reached while the dict is still loading (a
        # module-scope wrapper is itself an item of its own snapshot) still sees
        # the complete scope once the load finishes. Applied as pickle STATE it
        # would have been a copy of whatever had loaded by then.
        return cls._build_function(scope, module, code, qualname, name, closure)

    @classmethod
    def _apply_function_state(
        cls, fn: types.FunctionType, state: tuple[Any, ...]
    ) -> None:
        # Every write here must stay idempotent: for a function that is an item
        # of its own globals snapshot (or closes over itself) the pure-Python
        # pickler applies the state on both save_reduce passes; the C pickler
        # drops the outer pass after the memo fetch, so it runs once there.
        defaults, kwdefaults, attributes, doc, annotations, type_params = state
        fn.__defaults__ = defaults
        fn.__kwdefaults__ = kwdefaults
        # FunctionType() takes __doc__ from the code object and leaves
        # __annotations__/__type_params__ empty (the compiler sets them on the
        # function after creating it);
        # functools.wraps overwrote them on the live function and a guard rooted
        # there rebakes, so restore what the reducer captured.
        fn.__doc__ = doc
        fn.__annotations__ = annotations
        # On Python < 3.12 there is no __type_params__ slot, so both a live
        # function's __type_params__ and the write below land in __dict__.
        # Assign __dict__ first so the reducer's (possibly pruned) type_params
        # wins over whatever the carried __dict__ holds under that key.
        fn.__dict__ = attributes
        if type_params is not None:
            fn.__type_params__ = type_params

    @staticmethod
    def _is_literal(value: object) -> bool:
        # An always-picklable constant: the singletons and scalars dynamo treats
        # as constants, NOT every common_constant_type (torch.finfo/iinfo do not
        # pickle). The guard pickler carries these whether or not a guard reads
        # them: pruning buys nothing and, since _keep matches by id, would make
        # the rebuilt state depend on whether some unrelated guard happened to
        # register the interned value. The AOT pickler skips probing them.
        if value is None or value is Ellipsis or value is NotImplemented:
            return True
        return type(value) in (
            bool,
            int,
            float,
            complex,
            str,
            bytes,
            torch.dtype,
            torch.device,
            torch.layout,
            torch.memory_format,
        )

    @staticmethod
    def _fqn_resolves(fn: types.FunctionType | type) -> bool:
        """Whether pickling fn (a function or a class) by reference (import
        __module__, walk __qualname__) lands back on fn. False for a <locals> one, a functools.wraps
        wrapper (it carries the wrappee's names), an exec-created function, or
        a module absent from sys.modules; pickling those by reference fails at
        dump with PicklingError (a bare AttributeError from the C pickler for a
        <locals> name below 3.14), so the caller rebuilds them from the code
        object (or prunes them). Conservative on purpose: pickle would import a
        module that is not in sys.modules yet, this reports False for it
        (guards.py explains why on its caller), and a "<locals>" qualname
        component is refused like pickle refuses it. GuardsStatePickler handles
        <locals> on its own branch before asking; AOTCompilePickler dispatches
        on this alone."""
        if "<locals>" in fn.__qualname__.split("."):
            return False
        # __module__ need not be a str (a decorator can set anything); an
        # unhashable one must not TypeError out of the reducer.
        module = (
            sys.modules.get(fn.__module__) if isinstance(fn.__module__, str) else None
        )
        if module is None:
            return False
        resolved: object = module
        for name in fn.__qualname__.split("."):
            resolved = getattr(resolved, name, None)
        return resolved is fn

    @staticmethod
    def _read_raw_annotations(obj: Any, *, evaluate: bool = False) -> dict[str, Any]:
        # Reading obj.__annotations__ directly forces PEP 649 lazy evaluation on
        # 3.14+, raising NameError for a TYPE_CHECKING-only name. Ask for the
        # FORWARDREF format instead: it evaluates what it can and falls back to
        # proxies only for names that do not resolve, returning a COPY either
        # way. A ForwardRef proxy carries its owner and may not pickle (it does
        # not for a local function), so the caller prunes any it does not need.
        # `evaluate` asks for the VALUE format instead, for a caller that has to
        # serialize the values and cannot carry a proxy; that read raises for a
        # name that does not resolve. Either format can raise -- FORWARDREF only
        # when the annotation does real work outside a name lookup (formatting a
        # proxy in an f-string, `()[0]`), which the guards.py caller explains --
        # and both are left raising here: whether the set can be dropped is the
        # caller's question, and each caller logs the drop it takes.
        if sys.version_info >= (3, 14):
            import annotationlib

            fmt = annotationlib.Format
            return annotationlib.get_annotations(
                obj, format=fmt.VALUE if evaluate else fmt.FORWARDREF
            )
        return obj.__annotations__

    def _reduce_cell(self, cell: types.CellType) -> tuple[Any, ...]:
        try:
            contents = cell.cell_contents
        except ValueError:
            # A free variable only assigned on a path that did not run.
            return type(self)._unpickle_empty_cell, ()
        return (
            type(self)._unpickle_empty_cell,
            (),
            (contents,),
            None,
            None,
            type(self)._set_cell_contents,
        )

    def _reduce_bound_method(
        self, method: types.MethodType, *, receiver_is_live: bool = False
    ) -> tuple[Callable[..., Any], tuple[Any, ...]] | None:
        # pickle rebuilds a bound method by getattr() on self at load, which is
        # wrong when that does not resolve back to the same bound method; those
        # carry the function and self explicitly. `receiver_is_live` says
        # getattr() on the load-time receiver serves names as it does here (it
        # is handed over as external data, a persistent_id reference), so only
        # the probe below decides; the per-instance and __getattr__ gates exist
        # for a receiver that is rebuilt, possibly as a different type.
        receiver = method.__self__
        cls = type(receiver)
        func = method.__func__
        # A name served PER-INSTANCE (an instance __dict__ monkeypatch such as
        # obj.f = MethodType(f, obj), or a __slots__ member) is carried as
        # func+self explicitly: getattr() at load hands back whatever the dict
        # or slot holds, a raw function or a method bound elsewhere, never a
        # method over this pair, and in the self-cycle case the slot is not even
        # restored yet. The __dict__ clause only sees a receiver that HAS an
        # instance dict, so a pure-slots receiver falls through it to the slot
        # check (a slotted subclass of a non-slotted base has both, and either
        # clause gives the same answer). A class defining __getattr__ (nn.Module
        # included) takes the pair before either gate, without probing.
        # Probing would run that user code, and a subclass may rebuild such a
        # receiver as a DIFFERENT type at load
        # (GuardsStatePickler._unpickle_module turns a non-referenceable module
        # into a bare torch.nn.Module), on which getattr() would not resolve
        # the method. Both gates are skipped for a type receiver (a classmethod;
        # its namespace is restored with the class) and for a live receiver,
        # whose names getattr() serves at load exactly as it does now; those
        # are probed. issubclass(cls, ...) rather than isinstance so a raising
        # __getattribute__ cannot escape before the try below.
        explicit = (type(self)._unpickle_bound_method, (func, receiver))
        exempt = issubclass(cls, type) or receiver_is_live
        try:
            if not exempt and hasattr(cls, "__getattr__"):
                return explicit
            # __name__ is not guaranteed: MethodType accepts any callable, so
            # func may be a functools.partial with no __name__, or a proxy whose
            # __getattr__ raises something other than AttributeError; both fall
            # through to the explicit reduce rather than out of the reducer. Read
            # after the gate above, which takes the pair without probing func.
            name = getattr(func, "__name__", None)
            self_dict = getattr(receiver, "__dict__", None)
            if not exempt and (
                (isinstance(self_dict, dict) and name in self_dict)
                or (
                    name is not None
                    and isinstance(
                        inspect.getattr_static(cls, name, None),
                        types.MemberDescriptorType,
                    )
                )
            ):
                return explicit
            inner = getattr(receiver, name, None) if name is not None else None
        except Exception:
            # A probe that raises anything -- a __getattribute__ override, a
            # metaclass __getattr__ (which hasattr(cls, ...) also reaches), a
            # property -- falls back to the explicit reduce, which is always
            # correct.
            return explicit
        # Only a method BOUND to this receiver over this function proves the
        # class MRO resolves back to it. getattr can also hand back the raw
        # function (a staticmethod under that name), and pickle's default
        # getattr() reconstruction would then load a function where a method was.
        if (
            inspect.ismethod(inner)
            and inner.__func__ is func
            and inner.__self__ is receiver
        ):
            return None
        return explicit

    def _reduce_function(
        self,
        fn: types.FunctionType,
        *,
        defaults: tuple[Any, ...] | None,
        kwdefaults: dict[str, Any] | None,
        closure: tuple[types.CellType, ...] | None,
        attributes: dict[str, Any],
        doc: Any,
        annotations: dict[str, Any],
        type_params: tuple[Any, ...] | None,
        globals_snapshot: dict[str, Any] | None,
    ) -> tuple[Any, ...]:
        # Everything is passed in rather than read off fn: the subclass decides
        # what the rebuilt function carries, and the guard pickler prunes what
        # no guard reads so an unpicklable local class in an annotation -- or a
        # __doc__ reassigned to an unpicklable object -- cannot fail the whole
        # dump (a failure there silently bypasses the package).
        # Both unpicklers take (scope, module, code, qualname, name, closure):
        # the scope is the module NAME to import or the snapshot dict itself.
        args = (fn.__module__, fn.__code__, fn.__qualname__, fn.__name__, closure)
        if globals_snapshot is None:
            unpickle = type(self)._unpickle_fn_from_module
            args = (fn.__globals__.get("__name__"), *args)
        else:
            unpickle = type(self)._unpickle_fn_from_snapshot
            args = (globals_snapshot, *args)
        state = (defaults, kwdefaults, attributes, doc, annotations, type_params)
        return unpickle, args, state, None, None, type(self)._apply_function_state


@dataclasses.dataclass
class _GuardedCodeCacheEntry:
    """
    Contains the serializable information associated with a single compilation in dynamo.
    To restore an execution of compiled code, we will need to serialize the following data:
      - Dynamo bytecode for mapping Python inputs/outputs.
      - Dynamo guards.
    """

    guards_state: bytes
    dynamo_code: SerializedCode


class _GuardsStateUnpickler(pickle.Unpickler):
    def __init__(self, file: IO[bytes]) -> None:
        super().__init__(file)
        # One sentinel per load for every pruned container, aliases and distinct
        # ones alike (reducer_override's memo would keep distinct ones distinct;
        # a _Missing carries nothing but its reason, so collapsing them loses
        # nothing). Per load rather than per process: loaded values are keyed
        # by id elsewhere, and one artifact's sentinel has no business in another.
        self._pruned = _Missing(_PRUNED_VALUE_PID)

    def persistent_load(self, pid: str) -> _Missing:
        if pid != _PRUNED_VALUE_PID:
            raise pickle.UnpicklingError(f"unknown guards state persistent id {pid!r}")
        return self._pruned


def load_guards_state(guards_state: bytes) -> Any:
    try:
        import torch.distributed.fsdp._fully_shard._fully_shard as _fully_shard

        ctx = _fully_shard.disable_fsdp_module_new_init()
    except ImportError:
        ctx = nullcontext()  # type: ignore[assignment]
    with ctx:
        return _GuardsStateUnpickler(io.BytesIO(guards_state)).load()


def load_guard_manager(
    guards_state: "GuardsState",
    target_code: types.CodeType,
    runtime_global_scope: Any,
) -> "GuardManagerWrapper":
    # An EMPTY runtime_global_scope is a scope and not the absence of one: a
    # global guard then fails on a name it lacks, rather than falling back to the
    # globals serialized with the artifact, which only None selects.
    from .output_graph import OutputGraphCommon

    return torch._dynamo.guards.CheckFunctionManager(
        target_code,
        OutputGraphCommon(guards_state.output_graph),
        shape_code_parts=guards_state.shape_code_parts,
        runtime_global_scope=runtime_global_scope,
        guard_build_local_state=getattr(guards_state, "local_state", None),
    ).guard_manager


_BackendId = NewType("_BackendId", str)  # __compiled_fn
_FunctionId = NewType("_FunctionId", str)  # __resume_at


def _backend_ids_from_code(code: types.CodeType) -> Iterator[_BackendId]:
    for name in code.co_names:
        if is_compiled_fn_name(name):
            yield _BackendId(name)
    for const in code.co_consts:
        if isinstance(const, types.CodeType):
            yield from _backend_ids_from_code(const)


@dataclasses.dataclass(frozen=True)
class InlinedSource:
    module: str
    firstlineno: int
    lastlineno: int
    checksum: str
    content: str


@functools.cache
def _get_module_content(module: types.ModuleType) -> str:
    return inspect.getsource(module)


@dataclasses.dataclass
class SourceInfo:
    inlined_sources: set[InlinedSource]

    def add_code(self, code: types.CodeType) -> None:
        module = inspect.getmodule(code)
        if module is None:
            return
        sourcelines, firstlineno = inspect.getsourcelines(code)
        lastlineno = firstlineno + len(sourcelines)
        source = "".join(sourcelines)
        if source != "".join(_get_sourcelines(module, firstlineno, lastlineno)):
            raise AssertionError(
                f"Source mismatch for {module.__name__} "
                f"(line {firstlineno}-{lastlineno})"
            )
        self.inlined_sources.add(
            InlinedSource(
                module=module.__name__,
                firstlineno=firstlineno,
                lastlineno=lastlineno,
                checksum=_hash_source(source),
                content=_get_module_content(module),
            )
        )


@dataclasses.dataclass
class _DynamoCodeCacheEntry:
    """
    Contains the serializable information associated with a single code object
    in dynamo. To restore an execution of compiled code, we will need the following
    ingredients:
      1. The "original" code object, which serves as the entry point for eager
         execution, i.e. the code only executed when there's no cache entry hit.
      2. The python module name this code object belongs to, for identifying the
         enclosing global scope to inject compiled and resume functions.
      3. A list of function names that pointing to this code object. There could be
         multiple function objects pointing to the same code such as recursive functions.
      4. A list of guarded code that eval frame dispatches to.
      5. A list of imported module objects unioned from all compiled branches.
      6. A list of "backends" (compiled fx graph) unioned from all compiled branches.
      7. A string path used to access the original code object users defined.
         A code object can be accessed by "{python_module}.{function_name}.{code_source}" .
      8. A boolean flag indicating whether the function is installed to global scope.
      9. A boolean flag indicating whether the function has a compile id.
      10. Whether the entry currently has nothing installable: every compile of
         it was bypassed (its guards could not be serialized), or a backend
         artifact was missing when the package was saved. install() then leaves
         the frame to be traced fresh rather than skipping it as trivial.
         Cleared once a compile records a guarded code. The save-time writer,
         PrecompileCacheEntry.from_cache_entry, flags the whole entry when any
         one of its backend artifacts is missing; CompilePackage.initialize then
         loads it without its stale guarded codes and backend ids, every variant
         of that code object included, since install() would have used none.
         TODO(#196773): prune only the guarded codes whose bytecode names the
         missing backend at write time, so the other variants stay installable.
    """

    python_code: SerializedCode
    python_module: str
    function_names: list[_FunctionId]
    guarded_codes: list[_GuardedCodeCacheEntry]
    import_sources: dict[str, str]
    backend_ids: list[_BackendId]
    code_source: str | None
    install_to_global: bool
    has_compile_id: bool = False
    bypassed: bool = False


def _lookup_code(entry: _DynamoCodeCacheEntry) -> types.CodeType:
    if len(entry.function_names) != 1:
        raise AssertionError(
            f"Expected exactly one function name, got {len(entry.function_names)}"
        )
    fn: Any = sys.modules[entry.python_module]
    parts = entry.function_names[0].split(".")
    for part in parts:
        fn = getattr(fn, part)
    if entry.code_source:
        parts = entry.code_source.split(".")
        for part in parts:
            if part.endswith("]"):
                index_begin = part.rfind("[")
                if not isinstance(index_begin, int):
                    raise AssertionError(
                        f"Expected int for index_begin, got {type(index_begin)}"
                    )
                if index_begin < 0:
                    raise AssertionError(
                        f"Expected non-negative index_begin, got {index_begin}"
                    )
                attr = getattr(fn, part[:index_begin], None)
                if attr is None:
                    raise PackageError(f"Cannot find source for code entry {entry}")
                fn = attr[ast.literal_eval(part[index_begin + 1 : -1])]
            else:
                fn = getattr(fn, part)
    else:
        raise PackageError(f"Cannot find source for code entry {entry}")
    if not isinstance(fn, types.CodeType):
        raise AssertionError(
            f"Expected CodeType, got {type(fn)} for code entry {entry}"
        )
    return fn


def _raise_resolution_error(code: types.CodeType, scope: Any) -> Never:
    raise PackageError(
        f"Cannot resolve a fully qualified name for {code}. Lookup scope: {scope}"
    )


def _get_code_source(code: types.CodeType) -> tuple[str, str]:
    """
    Given a code object, return a fully qualified name which will be used as
    a serialized handle to access the code object from the new process.
    This is normally a straightforward process, but there are some corner cases:
    1. When a function is defined with decorator, then this function will be captured
       inside a closure with the wrapper object.
    2. When a function is defined as a nested function, then the code object will be
       stored on the co_consts field of the parent code object by Python compiler.
    This function handles all of the corner cases above.
    """

    module = inspect.getmodule(code)
    if module is None:
        raise PackageError(f"Cannot find module for code {code}")

    toplevel: Any = module
    if sys.version_info >= (3, 11):
        parts = code.co_qualname.split(".")

        for part in parts:
            if not hasattr(toplevel, part):
                _raise_resolution_error(code, toplevel)
            toplevel = getattr(toplevel, part)
            if inspect.isfunction(toplevel) or inspect.ismethod(toplevel):
                break
    seen = set()

    def _find_code_source(obj: Any) -> str | None:
        nonlocal toplevel
        nonlocal seen
        if obj in seen:
            return None

        seen.add(obj)

        if inspect.iscode(obj):
            if obj is code:
                return ""

            for i, const in enumerate(obj.co_consts):
                if (res := _find_code_source(const)) is not None:
                    return f".co_consts[{i}]{res}"

        if inspect.ismethod(obj):
            if (res := _find_code_source(obj.__func__)) is not None:
                toplevel = obj
                return f".__func__{res}"

        if inspect.isfunction(obj):
            if (res := _find_code_source(obj.__code__)) is not None:
                toplevel = obj
                return f".__code__{res}"
            if obj.__closure__ is not None:
                for i, cell in enumerate(obj.__closure__):
                    try:
                        cell_contents = cell.cell_contents
                    except ValueError:
                        continue
                    if not (
                        inspect.isfunction(cell_contents)
                        or inspect.iscode(cell_contents)
                        or inspect.ismethod(cell_contents)
                    ):
                        continue
                    if (res := _find_code_source(cell_contents)) is not None:
                        toplevel = obj
                        return f".__closure__[{i}].cell_contents{res}"

        if sys.version_info < (3, 11):
            if inspect.ismodule(obj):
                for value in obj.__dict__.values():
                    if not (
                        inspect.isfunction(value)
                        or inspect.isclass(value)
                        or inspect.ismethod(value)
                    ):
                        continue
                    if (res := _find_code_source(value)) is not None:
                        return res

            if inspect.isclass(obj):
                for name in itertools.chain(obj.__dict__.keys(), dir(obj)):
                    try:
                        value = getattr(obj, name)
                    except AttributeError:
                        continue
                    if not (
                        inspect.isfunction(value)
                        or inspect.isclass(value)
                        or inspect.ismethod(value)
                    ):
                        continue
                    if (res := _find_code_source(value)) is not None:
                        if value.__name__ != name:
                            _raise_resolution_error(code, toplevel)
                        return res
        return None

    code_source = _find_code_source(toplevel)
    if code_source is None:
        _raise_resolution_error(code, toplevel)
    return toplevel.__qualname__, code_source.strip(".")


@dataclasses.dataclass(frozen=True)
class SystemInfo:
    """
    System information including Python, PyTorch, and GPU details.
    This information is used to ensure compiled artifacts can only be loaded
    with compatible system configurations.
    """

    python_version: str
    torch_version: str
    toolkit_version: str | None
    triton_version: tuple[int, int] | None
    gpu_name: str | None
    CHECK_GPUS = ("cuda", "xpu")

    @classmethod
    def current(cls) -> "SystemInfo":
        """Create a SystemInfo instance with current system information."""
        # Get GPU name if CUDA or XPU is available
        gpu_name = None
        from torch.utils._triton import get_triton_version

        gpu_name, toolkit_version = None, None
        for device_type in cls.CHECK_GPUS:
            if getattr(torch, device_type).is_available():
                try:
                    gpu_name = getattr(torch, device_type).get_device_name()
                    toolkit_version = getattr(torch.version, device_type)
                    break
                except Exception:
                    pass

        return cls(
            python_version=platform.python_version(),
            torch_version=torch.__version__,
            toolkit_version=toolkit_version,
            triton_version=get_triton_version((0, 0)),
            gpu_name=gpu_name,
        )

    def check_compatibility(
        self, other: "SystemInfo", device_type: str = "cpu"
    ) -> None:
        """
        Check if this SystemInfo is compatible with another SystemInfo.
        Raises RuntimeError if incompatible.
        """
        if self.python_version != other.python_version:
            raise RuntimeError(
                f"Compile package was created with a different Python version: {self.python_version}"
            )

        if self.torch_version != other.torch_version:
            raise RuntimeError(
                f"Compile package was created with a different PyTorch version: {self.torch_version}"
            )
        if device_type in self.CHECK_GPUS:
            if not getattr(torch, device_type).is_available():
                raise RuntimeError(f"{device_type} is not available")

            if self.toolkit_version != other.toolkit_version:
                raise RuntimeError(
                    f"Compile package was created with a different toolkit version: {self.toolkit_version}"
                )

            if (
                other.triton_version != (0, 0)
                and self.triton_version != other.triton_version
            ):
                raise RuntimeError(
                    f"Compile package was created with a different Triton version: {self.triton_version}"
                )

            # Check GPU name if CUDA/XPU was used
            if other.gpu_name is not None and self.gpu_name != other.gpu_name:
                raise RuntimeError(
                    f"Compile package was created with different GPU: "
                    f"cached={self.gpu_name}, current={other.gpu_name}"
                )


def _collapse_device_types(device_types: frozenset[str]) -> str:
    """The single device type a package or an AOT artifact records: an
    accelerator wins over cpu, and naming no device reads as cpu. Among several
    accelerators one in `SystemInfo.CHECK_GPUS` wins, since any other name skips
    the load check; the rest tie alphabetically. One string cannot say that a
    graph needs two accelerators: it records the preferred one, and the load
    check is for that one.
    """
    for device_type in SystemInfo.CHECK_GPUS:
        if device_type in device_types:
            return device_type
    return next((d for d in sorted(device_types) if d != "cpu"), "cpu")


@dataclasses.dataclass
class _DynamoCacheEntry:
    codes: list[_DynamoCodeCacheEntry]
    source_info: SourceInfo
    device_type: str
    system_info: SystemInfo = dataclasses.field(default_factory=SystemInfo.current)
    fn_name: str | None = None
    fn_first_lineno: str | None = None

    @property
    def backend_ids(self) -> set[_BackendId]:
        return {backend_id for code in self.codes for backend_id in code.backend_ids}

    def check_versions(self) -> None:
        """Check if the current system is compatible with the system used to create this cache entry."""
        current_system_info = SystemInfo.current()
        self.system_info.check_compatibility(current_system_info, self.device_type)

    def debug_info(self) -> dict[str, Any]:
        if len(self.codes) == 0:
            raise AssertionError("Expected at least one code entry")
        return {
            "num_codes": str(len(self.codes)),
            "fn_name": self.fn_name,
            "fn_first_lineno": self.fn_first_lineno,
            "device_type": self.device_type,
            "backend_ids": list(self.backend_ids),
        }


from torch.compiler._cache import (
    CacheArtifact,
    CacheArtifactFactory,
    CacheArtifactRecorder,
)


@CacheArtifactFactory.register
class PrecompileCacheArtifact(CacheArtifact):
    def populate_cache(self) -> None:
        DynamoCache._write_to_local_cache(self.content, self.key)

    @staticmethod
    def type() -> str:
        return "precompile"


@dataclasses.dataclass
class PrecompileCacheEntry:
    """
    A full cache entry for caching precompile, for a toplevel torch.compile.
    Consists of a _DynamoCacheEntry, which contains all the dynamo related contents,
    and a set of backends content. In general, the backend content here will always
    be of type precompile_context.BackendCacheArtifact
    """

    dynamo: _DynamoCacheEntry
    backends: dict[_BackendId, Any]

    @staticmethod
    def from_cache_entry(
        cache_entry: _DynamoCacheEntry, backends: dict[_BackendId, Any]
    ) -> Optional["PrecompileCacheEntry"]:
        backend_content: dict[_BackendId, Any] = {}

        for code in cache_entry.codes:
            for backend_id in code.backend_ids:
                if backend_id not in backends:
                    logger.warning("Backend not found")
                    debug_str = json.dumps(
                        {
                            "entry": cache_entry.debug_info(),
                            "missing_backend": backend_id,
                        }
                    )
                    torch._logging.trace_structured(
                        "artifact",
                        metadata_fn=lambda: {
                            "name": "dynamo_cache_bypass",
                            "encoding": "json",
                        },
                        payload_fn=lambda: debug_str,
                        expect_trace_id=False,
                    )
                    code.bypassed = True
                    break
                else:
                    backend_content[backend_id] = backends[backend_id]

        return PrecompileCacheEntry(dynamo=cache_entry, backends=backend_content)


def _hash_source(source: str) -> str:
    sha256_hash = hashlib.sha256()
    sha256_hash.update(source.encode())
    return sha256_hash.hexdigest()


def _get_sourcelines(
    m: types.ModuleType, firstlineno: int, lastlineno: int
) -> list[str]:
    return inspect.getsourcelines(m)[0][firstlineno - 1 : lastlineno - 1]


def _hash_sourcelines(m: types.ModuleType, firstlineno: int, lastlineno: int) -> str:
    return _hash_source("".join(_get_sourcelines(m, firstlineno, lastlineno)))


def _compile_frame_context(
    code: types.CodeType,
) -> contextlib.AbstractContextManager[None]:
    from torch._dynamo.convert_frame import get_compile_id, log_dynamo_start
    from torch._guards import compile_context, CompileContext

    # Each code represents a new compile frame
    # recompiles on the same frame are all saved
    # under the same cache entry, so we don't have recompile ids
    # i.e. If cold start had 0/0, 0/1, 1/0, 1/1, these would be
    # collapsed into 0/0, 1/0 on warm.
    # pyrefly: ignore [deprecated]
    @contextlib.contextmanager
    def _ctx() -> Iterator[None]:
        increment_frame()
        compile_id = get_compile_id(frame_state={})
        with (
            compile_context(CompileContext(compile_id)),
            dynamo_timed(
                "_compile.compile_inner",
                phase_name="entire_frame_compile",
                dynamo_compile_column_us="dynamo_cumulative_compile_time_us",
                # TODO: save all relevant compilation metrics
                metadata={
                    "frame_key": str(torch._dynamo.utils.curr_frame),
                    "co_name": code.co_name,
                    "co_filename": code.co_filename,
                    "co_firstlineno": code.co_firstlineno,
                },
            ),
        ):
            log_dynamo_start(code)
            yield

    return _ctx()


class CompilePackage:
    """
    CompilePackage is considered a low level component and should not be directly exposed to
    end users. It has the following interface:

    1. `CompilePackage.__init__()` which optionally takes previously serialized dynamo states.
        a. when `dynamo` argument is None, it will construct a brand new CompilePackage object.
        b. when `dynamo` argument is not None, it will load a pre-compiled dynamo state.
    2. `package.save()` which dumps the dynamo and backend states to a DynamoCacheEntry object.
    3. `package.install(backends) which will handle all the side-effectful global scope
        updates with compiled functions and resume functions.
    """

    def __init__(
        self,
        fn: Callable[..., Any] | None,
        dynamo: _DynamoCacheEntry | None = None,
        ignore_inlined_sources: bool = False,
    ) -> None:
        self._innermost_fn = None
        self._codes: dict[types.CodeType, _DynamoCodeCacheEntry] = {}

        self._current_entry: _DynamoCodeCacheEntry | None = None
        # Backend ids the compile inside the current code_context NEWLY added
        # to the entry, so a bypass drops exactly those and never a backend an
        # earlier, installed variant of the same code object still needs.
        self._current_backend_ids: list[_BackendId] = []
        self._installed_globals: dict[types.ModuleType, list[str]] = {}
        # Every device type the graphs compiled into this package named.
        self._device_types: frozenset[str] = frozenset()

        # For debugging/testing purpose only.
        self._cached_backends: dict[_BackendId, Any] = {}
        self._source_info: SourceInfo = SourceInfo(inlined_sources=set())
        self._resume_codes: set[types.CodeType] = set()
        self._initialized = False
        if fn is not None:
            self.initialize(fn, dynamo, ignore_inlined_sources)
            self.uninstall()
            self.validate()

    def is_initialized(self) -> bool:
        return self._initialized

    def initialize(
        self,
        fn: Any,
        dynamo: _DynamoCacheEntry | None = None,
        ignore_inlined_sources: bool = False,
    ) -> None:
        from .eval_frame import innermost_fn

        if self._initialized:
            raise AssertionError("CompilePackage is already initialized")
        self._source_info = SourceInfo(inlined_sources=set())
        self._innermost_fn = innermost_fn(fn)  # type: ignore[assignment]
        if self._innermost_fn is None:
            raise AssertionError("innermost_fn returned None")
        if dynamo is not None:
            if not isinstance(dynamo, _DynamoCacheEntry):
                raise AssertionError(f"Expected _DynamoCacheEntry, got {type(dynamo)}")
            dynamo.check_versions()
            if not ignore_inlined_sources:
                for code in dynamo.source_info.inlined_sources:
                    m = importlib.import_module(code.module)
                    checksum = _hash_sourcelines(m, code.firstlineno, code.lastlineno)
                    if checksum != code.checksum:
                        raise RuntimeError(
                            f"Source code changes detected for {code.module} (line {code.firstlineno} - line {code.lastlineno})"
                        )

                self._source_info = dynamo.source_info

            main, *codes = dynamo.codes
            self._codes = {self._innermost_fn.__code__: main}
            for code in codes:
                self._codes[SerializedCode.to_code_object(code.python_code)] = code
            for key, code in self._codes.items():
                if code.bypassed:
                    # install() skips a bypassed entry entirely, so its guarded
                    # codes and backend ids are dead; start from a copy without
                    # them so the fresh compile's record replaces them and the
                    # next save writes an installable entry. A copy, not a
                    # clear, with the mutable containers the fresh compile
                    # writes to (import_sources, function_names) detached too:
                    # the caller's entry may be a store's own object
                    # (InMemoryDynamoStore hands out what it holds).
                    self._codes[key] = dataclasses.replace(
                        code,
                        guarded_codes=[],
                        backend_ids=[],
                        function_names=list(code.function_names),
                        import_sources=dict(code.import_sources),
                    )
            # The codes come back, so the device they recorded must too, or one
            # recompile after a reload re-saves the entry as what that frame
            # alone named. The collapse is a maximum under one order, so
            # re-collapsing its string with later frames gives what the full
            # set would: the re-saved string is never below the loaded one.
            self._device_types = frozenset((dynamo.device_type,))
        else:
            self._add_function(
                self._innermost_fn.__code__, self._innermost_fn.__module__
            )
        self._initialized = True

    def _add_function(
        self,
        python_code: types.CodeType,
        python_module: str,
        function_name: _FunctionId | None = None,
        code_source: str | None = None,
        install_to_global: bool = False,
    ) -> None:
        if python_code not in self._codes:
            code = _DynamoCodeCacheEntry(
                python_code=SerializedCode.from_code_object(python_code),
                python_module=python_module,
                function_names=[],
                guarded_codes=[],
                import_sources={},
                backend_ids=[],
                code_source=code_source,
                install_to_global=install_to_global,
            )
            self._codes[python_code] = code
        else:
            code = self._codes[python_code]
            if code.python_module != python_module:
                raise AssertionError(
                    f"python_module mismatch: {code.python_module} != {python_module}"
                )
            if code.install_to_global != install_to_global:
                raise AssertionError(
                    f"install_to_global mismatch: {code.install_to_global} != {install_to_global}"
                )
            if code.code_source != code_source:
                raise AssertionError(
                    f"code_source mismatch: {code.code_source} != {code_source}"
                )

        if function_name is not None:
            code.function_names.append(function_name)

    @property
    def cached_backends(self) -> dict[_BackendId, Any]:
        return self._cached_backends

    @functools.cached_property
    def source_id(self) -> str:
        if self._innermost_fn is None:
            raise AssertionError("_innermost_fn is not set")
        return CompilePackage.source_id_from_fn(self._innermost_fn)

    def _add_user_function(self, code: types.CodeType) -> None:
        function_name, code_source = _get_code_source(code)
        module = inspect.getmodule(code)
        if module is None:
            raise PackageError(f"Cannot find module for code {code}")
        self._add_function(
            code,
            module.__name__,
            function_name=_FunctionId(function_name),
            code_source=code_source,
        )

    @property
    def current_entry(self) -> _DynamoCodeCacheEntry | None:
        """The entry of the code object being compiled inside ``code_context``."""
        return self._current_entry

    @contextlib.contextmanager
    def code_context(self, code: types.CodeType) -> Generator[None, None, None]:
        if self._current_entry is not None:
            raise AssertionError("_current_entry is already set in code_context")

        # Sometimes user code cannot be inlined in dynamo resulting in extra user code
        # being compiled. We should record these as when they are actually invoked.
        if code not in self._codes:
            self._add_user_function(code)

        entry = self._codes[code]
        self._current_entry = entry
        self._current_backend_ids = []
        try:
            yield
        finally:
            entry.has_compile_id = True
            self._current_entry = None
            self._current_backend_ids = []

    def add_guarded_code(
        self,
        guards_state: bytes,
        dynamo_code: types.CodeType,
    ) -> None:
        if self._current_entry is None:
            raise AssertionError("_current_entry is not set in add_guarded_code")
        guarded_code_entry = _GuardedCodeCacheEntry(
            guards_state=guards_state,
            dynamo_code=SerializedCode.from_code_object(dynamo_code),
        )
        self._current_entry.guarded_codes.append(guarded_code_entry)
        self._current_entry.bypassed = False
        for backend_id in _backend_ids_from_code(dynamo_code):
            self._add_backend_id(backend_id)

    def add_inlined_source(self, sources: list[types.CodeType]) -> None:
        if self._current_entry is None:
            raise AssertionError("_current_entry is not set in add_inlined_source")
        for code in sources:
            if code in self._resume_codes:
                continue
            self._source_info.add_code(code)

    def update_device_type(self, graph: torch.fx.Graph | None) -> None:
        # One call per compiled frame, and a package spans frames (a graph
        # break adds a resume code), so accumulate: a cpu-only resume frame
        # must not erase the accelerator an earlier frame named.
        self._device_types |= _graph_device_types(graph)

    def bypass_current_compile(self) -> None:
        """Drop the backend ids the current compile registered on its entry.

        Only this compile is lost: its guarded code is never recorded
        (convert_frame consults output.package, which bypass_package clears,
        before add_guarded_code) and the backend ids it registered go with it. Guarded
        codes an earlier compile of the same code object recorded stay
        installable, so a reload keeps them and only re-traces the inputs that
        would have matched the dropped one. An entry left with no guarded code
        is marked bypassed so install() re-traces the frame instead of skipping
        it as trivial.
        """
        if self._current_entry is None:
            raise AssertionError("_current_entry is not set in bypass_current_compile")
        for backend_id in self._current_backend_ids:
            self._current_entry.backend_ids.remove(backend_id)
            self._cached_backends.pop(backend_id, None)
        self._current_backend_ids = []
        self._current_entry.bypassed = not self._current_entry.guarded_codes

    def add_resume_function(
        self,
        python_code: types.CodeType,
        python_module: str,
        function_name: str,
    ) -> None:
        self._add_function(
            python_code,
            python_module,
            function_name=_FunctionId(function_name),
            install_to_global=True,
        )
        self._resume_codes.add(python_code)

    def add_import_source(self, alias: str, module_name: str) -> None:
        if self._current_entry is None:
            raise AssertionError("_current_entry is not set in add_import_source")
        self._current_entry.import_sources[alias] = module_name

    def _add_backend_id(
        self, backend_id: _BackendId, backend: Any | None = None
    ) -> None:
        if self._current_entry is None:
            raise AssertionError("_current_entry is not set in add_backend_id")
        if backend_id not in self._current_entry.backend_ids:
            self._current_entry.backend_ids.append(backend_id)
            self._current_backend_ids.append(backend_id)
        if backend is not None:
            self._cached_backends[backend_id] = backend

    def add_backend_id(self, backend_id: str, backend: Any | None = None) -> None:
        if not backend_id.startswith(f"{COMPILED_FN_PREFIX}_"):
            raise AssertionError(
                f"backend_id must start with '{COMPILED_FN_PREFIX}_', got '{backend_id}'"
            )
        self._add_backend_id(_BackendId(backend_id), backend)

    def validate(self) -> None:
        if self._current_entry is not None:
            raise AssertionError("_current_entry should be None during validate")
        if self._innermost_fn is None:
            raise AssertionError("_innermost_fn is not set during validate")
        if not self._initialized:
            raise AssertionError("CompilePackage is not initialized during validate")
        if next(iter(self._codes)) is not self._innermost_fn.__code__:
            raise AssertionError(
                "First code entry does not match _innermost_fn.__code__"
            )

    def _install_global(
        self,
        module: types.ModuleType,
        name: str,
        value: object,
        *,
        record_only_if_new: bool = False,
    ) -> None:
        # A pre-reset compile in this process may still own `name` via a
        # CleanupHook that hasn't fired yet. We're taking over the binding now,
        # so that hook must not delete it once its code object is collected.
        CleanupHook.disown(module.__dict__, name)
        record = not (record_only_if_new and name in module.__dict__)
        module.__dict__[name] = value
        if record:
            self._installed_globals.setdefault(module, []).append(name)

    def uninstall(self) -> None:
        from torch._C._dynamo.eval_frame import _reset_precompile_entries

        if self._innermost_fn is None:
            raise AssertionError("_innermost_fn is not set in uninstall")
        for module, names in self._installed_globals.items():
            for name in names:
                module.__dict__.pop(name, None)

        self._installed_globals = {}

        _reset_precompile_entries(self._innermost_fn.__code__)

    def install(self, backends: dict[_BackendId, Any]) -> None:
        """
        Sync the package states to the compiled function. This includes the following actions:
          1. Clean up the previously installed states.
          2. Install the compiled functions to global scopes.
          3. Install the precompiled cache entries to ExtraStates on the code object.
        """
        from torch._C._dynamo.eval_frame import _load_precompile_entry

        from .convert_frame import input_codes
        from .output_graph import get_builtins_dict

        self.uninstall()
        for code, entry in self._codes.items():
            context = (
                _compile_frame_context(code)
                if entry.has_compile_id
                else contextlib.nullcontext()
            )
            with context:
                module = sys.modules[entry.python_module]
                # An __import_* alias someone else bound first may be held BY
                # REFERENCE by a loaded artifact's guards --
                # AOTCompiledFunction._seed_guard_scope seeds those aliases into
                # a live module scope and nothing re-seeds them -- so uninstall()
                # must leave a binding this package did not create alone. The
                # aliases are the only names install() records that are ever
                # seeded that way.
                for alias, module_name in entry.import_sources.items():
                    self._install_global(
                        module,
                        alias,
                        importlib.import_module(module_name),
                        record_only_if_new=True,
                    )
                target_code = code
                if entry.install_to_global:
                    for function_name in entry.function_names:
                        if code.co_freevars:
                            # Resume functions with freevars need a factory
                            # that takes a closure tuple, matching
                            # install_resume_function_global in output_graph.py.
                            f_globals = module.__dict__
                            fn_name = function_name

                            def _make_fn(
                                closure: tuple[types.CellType, ...],
                                _code: types.CodeType = code,
                                _globals: dict[str, Any] = f_globals,
                                _name: str = fn_name,
                            ) -> types.FunctionType:
                                return types.FunctionType(
                                    _code, _globals, _name, None, closure
                                )

                            self._install_global(module, function_name, _make_fn)
                        else:
                            fn = types.FunctionType(
                                code, module.__dict__, function_name
                            )
                            self._install_global(module, function_name, fn)
                if entry.code_source:
                    target_code = _lookup_code(entry)

                if entry.bypassed:
                    # If the entry is bypassed, do not install backends
                    # or guarded codes.
                    continue

                input_codes.add(target_code)
                for backend_id in entry.backend_ids:
                    if backend_id not in backends:
                        raise RuntimeError(
                            f"Backend {backend_id} is not found in the given backends"
                        )
                    with dynamo_timed(
                        "after_deserialization", phase_name="backend_compile"
                    ):
                        backend = backends[backend_id].after_deserialization()
                        self._install_global(
                            module,
                            backend_id,
                            torch._dynamo.disable(backend),
                        )

                if len(entry.guarded_codes) == 0:
                    # Dynamo generates empty graph for trivial functions, should just skip them
                    # in these cases.
                    torch._dynamo.eval_frame.skip_code(target_code)

                for guarded_code in entry.guarded_codes:
                    with dynamo_timed("precompile_load_guards"):
                        guards_state = load_guards_state(guarded_code.guards_state)
                    runtime_global_scope = sys.modules[entry.python_module].__dict__
                    # The installed builtins dict might be absent from the runtime
                    # while loading guards. Populate it if it's missing.
                    if (
                        builtin_dict_name
                        := guards_state.output_graph.name_of_builtins_dict_key_in_fglobals
                    ):
                        # A pre-reset compile's CleanupHook may still own this
                        # name even when we're about to leave its value alone
                        # below (same dict object every compile in this
                        # module), so it must not delete it once collected.
                        CleanupHook.disown(runtime_global_scope, builtin_dict_name)
                        builtins_dict = get_builtins_dict(runtime_global_scope)
                        if builtin_dict_name in runtime_global_scope:
                            if (
                                runtime_global_scope[builtin_dict_name]
                                is not builtins_dict
                            ):
                                raise AssertionError(
                                    f"Builtins dict mismatch for key '{builtin_dict_name}'"
                                )
                        else:
                            runtime_global_scope[builtin_dict_name] = builtins_dict
                    if not isinstance(guards_state, torch._dynamo.guards.GuardsState):
                        raise AssertionError(
                            f"Expected GuardsState, got {type(guards_state)}"
                        )
                    with dynamo_timed("precompile_build_guards"):
                        guard_manager = load_guard_manager(
                            guards_state, target_code, runtime_global_scope
                        )
                    _load_precompile_entry(
                        target_code,
                        guard_manager,
                        SerializedCode.to_code_object(guarded_code.dynamo_code),
                    )

    def cache_entry(self) -> _DynamoCacheEntry:
        self.validate()
        if self._innermost_fn is None:
            raise AssertionError("_innermost_fn is not set in cache_entry")
        return _DynamoCacheEntry(
            codes=list(self._codes.values()),
            source_info=self._source_info,
            device_type=_collapse_device_types(self._device_types),
            fn_name=self._innermost_fn.__qualname__,
            fn_first_lineno=self._innermost_fn.__code__.co_firstlineno,
        )

    @staticmethod
    def source_id_from_fn(fn: Callable[..., Any]) -> str:
        from .eval_frame import innermost_fn

        innermost_fn_ = innermost_fn(fn)

        sha256_hash = hashlib.sha256()
        sha256_hash.update(innermost_fn_.__qualname__.encode())
        sha256_hash.update(str(innermost_fn_.__code__.co_firstlineno).encode())
        return sha256_hash.hexdigest()


_Backends = dict[_BackendId, Any]


class DynamoStore(abc.ABC):
    """
    A DynamoStore tracks active CompilePackages, and provides methods to store and retrieve them.

    This is an abstract base class for different storage implementations.
    """

    def record_package(self, package: CompilePackage) -> None:
        """
        Records a package to PrecompileContext, so that it can be serialized later.
        """
        from torch._dynamo.precompile_context import PrecompileContext

        cache_entry = package.cache_entry()
        PrecompileContext.record_dynamo_cache_entry(
            cache_entry=cache_entry, key=package.source_id
        )

    def record_eager_backend(self, backend_id: _BackendId, backend: Any) -> None:
        """
        Records eager fx graphs to PrecompileContext for testing purposes.
        """
        from torch._dynamo.precompile_context import (
            EagerCacheArtifact,
            PrecompileContext,
        )

        result = EagerCacheArtifact(key=backend_id, content=backend)
        PrecompileContext.record_artifact(result)

    @abc.abstractmethod
    def clear(self) -> None: ...

    @abc.abstractmethod
    def write(
        self,
        cache_entry: PrecompileCacheEntry,
        path: str,
    ) -> None:
        """
        Abstract method to write dynamo cache entry and backends to storage.

        Args:
            dynamo: The dynamo cache entry to write
            backends: Dictionary of backend content to write
            path: Path or key to identify where to write the data
        """
        ...

    def save_cache_entry(self, cache_entry: _DynamoCacheEntry, key: str) -> None:
        """
        Saves a package to a given path. Grabs backends from PrecompileContext.
        """
        from torch._dynamo.precompile_context import (
            BackendCacheArtifact,
            PrecompileContext,
        )

        backend_content: _Backends = {}
        for backend_id in cache_entry.backend_ids:
            serialized_backend = PrecompileContext.serialize_artifact_by_key(backend_id)
            if serialized_backend is None:
                raise RuntimeError(
                    f"Backend {backend_id} is not found in the given backends"
                )
            if not isinstance(serialized_backend, BackendCacheArtifact):
                raise AssertionError(
                    f"Expected BackendCacheArtifact, got {type(serialized_backend)}"
                )
            backend_content[backend_id] = serialized_backend

        entry = PrecompileCacheEntry(cache_entry, backend_content)

        self.write(entry, key)

    def save_package(self, package: CompilePackage, key: str) -> None:
        """
        Saves a package to a given path. Grabs backends from PrecompileContext.
        """
        self.record_package(package)
        cache_entry = package.cache_entry()
        self.save_cache_entry(cache_entry, key)

    @abc.abstractmethod
    def read(self, path: str) -> PrecompileCacheEntry:
        """
        Abstract method to read dynamo cache entry and backends from storage.

        Args:
            path: Path or key to identify where to read the data from

        Returns:
            A tuple containing (dynamo_cache_entry, backend_content)
        """
        ...

    def load_cache_entry(self, key: str) -> PrecompileCacheEntry:
        from torch._dynamo.precompile_context import (
            BackendCacheArtifact,
            PrecompileContext,
        )

        precompile_entry = self.read(key)
        for backend in precompile_entry.backends.values():
            if not isinstance(backend, BackendCacheArtifact):
                raise AssertionError(
                    f"Expected BackendCacheArtifact, got {type(backend)}"
                )
            PrecompileContext.record_artifact(backend)

        return precompile_entry

    def load_package(
        self, fn: Any, key: str
    ) -> tuple[CompilePackage, dict[_BackendId, Any]]:
        """
        Loads a package from a given path and returns it plus a list of deserialized backends
        """
        entry = self.load_cache_entry(key)
        package = CompilePackage(fn, entry.dynamo)
        return package, entry.backends


class InMemoryDynamoStore(DynamoStore):
    """
    A DynamoStore implementation that keeps state about CompilePackages in memory.
    """

    def __init__(self) -> None:
        self.packages: dict[str, PrecompileCacheEntry] = {}

    def clear(self) -> None:
        self.packages.clear()

    def write(
        self,
        cache_entry: PrecompileCacheEntry,
        path: str,
    ) -> None:
        """
        Store the dynamo cache entry and backends in memory instead of writing to disk.
        """
        self.packages[path] = cache_entry

    def read(self, path: str) -> PrecompileCacheEntry:
        """
        Read dynamo cache entry and backends from memory.
        """
        if path not in self.packages:
            raise RuntimeError(f"No package found with key {path}")

        return self.packages[path]


class DiskDynamoStore(DynamoStore):
    """
    A DynamoStore implementation that keeps state about CompilePackages on disk.
    """

    def __init__(self, path_prefix: str = "") -> None:
        """
        Initialize a DiskDynamoStore with a path prefix.

        Args:
            path_prefix: Prefix directory for where to put CompilePackages on disk
        """
        self._path_prefix = path_prefix

    def path_prefix(self) -> str:
        return self._path_prefix

    def clear(self) -> None:
        """
        Clear all CompilePackages from disk.
        """
        if self.path_prefix():
            shutil.rmtree(self.path_prefix(), ignore_errors=True)

    def write(
        self,
        cache_entry: PrecompileCacheEntry,
        path: str,
    ) -> None:
        """
        Write dynamo cache entry and backends to disk.
        """
        try:
            pickled_content: bytes = pickle.dumps(cache_entry)
            CacheArtifactRecorder(PrecompileCacheArtifact.type(), path).record(
                pickled_content
            )
            self._write_to_local_cache(pickled_content, path)
        except Exception as e:
            raise RuntimeError(f"Failed to save package to {path}: {e}") from e

    def _write_to_local_cache(self, pickled_content: bytes, path: str) -> None:
        from torch._inductor.codecache import write_atomic

        path = os.path.join(self.path_prefix(), path) if self.path_prefix() else path
        try:
            os.makedirs(path, exist_ok=True)
            write_atomic(os.path.join(path, "entry"), pickled_content)
        except Exception as e:
            raise RuntimeError(f"Failed to save package to {path}: {e}") from e

    def read(self, path: str) -> PrecompileCacheEntry:
        """
        Read dynamo cache entry and backends from disk.
        """
        path = os.path.join(self.path_prefix(), path) if self.path_prefix() else path
        try:
            with open(os.path.join(path, "entry"), "rb") as f:
                pickled_content = f.read()
                entry = pickle.loads(pickled_content)
                return entry
        except Exception as e:
            raise RuntimeError(f"Failed to load package from path {path}: {e}") from e


class DiskDynamoCache(DiskDynamoStore):
    """
    Special DiskDynamoStore which adds some helper functions for automatically
    tracking paths of packages
    """

    def save(self, package: CompilePackage) -> None:
        """
        Saves a package to a given path. Grabs backends from PrecompileContext.
        """
        key = package.source_id
        logger.info("Saving CompilePackage for %s", package.source_id)
        super().save_package(package, key)

    def load(self, fn: Callable[..., Any]) -> PrecompileCacheEntry | None:
        """
        Loads a package from a given path and returns it plus a list of deserialized backends
        """
        key = CompilePackage.source_id_from_fn(fn)
        logger.info("Loading CompilePackage for %s", key)
        path = os.path.join(self.path_prefix(), key)
        if os.path.exists(path):
            try:
                result = super().load_cache_entry(key)
                counters["dynamo_cache"]["dynamo_cache_hit"] += 1
                return result
            except Exception:
                counters["dynamo_cache"]["dynamo_cache_error"] += 1
                logger.warning(
                    "Failed to load package from path %s", path, exc_info=True
                )
                return None
        logger.info("No package found for %s", key)
        counters["dynamo_cache"]["dynamo_cache_miss"] += 1
        return None

    def load_and_install_package(self, fn: Callable[..., Any]) -> CompilePackage | None:
        """
        Load directly into a package and install backends
        """
        results = self.load(fn)
        if results is None:
            return None
        else:
            package = CompilePackage(fn, results.dynamo)
            package.install(results.backends)
            return package

    def path_prefix(self) -> str:
        return os.path.join(cache_dir(), "dynamo")


def cache_dir() -> str:
    from torch._inductor.runtime.cache_dir_utils import cache_dir

    return cache_dir()


DynamoCache = DiskDynamoCache(os.path.join(cache_dir(), "dynamo"))
