SSAValue

SSAValue dataclass

Bases: Generic[AttributeCovT], IRWithUses, ABC

A reference to an SSA variable. An SSA variable is either an operation result, or a basic block argument.

Source code in xdsl/ir/core.py

@dataclass(eq=False)
class SSAValue(Generic[AttributeCovT], IRWithUses, ABC):
    """
    A reference to an SSA variable.
    An SSA variable is either an operation result, or a basic block argument.
    """

    _type: AttributeCovT
    """Each SSA variable is associated to a type."""

    _name: str | None = field(init=False, default=None)

    _name_regex: ClassVar[re.Pattern[str]] = re.compile(r"([A-Za-z_$.-][\w$.-]*)")

    @property
    def type(self) -> AttributeCovT:
        return self._type

    @property
    @abstractmethod
    def owner(self) -> Operation | Block:
        """
        An SSA variable is either an operation result, or a basic block argument.
        This property returns the Operation or Block that currently defines a specific value.
        """
        pass

    @property
    def name_hint(self) -> str | None:
        return self._name

    @name_hint.setter
    def name_hint(self, name: str | None):
        # only allow valid names
        if SSAValue.is_valid_name(name):
            # Remove `_` followed by numbers at the end of the name
            if name is not None:
                r1 = re.compile(r"(_\d+)+$")
                if match := r1.search(name):
                    name = name[: match.start()]
            self._name = name
        else:
            raise ValueError(
                "Invalid SSA Value name format!",
                r"Make sure names contain only characters of [A-Za-z0-9_$.-] and don't start with a number!",
            )

    @classmethod
    def is_valid_name(cls, name: str | None):
        return name is None or cls._name_regex.fullmatch(name)

    @staticmethod
    def get(arg: SSAValue | Operation) -> SSAValue:
        "Get a new SSAValue from either a SSAValue, or an operation with a single result."
        match arg:
            case SSAValue():
                return arg
            case Operation():
                if len(arg.results) == 1:
                    return arg.results[0]
                raise ValueError(
                    "SSAValue.build: expected operation with a single result."
                )

    def replace_by(self, value: SSAValue) -> None:
        """Replace the value by another value in all its uses."""
        for use in self.uses.copy():
            use.operation.operands[use.index] = value
        # carry over name if possible
        if value.name_hint is None:
            value.name_hint = self.name_hint
        assert not self.uses, "unexpected error in xdsl"

    def replace_by_if(self, value: SSAValue, test: Callable[[Use], bool]):
        """
        Replace the value by another value in all its uses that pass the given test
        function.
        """
        for use in self.uses.copy():
            if test(use):
                use.operation.operands[use.index] = value
        # carry over name if possible
        if value.name_hint is None:
            value.name_hint = self.name_hint

    def erase(self, safe_erase: bool = True) -> None:
        """
        Erase the value.
        If safe_erase is True, then check that no operations use the value anymore.
        If safe_erase is False, then replace its uses by an ErasedSSAValue.
        """
        if safe_erase and len(self.uses) != 0:
            raise Exception(
                "Attempting to delete SSA value that still has uses of result "
                f"of operation:\n{self.owner}"
            )
        self.replace_by(ErasedSSAValue(self.type, self))

    def __hash__(self):
        """
        Make SSAValue hashable. Two SSA Values are never the same, therefore
        the use of `id` is allowed here.
        """
        return id(self)

    def __eq__(self, other: object) -> bool:
        return self is other

owner: Operation | Block abstractmethod property

An SSA variable is either an operation result, or a basic block argument. This property returns the Operation or Block that currently defines a specific value.

get(arg: SSAValue | Operation) -> SSAValue staticmethod

Get a new SSAValue from either a SSAValue, or an operation with a single result.

Source code in xdsl/ir/core.py

@staticmethod
def get(arg: SSAValue | Operation) -> SSAValue:
    "Get a new SSAValue from either a SSAValue, or an operation with a single result."
    match arg:
        case SSAValue():
            return arg
        case Operation():
            if len(arg.results) == 1:
                return arg.results[0]
            raise ValueError(
                "SSAValue.build: expected operation with a single result."
            )

replace_by(value: SSAValue) -> None

Replace the value by another value in all its uses.

Source code in xdsl/ir/core.py

def replace_by(self, value: SSAValue) -> None:
    """Replace the value by another value in all its uses."""
    for use in self.uses.copy():
        use.operation.operands[use.index] = value
    # carry over name if possible
    if value.name_hint is None:
        value.name_hint = self.name_hint
    assert not self.uses, "unexpected error in xdsl"

replace_by_if(value: SSAValue, test: Callable[[Use], bool])

Replace the value by another value in all its uses that pass the given test function.

Source code in xdsl/ir/core.py

def replace_by_if(self, value: SSAValue, test: Callable[[Use], bool]):
    """
    Replace the value by another value in all its uses that pass the given test
    function.
    """
    for use in self.uses.copy():
        if test(use):
            use.operation.operands[use.index] = value
    # carry over name if possible
    if value.name_hint is None:
        value.name_hint = self.name_hint

erase(safe_erase: bool = True) -> None

Erase the value. If safe_erase is True, then check that no operations use the value anymore. If safe_erase is False, then replace its uses by an ErasedSSAValue.

Source code in xdsl/ir/core.py

def erase(self, safe_erase: bool = True) -> None:
    """
    Erase the value.
    If safe_erase is True, then check that no operations use the value anymore.
    If safe_erase is False, then replace its uses by an ErasedSSAValue.
    """
    if safe_erase and len(self.uses) != 0:
        raise Exception(
            "Attempting to delete SSA value that still has uses of result "
            f"of operation:\n{self.owner}"
        )
    self.replace_by(ErasedSSAValue(self.type, self))

__hash__()

Make SSAValue hashable. Two SSA Values are never the same, therefore the use of id is allowed here.

Source code in xdsl/ir/core.py

def __hash__(self):
    """
    Make SSAValue hashable. Two SSA Values are never the same, therefore
    the use of `id` is allowed here.
    """
    return id(self)

Use dataclass

The use of a SSA value.

Source code in xdsl/ir/core.py

@dataclass(frozen=True)
class Use:
    """The use of a SSA value."""

    operation: Operation
    """The operation using the value."""

    index: int
    """The index of the operand using the value in the operation."""

operation: Operation instance-attribute

The operation using the value.

index: int instance-attribute

The index of the operand using the value in the operation.