Struct IValue

Struct Documentation

struct c10::IValue

IValue (Interpreter Value) is a tagged union over the types supported by the TorchScript interpreter.

IValues contain their values as an IValue::Payload, which holds primitive types (int64_t, bool, double, Device) and Tensor as values, and all other types as a c10::intrusive_ptr. In order to optimize performance of the destructor and related operations by making the Tensor and c10::intrusive_ptr paths generate the same code, we represent a null c10::intrusive_ptr as UndefinedTensorImpl::singleton(), not nullptr.

IValues are used as inputs to and outputs from the TorchScript interpreter. To retrieve the value contained within an IValue, use the .toX() methods, where X is the type you are trying to get. Note that neither the .toX() methods nor the templated .to<T> functions do any kind of casting, they only unwrap the contained value. For example:

// Make the IValue
torch::IValue my_ivalue(26);
std::cout << my_ivalue << "\n";

// Unwrap the IValue
int64_t my_int = my_ivalue.toInt();
std::cout << my_int << "\n";

// This will throw an error!
// `my_ivalue` is tagged as an int and cannot be used as another type
torch::Tensor my_tensor = my_ivalue.toTensor();

Public Types

using enable_if_ivalue_constructible = std::enable_if_t<std::is_constructible<IValue, T>::value, std::nullptr_t>
using HashAliasedIValues = std::unordered_set<IValue, HashAliasedIValue, CompAliasedIValues>
using HashAliasedIValueMap = std::unordered_map<IValue, IValue, HashAliasedIValue, CompAliasedIValues>

Public Functions

IValue(const IValue &rhs)
IValue(IValue &&rhs) noexcept
IValue &operator=(IValue &&rhs) & noexcept
IValue &operator=(IValue const &rhs) &
void dump() const
IValue equals(const IValue &rhs) const

Equality comparison.

The semantics are the same as Python’s ==:

  1. Numerical types are compared by value.

  2. Tensors compute element-wise equality, returning a BoolTensor (see: torch.eq())

  3. Strings are compared by value.

  4. Sequence types (list, tuple) are compared lexicographically by comparing their elements. Different sequence types never compare equal.

  5. Mappings (dict) must have equal (key, value) pairs.

  6. If not listed above, the default behavior for is to test identity equality (e.g. pointer equality).

Why does this return an IValue instead of a bool? Because in PyTorch, tensor1 == tensor2 returns a BoolTensor, not a bool.

NOTE: we (like Python) assume that identity equality implies value equality for efficiency. TODO: need to support customizing equality

bool is(const IValue &rhs) const

Identity comparison.

Checks if this is the same object as rhs. The semantics are the same as Python’s is operator.

NOTE: Like in Python, this operation is poorly defined for primitive types like numbers and strings. Prefer to use == unless you really want to check identity equality.

IValue hash() const

Hashing for IValues.

Returns an IValue-boxed int.

Some notes:

  • Like eager, Tensors are hashed by looking at the pointer. This is not strictly correct because two value-equal tensors with different tensor pointers will hash differently, but we choose to reproduce the eager semantics.

  • Hashing is not defined on all built-in IValue types (e.g. list and dict), following Python. Calling hash() on these types will throw.

