Caffe2 - C++ API
A deep learning, cross platform ML framework
Public Member Functions | Protected Attributes
caffe2::Tensor< Context > Class Template Reference

Tensor is the basic class in Caffe2 that stores a contiguous memory with its shape information. More...

#include <tensor.h>

Public Member Functions

 Tensor ()
 Initializes an empty tensor.
 
 Tensor (const vector< TIndex > &dims)
 Creates a tensor of the given dimension. More...
 
 Tensor (const vector< int > &dims)
 
template<class SrcContext , class ContextForCopy >
 Tensor (const Tensor< SrcContext > &src, ContextForCopy *context)
 Creates a tensor from a source tensor, copying over the content. More...
 
template<class SrcContext >
 Tensor (const Tensor< SrcContext > &src)
 Creates a tensor from a source tensor, copying over the content. More...
 
template<typename T >
 Tensor (const vector< TIndex > &dims, const vector< T > &values, Context *context)
 Creates a tensor, and fills its contents with the given values.
 
template<typename T , typename = typename std::enable_if<std::is_scalar<T>::value>::type>
 Tensor (const T &value, Context *context)
 Creates a scalar tensor, and fills its content with the given value.
 
template<class SrcContext , class ContextForCopy >
void CopyFrom (const Tensor< SrcContext > &src, ContextForCopy *context)
 Copies the data from a source tensor, with a contex provided to carry out the underlying memcpy operation.
 
template<class SrcContext >
void CopyFrom (const Tensor< SrcContext > &src)
 Copies the data from a source tensor. More...
 
template<class ContextForCopy >
void Extend (TIndex num, float growthPct, ContextForCopy *context)
 Extends the outer-most dimension of this tensor by num elements, preserving the existing data. More...
 
template<class T , class ContextForCopy >
void Reserve (const std::vector< T > &newCapacity, ContextForCopy *context)
 
void Shrink (TIndex outer_dim)
 Shrinks the outer-most dimension to given size, keeping the data. More...
 
template<typename... Ts>
void Resize (Ts...dim_source)
 Resizes a tensor. More...
 
template<class OtherContext >
void ResizeLike (const Tensor< OtherContext > &src_tensor)
 Resize the tensor like the source tensor. More...
 
void Reshape (const vector< TIndex > &dims)
 Resizes the tensor without touching underlying storage. More...
 
void Reshape (const vector< int > &dims)
 
void FreeMemory ()
 Release whatever memory the tensor was holding but keep size and type information. More...
 
string DebugString () const
 A utility function to print the debug string for the tensor. More...
 
void swap (Tensor< Context > &other)
 
void ShareData (const Tensor &src)
 Shares the data with another tensor. More...
 
template<typename T , typename Deleter = MemoryDeleter>
void ShareExternalPointer (T *src, size_t capacity=0, Deleter d=nullptr)
 Shares the data with an externally managed pointer. More...
 
template<typename Deleter = MemoryDeleter>
void ShareExternalPointer (void *src, const TypeMeta &meta, size_t capacity=0, Deleter d=nullptr)
 
bool shares_data () const
 
const void * raw_data () const
 Returns a const raw void* pointer of the underlying storage. More...
 
template<typename T >
const T * data () const
 Returns a typed pointer of the underlying storage. More...
 
void * raw_mutable_data (const TypeMeta &meta)
 Returns a mutable raw pointer of the underlying storage. More...
 
void * raw_mutable_data ()
 Returns a mutable raw pointer of the underlying storage. More...
 
template<typename T >
T * mutable_data ()
 Returns a typed pointer of the underlying storage. More...
 
int ndim () const
 Returns the number of dimensions of the data.
 
