Class Tensor

Represents data in a multidimensional array-like structure.

Inheritance
object
Tensor
Tensor<T>
Implements
Inherited Members
Namespace: Unity.InferenceEngine
Assembly: Unity.InferenceEngine.dll
Syntax
public abstract class Tensor : IDisposable
Remarks

Tensors are the fundamental data structure used to represent multidimensional arrays of data, such as images and audio. Use them as inputs for models, and to download a copy of the backend output values (backendType).

Ownership and Lifetime
Tensors manage native memory resources. You must call Dispose() of a tensor when it is no longer needed. The ownership of the tensor's internal data (dataOnBackend) belongs to the Tensor object itself. Disposing the tensor also disposes its underlying data.

Data Representation
A Tensor's structure is defined by its shape (a TensorShape object) and its dataType. The actual data is held by an ITensorData implementation, which dictates the physical storage location BackendType. Data within the tensor is stored in a flattened, row-major format.

Asynchronous Operations and Data Access
Tensor data can be pending a device is performing computations, or if the data is stored on a non-readable device-specific type (for example GPU memory). To get a CPU readable copy of the data, use ReadbackAndClone(), or ReadbackAndCloneAsync() for an asynchronous operation. You can check the status of an asynchronous readback request with IsReadbackRequestDone().

Examples

The following example demonstrates how to interact with a Tensor object, ensuring its data is available on the CPU for reading, and then properly disposing of resources.

For a full workflow example, refer to Workflow example.

// Create a tensor
m_Tensor = new Tensor<float>(new TensorShape(2, 3), new[] { 1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f });
// Alternatively with `using` so you don't need to call `Dispose()` when you are done with the tensor
using var m_OtherTensor = new Tensor<float>(new TensorShape(2, 3), new[] { 1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f });

// Get a CPU-accessible clone of the tensor. This copy owns its own data.
Tensor<float> cpuCopyTensor = m_Tensor.ReadbackAndClone() as Tensor<float>;


// Release memory.
cpuCopyTensor.Dispose();
m_Tensor.Dispose();

Properties

backendType

The backend type where the tensor data is currently stored (for example, CPU, GPU).

Declaration
public BackendType backendType { get; }
Property Value
Type Description
BackendType
See Also

count

The total number of elements in the tensor, calculated as the product of its dimensions.

Declaration
public int count { get; }
Property Value
Type Description
int
See Also

dataOnBackend

The device-specific internal representation of the tensor data.

Declaration
public ITensorData dataOnBackend { get; }
Property Value
Type Description
ITensorData
Remarks

Accessing this property allows for direct manipulation of the underlying data, but typically requires knowledge of concrete ITensorData implementations.

See Also

dataType

The data type of the elements of the tensor.

Declaration
public DataType dataType { get; }
Property Value
Type Description
DataType
See Also

shape

The shape of the tensor, as a TensorShape object, defining its dimensions.

Declaration
public TensorShape shape { get; }
Property Value
Type Description
TensorShape
See Also

Methods

AdoptTensorData(ITensorData, bool)

Associates a new tensor data object with this tensor.

Declaration
public void AdoptTensorData(ITensorData tensorData, bool disposePrevious = true)
Parameters
Type Name Description
ITensorData tensorData

The new ITensorData instance to associate with the tensor. This data must have sufficient capacity for the tensor's current count.
bool disposePrevious

If true, the previously associated tensor data will be disposed. Set to false if you intend to manage the lifetime of the previous data manually.
Exceptions
Type Condition
AssertionException

Thrown if the provided tensorData has insufficient capacity for the tensor's current element count.
See Also

CompleteAllPendingOperations()

Completes all scheduled tensor operations on the device backend. This is a blocking call that ensures all pending computations or data transfers related to this tensor have completed.

Declaration
public void CompleteAllPendingOperations()
See Also

Dispose()

Disposes of the tensor and releases any associated unmanaged memory resources. This method must be called on the main thread to prevent memory leaks. After calling Dispose, the tensor instance should no longer be used.

Declaration
public void Dispose()
See Also

IsReadbackRequestDone()

Checks if an asynchronous readback request for the tensor's data has completed.

Declaration
public bool IsReadbackRequestDone()
Returns
Type Description
bool

true if the asynchronous readback request is done and successful. Otherwise false.
See Also

ReadbackAndClone()

Performs a blocking download of the internal tensor data from its backend to a new CPU-accessible Tensor instance. This method ensures all pending operations on the original tensor's data are completed before the download begins.

Declaration
public Tensor ReadbackAndClone()
Returns
Type Description
Tensor

A new Tensor instance containing a CPU-accessible copy of the original tensor's data. This new tensor is independent and must also be disposed of.
See Also

ReadbackAndCloneAsync()

Schedules an asynchronous download of the internal tensor data from its backend to a new CPU-accessible Tensor instance. This method returns an Awaitable_1 that can be used to await the completion of the download operation without blocking the main thread.

Declaration
public Awaitable<Tensor> ReadbackAndCloneAsync()
Returns
Type Description
Awaitable<Tensor>

An Awaitable_1 that resolves to a new Tensor instance containing a CPU-accessible copy of the original tensor's data. This new tensor is independent and must also be disposed of.
See Also

ReadbackRequest()

Schedules an asynchronous download of the internal tensor data from its backend to a CPU-accessible location. You can check the completion of this request using IsReadbackRequestDone().

Declaration
public void ReadbackRequest()
See Also

ReleaseTensorData()

Detaches the current ITensorData object from the tensor and returns it. The tensor will no longer manage the lifetime of this data.

Declaration
public ITensorData ReleaseTensorData()
Returns
Type Description
ITensorData

The ITensorData object that was previously associated with this tensor. Returns null if no data was associated.
See Also

Reshape(TensorShape)

Changes the logical shape of the tensor without changing the backing data's physical allocation.

Declaration
public abstract void Reshape(TensorShape shape)
Parameters
Type Name Description
TensorShape shape

The new shape for the tensor. The total number of elements in the new shape must fit within the currently allocated backend tensor data's capacity.
Exceptions
Type Condition
AssertionException

Thrown if the new shape's total elements exceed the allocated capacity.
See Also

ToString()

Returns a string that represents the Tensor's data type and shape.

Declaration
public override string ToString()
Returns
Type Description
string

A string representation of the tensor.
Overrides
See Also

Implements

See Also