IValue(at::Tensor t)
bool isTensor() const
at::Tensor toTensor() &&
at::Tensor &toTensor() &
const at::Tensor &toTensor() const &
at::TensorImpl *unsafeToTensorImpl() const
IValue(at::Storage s)
bool isStorage() const
c10::Storage toStorage() &&
c10::Storage toStorage() const &
const IValue &toIValue() const
IValue &toIValue()
bool isCapsule() const
c10::intrusive_ptr<torch::CustomClassHolder> toCapsule() &&
c10::intrusive_ptr<torch::CustomClassHolder> toCapsule() const &
template<typename T, std::enable_if_t<std::is_base_of<torch::CustomClassHolder, T>::value, int> = 0>
IValue(intrusive_ptr<T> custom_class)
bool isCustomClass() const
template<typename T>
c10::intrusive_ptr<T> toCustomClass() &&
template<typename T>
c10::intrusive_ptr<T> toCustomClass() const &
IValue(c10::intrusive_ptr<ivalue::Tuple> v)
template<typename ...Args, std::enable_if_t<!guts::disjunction<std::is_lvalue_reference<Args>..., guts::negation<std::is_constructible<IValue, Args>>...>::value, std::nullptr_t> = nullptr>
IValue(const std::tuple<Args...> &t)
template<typename ...Args, std::enable_if_t<!guts::disjunction<std::is_lvalue_reference<Args>..., guts::negation<std::is_constructible<IValue, Args>>...>::value, std::nullptr_t> = nullptr>
IValue(std::tuple<Args...> &&t)
bool isTuple() const
c10::intrusive_ptr<ivalue::Tuple> toTuple() &&
c10::intrusive_ptr<ivalue::Tuple> toTuple() const &
IValue(double d)
bool isDouble() const
double toDouble() const
template<typename T>
IValue(c10::complex<T> c)
bool isComplexDouble() const
c10::complex<double> toComplexDouble() const
IValue(c10::intrusive_ptr<ivalue::Future> v)
bool isFuture() const
c10::intrusive_ptr<ivalue::Future> toFuture() &&
c10::intrusive_ptr<ivalue::Future> toFuture() const &
IValue(c10::intrusive_ptr<c10::RRefInterface> v)
bool isRRef() const
c10::intrusive_ptr<c10::RRefInterface> toRRef() &&
c10::intrusive_ptr<c10::RRefInterface> toRRef() const &
IValue(c10::intrusive_ptr<at::Quantizer> v)
bool isQuantizer() const
c10::intrusive_ptr<at::Quantizer> toQuantizer() &&
c10::intrusive_ptr<at::Quantizer> toQuantizer() const &
IValue(int64_t i)
IValue(int32_t i)
bool isInt() const
int64_t toInt() const
IValue(bool b)
bool isBool() const
bool toBool() const
bool isIntList() const
c10::List<int64_t> toIntList() &&
c10::List<int64_t> toIntList() const &
std::vector<int64_t> toIntVector() const
IValue(c10::intrusive_ptr<ivalue::ConstantString> v)
IValue(std::string v)
IValue(const char *v)
IValue(c10::string_view v)
bool isString() const
c10::intrusive_ptr<ivalue::ConstantString> toString() &&
c10::intrusive_ptr<ivalue::ConstantString> toString() const &
const std::string &toStringRef() const
c10::optional<std::reference_wrapper<const std::string>> toOptionalStringRef() const
c10::string_view toStringView() const
bool isDoubleList() const
c10::List<double> toDoubleList() &&
c10::List<double> toDoubleList() const &
std::vector<double> toDoubleVector() const
bool isComplexDoubleList() const
c10::List<c10::complex<double>> toComplexDoubleList() &&
c10::List<c10::complex<double>> toComplexDoubleList() const &
std::vector<c10::complex<double>> toComplexDoubleVector() const
bool isBoolList() const
c10::List<bool> toBoolList() &&
c10::List<bool> toBoolList() const &
bool isTensorList() const
c10::List<at::Tensor> toTensorList() &&
c10::List<at::Tensor> toTensorList() const &
std::vector<at::Tensor> toTensorVector() const
IValue(c10::List<IValue> v)
bool isList() const
c10::List<IValue> toList() &&
c10::List<IValue> toList() const &
c10::ArrayRef<IValue> toListRef() const
template<class T, enable_if_ivalue_constructible<T> = nullptr>
IValue(c10::List<T> &&v)
template<class T, enable_if_ivalue_constructible<T> = nullptr>
IValue(const c10::List<T> &v)
template<class T, enable_if_ivalue_constructible<T> = nullptr>
IValue(at::ArrayRef<T> v)
template<class T, enable_if_ivalue_constructible<T> = nullptr>
IValue(const std::vector<T> &v)
template<class T, size_t N>
IValue(std::array<T, N> v)
IValue(c10::Dict<IValue, IValue> v)
bool isGenericDict() const
c10::Dict<IValue, IValue> toGenericDict() &&
c10::Dict<IValue, IValue> toGenericDict() const &
template<class Key, class Value>
IValue(c10::Dict<Key, Value> v)
template<class Key, class Value>
IValue(std::unordered_map<Key, Value> v)
template<class T, enable_if_ivalue_constructible<T> = nullptr>
IValue(c10::optional<T> v)
IValue(c10::intrusive_ptr<ivalue::Object> v)
bool isObject() const
c10::intrusive_ptr<ivalue::Object> toObject() &&
c10::intrusive_ptr<ivalue::Object> toObject() const &
const ivalue::Object &toObjectRef() const
torch::jit::Module toModule() const
bool isModule() const
IValue(c10::intrusive_ptr<ivalue::PyObjectHolder> v)
bool isPyObject() const
c10::intrusive_ptr<ivalue::PyObjectHolder> toPyObjectHolder() &&
c10::intrusive_ptr<ivalue::PyObjectHolder> toPyObjectHolder() const &
PyObject *toPyObject() const
IValue(c10::intrusive_ptr<ivalue::EnumHolder> v)
bool isEnum() const
c10::intrusive_ptr<ivalue::EnumHolder> toEnumHolder() &&
c10::intrusive_ptr<ivalue::EnumHolder> toEnumHolder() const &
bool isNone() const
std::string toNone() const
IValue(const at::Scalar &s)
bool isScalar() const
at::Scalar toScalar() const
IValue(c10::Device d)
bool isDevice() const
c10::Device toDevice() const
IValue(c10::Stream stream)
c10::Stream toStream() &&
c10::Stream toStream() const &
bool isStream() const
IValue(ScalarType t)
at::ScalarType toScalarType() const
IValue(Layout l)
at::Layout toLayout() const
IValue(MemoryFormat m)
at::MemoryFormat toMemoryFormat() const
IValue(at::QScheme qscheme)
at::QScheme toQScheme() const
IValue(at::Dimname dimname)
at::Dimname toDimname() const
IValue(at::Generator g)
bool isGenerator() const
at::Generator toGenerator() &&
at::Generator toGenerator() const &
std::string tagKind() const
template<typename T>
T to() &&
template<typename T>
c10::detail::ivalue_to_const_ref_overload_return<T>::type to() const &
template<typename T>
optional<T> toOptional()
template<typename T>
optional<T> toOptional() const
std::ostream &repr(std::ostream &stream, std::function<bool(std::ostream&, const IValue &v)> customFormatter) const
bool isPtrType() const
TypePtr type() const
bool overlaps(const IValue &rhs) const
void getSubValues(HashAliasedIValues &subValues) const
void visit(const std::function<bool(const IValue&)> &visitor) const
IValue deepcopy() const
IValue deepcopy(HashAliasedIValueMap &memo) const

Public Static Functions

size_t hash(const IValue &iv)
IValue make_capsule(intrusive_ptr<torch::CustomClassHolder> blob)
IValue uninitialized()


friend bool operator==(const IValue &lhs, const IValue &rhs)

This implements the same semantics as bool(lhs == rhs) in Python.

which is the same as equals() except for Tensor types.

friend bool operator!=(const IValue &lhs, const IValue &rhs)
friend std::ostream &operator<<(std::ostream &out, const IValue &v)
struct CompAliasedIValues

Public Functions

bool operator()(const IValue &lhs, const IValue &rhs) const
struct HashAliasedIValue

Public Functions

size_t operator()(const IValue &val) const


Access comprehensive developer documentation for PyTorch

View Docs


Get in-depth tutorials for beginners and advanced developers

View Tutorials


Find development resources and get your questions answered

View Resources