TIndex size () const
 Returns the size (i.e. More...
 
size_t itemsize () const
 Return the number of bytes each item takes in the tensor.
 
size_t nbytes () const
 Returns the total number of bytes of the storage. More...
 
size_t capacity_nbytes () const
 
const vector< TIndex > & dims () const
 Returns the dimensions of the tensor as a vector.
 
TIndex size_from_dim (int k) const
 
TIndex size_to_dim (int k) const
 
TIndex size_between_dim (int k, int l) const
 
int canonical_axis_index (int axis_index) const
 Returns the 'canonical' version of a (usually) user-specified axis, allowing for negative indexing (e.g., -1 for the last axis). More...
 
template<typename T >
bool IsType () const
 Checks if the tensor content is of the given data type.
 
const TypeMetameta () const
 Returns the TypeMeta object associated with the current data type.
 
int dim32 (const int i) const
 Returns the i-th dimension of the tensor in int. More...
 
TIndex dim (const int i) const
 Returns the i-th dimension of the tensor. More...
 

Protected Attributes

vector< TIndex > dims_
 
TIndex size_ = -1
 
TypeMeta meta_
 
std::shared_ptr< void > data_
 
bool shares_data_ = false
 
size_t capacity_ = 0
 
bool reserved_ = false
 

Detailed Description

template<class Context>
class caffe2::Tensor< Context >

Tensor is the basic class in Caffe2 that stores a contiguous memory with its shape information.

The Tensor class is essentially a wrapper around a device-specific memory (the device is specified by the Context template argument), and deals with the allocation and de-allocation of such memory. We make a simplified assumption that the memory is always contiguous.

Definition at line 109 of file tensor.h.

Constructor & Destructor Documentation

template<class Context>
caffe2::Tensor< Context >::Tensor ( const vector< TIndex > &  dims)
inlineexplicit

Creates a tensor of the given dimension.

Note that the actual data allocation is not going to be carried out until the first time mutable_data() is called.

Definition at line 122 of file tensor.h.

template<class Context>
template<class SrcContext , class ContextForCopy >
caffe2::Tensor< Context >::Tensor ( const Tensor< SrcContext > &  src,
ContextForCopy *  context 
)
inline

Creates a tensor from a source tensor, copying over the content.

Note that the source tensor can be from a different device context. The second argument provides a device context object (either Context or SrcContext) that will be responsible for copying the underlying data. If you do not wish to pass in a Context object, an equivalent constructor function exists that will create an implicit context object for copy, but be noted that this will cause a potential performance hit.

Definition at line 136 of file tensor.h.

template<class Context>
template<class SrcContext >
caffe2::Tensor< Context >::Tensor ( const Tensor< SrcContext > &  src)
inlineexplicit

Creates a tensor from a source tensor, copying over the content.

Note that this may have a potential performance hit, since a temporary context object will be created for the memory copy. Prefer explicitly providing a context for copy if you can.

Since it's a potentially expensive operation - making copy constructor explicit here. If SrcContext != Context it's actually a typecast constructor and it should be definitely explicit.

Definition at line 152 of file tensor.h.

Member Function Documentation

template<class Context>
int caffe2::Tensor< Context >::canonical_axis_index ( int  axis_index) const
inline

Returns the 'canonical' version of a (usually) user-specified axis, allowing for negative indexing (e.g., -1 for the last axis).

Parameters
axis_indexthe axis index. If 0 <= index < ndim(), return index. If -ndim <= index <= -1, return (ndim() - (-index)), e.g., the last axis index (ndim() - 1) if index == -1, the second to last if index == -2, etc. Dies on out of range index.

Definition at line 652 of file tensor.h.

template<class Context>
template<class SrcContext >
void caffe2::Tensor< Context >::CopyFrom ( const Tensor< SrcContext > &  src)
inline

Copies the data from a source tensor.

Note that this may have a potential performance hit, since a temporary context object will be created for the memory copy. Prefer explicitly providing a context for copy if you can.

Definition at line 206 of file tensor.h.

template<class Context>
template<typename T >
const T* caffe2::Tensor< Context >::data ( ) const
inline

Returns a typed pointer of the underlying storage.

mutable_data() or raw_mutable_data() must have been called prior to this function call, and the data type must be of the correct type. If you want to get a void* pointer instead, use raw_data().

Definition at line 500 of file tensor.h.

template<class Context>
string caffe2::Tensor< Context >::DebugString ( ) const
inline

A utility function to print the debug string for the tensor.

Note that this is very slow since it involves quite some string operations, so do not use it in your performance-critical code.

Definition at line 383 of file tensor.h.

template<class Context>
TIndex caffe2::Tensor< Context >::dim ( const int  i) const
inline

Returns the i-th dimension of the tensor.

Note that the passed in index must be between 0 (inclusive) and the number of dimensions, otherwise this function will produce a fatal message.

Definition at line 687 of file tensor.h.

template<class Context>
int caffe2::Tensor< Context >::dim32 ( const int  i) const
inline

Returns the i-th dimension of the tensor in int.

This function returns an int value instead of TIndex, which depending on the typedef could be int64. If you want int64 dim values, make sure you call dim() instead.

Definition at line 673 of file tensor.h.

template<class Context>
template<class ContextForCopy >
void caffe2::Tensor< Context >::Extend ( TIndex  num,
float  growthPct,
ContextForCopy *  context 
)
inline

Extends the outer-most dimension of this tensor by num elements, preserving the existing data.

The underlying data may be reallocated in order to accommodate the new elements, in which case this tensors' capacity is grown at a factor of growthPct. This ensures that Extend runs on an amortized O(1) time complexity.

Definition at line 223 of file tensor.h.

template<class Context>
void caffe2::Tensor< Context >::FreeMemory ( )
inline

Release whatever memory the tensor was holding but keep size and type information.

Subsequent call to mutable_data will trigger new memory allocation.

Definition at line 369 of file tensor.h.

template<class Context>
template<typename T >
T* caffe2::Tensor< Context >::mutable_data ( )
inline

Returns a typed pointer of the underlying storage.

For fundamental types, we reuse possible existing storage if there is sufficient capacity.

Definition at line 594 of file tensor.h.

template<class Context>
size_t caffe2::Tensor< Context >::nbytes ( ) const
inline

Returns the total number of bytes of the storage.

This is equivalent to calling size() * itemsize().

Definition at line 619 of file tensor.h.

template<class Context>
const void* caffe2::Tensor< Context >::raw_data ( ) const
inline

Returns a const raw void* pointer of the underlying storage.

mutable_data() or raw_mutable_data() must have been called prior to this function call.

Definition at line 488 of file tensor.h.

template<class Context>
void* caffe2::Tensor< Context >::raw_mutable_data ( const TypeMeta meta)
inline

Returns a mutable raw pointer of the underlying storage.

Since we will need to know the type of the data for allocation, a TypeMeta object is passed in to specify the necessary information. This is conceptually equivalent of calling mutable_data<T>() where the TypeMeta parameter meta is derived from the type T. This function differs from mutable_data<T>() in the sense that the type T can be specified during runtime via the TypeMeta object.

If the existing data does not match the desired type, it will be deleted and a new storage will be created.

Definition at line 526 of file tensor.h.

template<class Context>
void* caffe2::Tensor< Context >::raw_mutable_data ( )
inline

Returns a mutable raw pointer of the underlying storage.

This can only be used when you know for sure that the underlying storage of the tensor is already created via an earlier raw_mutable_data(meta) call or a mutable_data<T>() call.

If the existing data does not match the desired type, it will be deleted and a new storage will be created.

Definition at line 579 of file tensor.h.

template<class Context>
void caffe2::Tensor< Context >::Reshape ( const vector< TIndex > &  dims)
inline

Resizes the tensor without touching underlying storage.

This requires the total size of the tensor to remains constant.

Definition at line 342 of file tensor.h.

template<class Context>
template<typename... Ts>
void caffe2::Tensor< Context >::Resize ( Ts...  dim_source)
inline

Resizes a tensor.

Resize takes in a vector of ints specifying the dimensions of the tensor. You can pass in an empty vector to specify that it is a scalar (i.e. containing one single item).

The underlying storage may be deleted after calling Resize: if the new shape leads to a different number of items in the tensor, the old memory is deleted and new memory will be allocated next time you call mutable_data(). However, if the shape is different but the total number of items is the same, the underlying storage is kept.

Definition at line 304 of file tensor.h.

template<class Context>
template<class OtherContext >
void caffe2::Tensor< Context >::ResizeLike ( const Tensor< OtherContext > &  src_tensor)
inline

Resize the tensor like the source tensor.

Note that this is just a sugar wrapper that essentially calls Resize(src_tensor.dims()).

Definition at line 331 of file tensor.h.

template<class Context>
void caffe2::Tensor< Context >::ShareData ( const Tensor< Context > &  src)
inline

Shares the data with another tensor.

To share data between two tensors, the sizes of the two tensors must be equal already. The reason we do not implicitly do a Resize to make the two tensors have the same shape is that we want to allow tensors of different shapes but the same number of items to still be able to share data. This allows one to e.g. have a n-dimensional Tensor and a flattened version sharing the same underlying storage.

The source tensor should already have its data allocated.

Definition at line 416 of file tensor.h.

template<class Context>
template<typename T , typename Deleter = MemoryDeleter>
void caffe2::Tensor< Context >::ShareExternalPointer ( T *  src,
size_t  capacity = 0,
Deleter  d = nullptr 
)
inline

Shares the data with an externally managed pointer.

This is similar to ShareData() but the source is a pointer with an advanced deleter option. In default, no deletion takes place, and one needs to make sure that the external memory is deallocated only after the tensor finishes using it. If a Deleter object is passed in, when this tensor is reallocated or freed, the deleter function is going to be called.

Definition at line 444 of file tensor.h.

template<class Context>
void caffe2::Tensor< Context >::Shrink ( TIndex  outer_dim)
inline

Shrinks the outer-most dimension to given size, keeping the data.

This method guarantees that no re-allocations are carried out, which means that the extra capacity after the end of the shurnk tensor is maintained.

Definition at line 277 of file tensor.h.

template<class Context>
TIndex caffe2::Tensor< Context >::size ( ) const
inline

Returns the size (i.e.

the number of items) of the tensor.

Definition at line 609 of file tensor.h.


The documentation for this class was generated from the following file: