Tensor
#include "max/c/tensor.h"
Functions
M_newTensorSpec()
M_TensorSpec *M_newTensorSpec(const int64_t *shape, int64_t rankSize, M_Dtype dtype, const char *tensorName)
Creates a tensor specification.
You need this in order to set the input tensors with M_borrowTensorInto()
.
When storing tensor data in memory, we always use a diminishing stride size. That is, earlier dimensions in the shape have larger strides than later dimensions. For example, a C array declared as int arr[1][2][3]
would have a shape specified as {1, 2, 3}
.
-
Parameters:
- shape – The shape of the tensor.
- rankSize – The rank size of the tensor.
- dtype – The datatype for the tensor.
- tensorName – The name for the tensor. This string gets copied as part of the operation of
M_newTensorSpec
, so your original string need not remain valid after the completion of this call.
-
Returns:
A pointer to the tensor spec. You are responsible for the memory associated with the pointer returned. The memory can be deallocated by calling
M_freeTensorSpec()
.
M_isDynamicRanked()
int M_isDynamicRanked(const M_TensorSpec *spec)
Returns if the given spec has a dynamic rank.
-
Parameters:
spec – The tensor spec.
-
Returns:
1
if the rank is dynamic.0
otherwise.
M_getDimAt()
int64_t M_getDimAt(const M_TensorSpec *spec, size_t axis)
Gets the element at a particular axis.
-
Parameters:
- spec – The tensor spec.
- axis – The requested axis
-
Returns:
The dimension at requested axis if the spec and axis are valid and has static rank. Otherwise,
0
. A dimension equalingM_getDynamicDimensionValue()
indicates dynamic dimension e.g. batch-size of a model expecting a batched tensor.
M_getRank()
int64_t M_getRank(const M_TensorSpec *spec)
Gets the rank from the tensor spec.
-
Parameters:
spec – The tensor spec.
-
Returns:
The number of dimensions in the tensor spec if the spec is static and valid,
M_getDynamicRankValue()
if dynamic. Otherwise,0
.
M_getDtype()
M_Dtype M_getDtype(const M_TensorSpec *spec)
Gets the datatype from the tensor spec.
-
Parameters:
spec – The tensor spec.
-
Returns:
The element type from the tensor spec if the tensor spec is valid. Otherwise,
M_UNKNOWN
.
M_getName()
const char *M_getName(M_TensorSpec *spec)
Gets the name of the tensor from the tensor spec.
-
Parameters:
spec – The tensor spec.
-
Returns:
A null-terminated string containing the name of the tensor if the
spec
is valid. Otherwise,NULL
. The memory associated with the returned string is owned byspec
.
M_newAsyncTensorMap()
M_AsyncTensorMap *M_newAsyncTensorMap(const M_RuntimeContext *context)
Creates a map of tensor names to async tensors.
-
Parameters:
- context – The runtime context.
- size – The size of the collection.
-
Returns:
A pointer to the tensor map. You are responsible for the memory associated with the pointer returned. The memory can be deallocated by calling
M_freeAsyncTensorMap()
.
M_copyAsyncTensorMap()
M_AsyncTensorMap *M_copyAsyncTensorMap(const M_AsyncTensorMap *tensorMap)
Copies a tensor map.
-
Parameters:
tensor – The tensor to copy.
-
Returns:
A pointer to the tensor map. You are responsible for the memory associated with the pointer returned. The memory can be deallocated by calling
M_freeAsyncTensorMap()
.
M_getTensorMapSize()
size_t M_getTensorMapSize(const M_AsyncTensorMap *tensorMap, M_Status *status)
Gets the size of the tensor map.
-
Parameters:
- tensorMap – The tensor map.
- status – The status object for reporting errors.
-
Returns:
The size of the tensor map if the tensor map is valid. Otherwise,
0
and thestatus
parameter contains an error message.
M_borrowTensorInto()
void M_borrowTensorInto(M_AsyncTensorMap *tensors, const void *input, const M_TensorSpec *tensorSpec, M_Status *status)
Adds a tensor to the tensor map.
You are responsible for the lifetime of the input tensor data. Its data gets “borrowed” into the Tensor Map.
-
Parameters:
- tensors – The tensor map, from
M_newAsyncTensorMap()
. - input – The input tensor data.
- tensorSpec – The tensor spec, from
M_newTensorSpec()
. This gets copied as part of the operation ofM_borrowTensorInto
, so your original tensorSpec need not exist through the lifetime of the tensor map. - status – The status object for reporting errors.
- tensors – The tensor map, from
M_createBorrowedTensor()
M_AsyncValue *M_createBorrowedTensor(const void *data, const M_TensorSpec *tensorSpec, M_RuntimeContext *context)
Creates a borrowed tensor wrapped in an AsyncValue
.
-
Parameters:
- data – The tensor data.
- tensorSpec – The tensor spec, from
M_newTensorSpec()
. This gets copied as part of the operation ofM_createBorrowedTensor
, so your original tensorSpec need not exist through the lifetime of the tensor. - context – The runtime context.
-
Returns:
A pointer to the value. You are responsible for the memory associated with the pointer returned. The memory can be deallocated by calling
M_freeValue()
. The held value inside the return value is owned by theAsyncValue
, however the tensor data is borrowed and must outlive the returnedM_AsyncValue
.
M_getTensorByNameFrom()
M_AsyncTensor *M_getTensorByNameFrom(M_AsyncTensorMap *tensorMap, const char *name, M_Status *status)
Gets a tensor from the tensor map by name.
-
Parameters:
- tensorMap – The tensor map.
- tensorName – The name of the tensor.
- status – The status object for reporting errors.
-
Returns:
A pointer to the tensor. You are responsible for the memory associated with the pointer returned. The memory can be deallocated by calling
M_freeTensor()
. The held tensor inside the return value is simply borrowed from the corresponding inputM_AsyncTensorMap
. If the tensor map or name are invalid, aNULL
pointer is returned and thestatus
parameter contains an error message.
M_tensorMapKeys()
const char **M_tensorMapKeys(M_AsyncTensorMap *tensorMap, int64_t *size)
M_deleteTensorMapKeys()
void M_deleteTensorMapKeys(const char **keys)
M_getTensorFromValue()
M_AsyncTensor *M_getTensorFromValue(M_AsyncValue *value)
Gets a tensor from the async value.
-
Parameters:
value – The async value.
-
Returns:
A pointer to the tensor. You are responsible for the memory associated with the pointer returned. The memory can be deallocated by calling
M_freeTensor()
. The held tensor inside the return value is simply borrowed from theM_AsyncValue
. Note that the tensor name is not available through this method (unlikeM_getTensorByNameFrom
). If the value is invalid or not a tensor, aNULL
pointer is returned.
M_getTensorNumElements()
size_t M_getTensorNumElements(const M_AsyncTensor *tensor)
Gets the number of elements for the tensor.
-
Parameters:
tensor – The tensor which must not be
NULL
. -
Returns:
The number of elements for the given tensor.
M_getTensorType()
M_Dtype M_getTensorType(const M_AsyncTensor *tensor)
Gets the corresponding M_Dtype
for the tensor.
-
Parameters:
tensor – The tensor which must not be
NULL
. -
Returns:
The corresponding
M_Dtype
for the tensor.
M_getTensorData()
const void *M_getTensorData(const M_AsyncTensor *tensor)
Gets a pointer to underlying data of the tensor.
-
Parameters:
tensor – The tensor which must not be
NULL
. -
Returns:
A pointer to the underlying data of the tensor. This pointer is valid for the lifetime of the underlying tensor.
M_getTensorSpec()
M_TensorSpec *M_getTensorSpec(const M_AsyncTensor *tensor)
Gets a Tensor Spec for the tensor.
-
Parameters:
tensor – The tensor.
-
Returns:
The tensor spec for the tensor if the tensor is valid. Otherwise,
NULL
.
M_getTensorMapIterator()
M_TensorMapIterator *M_getTensorMapIterator(M_AsyncTensorMap *tensorMap, M_Status *status)
Gets a tensor map iterator for the tensor map.
-
Parameters:
- tensorMap – The tensor map.
- status – The status object for reporting errors.
-
Returns:
A pointer to the tensor map iterator. You are responsible for the memory associated with the pointer returned. The memory can be deallocated by calling
M_freeTensorMapIterator()
. If the tensor map is invalid, aNULL
pointer is returned and thestatus
parameter contains an error message.
M_advanceTensorMapIterator()
void M_advanceTensorMapIterator(M_TensorMapIterator *iterator)
Advances the tensor map iterator by one entry.
-
Parameters:
iterator – The tensor map iterator.
M_getNameFromMapIterator()
const char *M_getNameFromMapIterator(M_TensorMapIterator *iterator)
Gets the name of the tensor from the tensor map iterator.
-
Parameters:
iterator – The tensor map iterator.
-
Returns:
A null-terminated string containing the name of the tensor if the
iterator
is valid. Otherwise,NULL
. The memory associated with the returned string is owned byspec
.
M_getTensorFromMapIterator()
M_AsyncTensor *M_getTensorFromMapIterator(M_TensorMapIterator *iterator)
Gets the tensor from the tensor map iterator.
-
Parameters:
iterator – The tensor map iterator.
-
Returns:
A pointer to the tensor. You are responsible for the memory associated with the pointer returned. The memory can be deallocated by calling
M_freeTensor()
. The held tensor inside the return value is simply borrowed from the corresponding inputM_AsyncTensorMap
. If the tensor map iterator is invalid, aNULL
pointer is returned.
M_isEndOfTensorMap()
bool M_isEndOfTensorMap(M_AsyncTensorMap *tensorMap, M_TensorMapIterator *iterator)
Checks if the iterator has reached the end of the tensor map.
-
Parameters:
- tensorMap – The tensor map.
- iterator – The tensor map iterator.
-
Returns:
True if the iterator points to the end of the map, false otherwise. Also returns true if either the tensorMap or iterator are invalid.
M_freeTensor()
void M_freeTensor(M_AsyncTensor *tensor)
Deallocates the memory for the tensor. No-op if tensor
is NULL.
-
Parameters:
tensor – The tensor to deallocate.
M_freeTensorNameArray()
void M_freeTensorNameArray(M_TensorNameArray *names)
Deallocates the memory for the array of tensor names. No-op if names
is NULL.
-
Parameters:
names – The tensor names to deallocate.
M_freeTensorSpec()
void M_freeTensorSpec(M_TensorSpec *spec)
Deallocates the memory for the tensor spec. No-op if spec
is NULL.
-
Parameters:
spec – The tensor spec to deallocate.
M_freeAsyncTensorMap()
void M_freeAsyncTensorMap(M_AsyncTensorMap *tensorMap)
Deallocates the memory for the tensor map. No-op if tensorMap
is NULL.
-
Parameters:
tensorMap – The tensor map to deallocate.
M_freeTensorMapIterator()
void M_freeTensorMapIterator(M_TensorMapIterator *iterator)
Deallocates the memory for the tensor map iterator. No-op if iterator
is NULL.
-
Parameters:
iterator – The tensor map iterator to deallocate.
Was this page helpful?
Thank you! We'll create more content like this.
Thank you for helping us improve!
If you'd like to share more information, please report an issue on GitHub
😔 What went wrong?