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)

string	DebugString () const
	A utility function to print the debug string for the tensor. More...

void	ShareData (const Tensor &src)
	Shares the data with another tensor. More...

template<typename T >
void	ShareExternalPointer (T *src, size_t capacity=0)
	Shares the data with an externally managed pointer. More...

template<typename T , typename Deleter >
void	ShareExternalPointer (T *src, size_t capacity, Deleter &&d)
	Shares the data with an externally managed pointer. More...

void	ShareExternalPointer (void *src, const TypeMeta &meta, size_t capacity=0)

template<class Deleter >
void	ShareExternalPointer (void *src, const TypeMeta &meta, size_t capacity, Deleter &&d)

bool	shares_data ()

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

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 TypeMeta &	meta () 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

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 73 of file tensor.h.

Constructor & Destructor Documentation

◆ Tensor() [1/3]

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 86 of file tensor.h.

◆ Tensor() [2/3]

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 100 of file tensor.h.

◆ Tensor() [3/3]

template<class Context>

template<class SrcContext >

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

inline

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.

Definition at line 112 of file tensor.h.

Member Function Documentation

◆ canonical_axis_index()

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_index the 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 573 of file tensor.h.

◆ CopyFrom()

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 166 of file tensor.h.

◆ data()

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 433 of file tensor.h.

◆ DebugString()

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 317 of file tensor.h.

◆ dim()

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 606 of file tensor.h.

◆ dim32()

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 594 of file tensor.h.

◆ Extend()

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 183 of file tensor.h.

◆ mutable_data()

template<class Context>

template<typename T >

T* caffe2::Tensor< Context >::mutable_data ( )

inline

Returns a typed pointer of the underlying storage.

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

Definition at line 519 of file tensor.h.

◆ nbytes()

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 544 of file tensor.h.

◆ raw_data()

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 421 of file tensor.h.

◆ raw_mutable_data() [1/2]

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 459 of file tensor.h.

◆ raw_mutable_data() [2/2]

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 504 of file tensor.h.

◆ Reshape()

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 290 of file tensor.h.

◆ Resize()

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 263 of file tensor.h.

◆ ResizeLike()

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 279 of file tensor.h.

◆ ShareData()

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 340 of file tensor.h.

◆ ShareExternalPointer() [1/2]

template<class Context>

template<typename T >

void caffe2::Tensor< Context >::ShareExternalPointer	(	T *	src,
		size_t	capacity = `0`
	)

inline

Shares the data with an externally managed pointer.

This is similar to ShareData() but the tensor does not take over ownership of the pointer, so the caller can explicitly manage the memory storage. One needs to make sure that the external memory is deallocated only after the tensor finishes using it.

Definition at line 367 of file tensor.h.

◆ ShareExternalPointer() [2/2]

template<class Context>

template<typename T , typename Deleter >

void caffe2::Tensor< Context >::ShareExternalPointer	(	T *	src,
		size_t	capacity,
		Deleter &&	d
	)

inline

Shares the data with an externally managed pointer.

This overload takes a Deleter functor to be called when this tensor is reallocated or freed.

Definition at line 378 of file tensor.h.

◆ Shrink()

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 236 of file tensor.h.

◆ size()

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 534 of file tensor.h.

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

caffe2/core/tensor.h

Public Member Functions

Protected Attributes

Detailed Description

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

Constructor & Destructor Documentation

◆ Tensor() [1/3]

◆ Tensor() [2/3]

◆ Tensor() [3/3]

Member Function Documentation

◆ canonical_axis_index()

◆ CopyFrom()

◆ data()

◆ DebugString()

◆ dim()

◆ dim32()

◆ Extend()

◆ mutable_data()

◆ nbytes()

◆ raw_data()

◆ raw_mutable_data() [1/2]

◆ raw_mutable_data() [2/2]

◆ Reshape()

◆ Resize()

◆ ResizeLike()

◆ ShareData()

◆ ShareExternalPointer() [1/2]

◆ ShareExternalPointer() [2/2]

◆ Shrink()

◆ size()

Facebook Open Source

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