Windows apps
Collapse the table of content
Expand the table of content
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

array_view Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

Represents an N-dimensional view over the data held in another container.

template <
    typename value_type,  
    int _Rank = 1  
>  
class array_view : public _Array_view_base<_Rank, sizeof(value_type)/sizeof(int)>;  
 
template <
    typename value_type,  
    int _Rank  
>  
class array_view<const value_type, _Rank> : public _Array_view_base<_Rank, sizeof(value_type)/sizeof(int)>;  

Parameters

value_type
The data type of the elements in the array_view object.

_Rank
The rank of the array_view object.

Public Constructors

NameDescription
array_view::array_view ConstructorInitializes a new instance of the array_view class. There is no default constructor for array<T,N>. All constructors are restricted to run on the CPU only and cannot be executed on a Direct3D target.
array_view::~array_view DestructorDestroys the array_view object.

Public Methods

NameDescription
array_view::copy_to MethodCopies the contents of the array_view object to the specified destination by calling copy(*this, dest).
array_view::data MethodReturns a pointer to the raw data of the array_view.
array_view::discard_data MethodDiscards the current data underlying this view.
array_view::get_extent MethodReturns the extent object of the array_view object.
array_view::get_ref MethodReturns a reference to the indexed element.
array_view::get_source_accelerator_view MethodReturns the accelerator_view where the data source of the array_view is located.
array_view::refresh MethodNotifies the array_view object that its bound memory has been modified outside the array_view interface. A call to this method renders all cached information stale.
array_view::reinterpret_as MethodReturns a one-dimensional array that contains all the elements in the array_view object.
array_view::section MethodReturns a subsection of the array_view object that's at the specified origin and, optionally, that has the specified extent.
array_view::synchronize MethodSynchronizes any modifications made to the array_view object back to its source data.
array_view::synchronize_async MethodAsynchronously synchronizes any modifications made to the array_view object back to its source data.
array_view::synchronize_to MethodSynchronizes any modifications made to the array_view object to the specified accelerator_view.
array_view::synchronize_to_async MethodAsynchronously synchronizes any modifications made to the array_view object to the specified accelerator_view.
array_view::view_as MethodProduces an array_view object of a different rank using this array_view object’s data.

Public Operators

NameDescription
array_view::operator() OperatorReturns the value of the element that is specified by the parameter or parameters.
array_view::operator[] OperatorReturns the element that is specified by the parameters.
array_view::operator= OperatorCopies the contents of the specified array_view object into this one.

Public Constants

NameDescription
array_view::rank ConstantStores the rank of the array_view object.

Data Members

NameDescription
array_view::extent Data MemberGets the extent object that defines the shape of the array_view object.
array_view::source_accelerator_view Data MemberGets the accelerator_view where the data source of the array_view is located
array_view::value_type Data MemberThe value type of the array_view and the bound array.

The array_view class represents a view into the data that is contained in an array object or a subsection of an array object.

You can access the array_view object where the source data is located (locally) or on a different accelerator or a coherence domain (remotely). When you access the object remotely, views are copied and cached as necessary. Except for the effects of automatic caching, array_view objects have a performance profile similar to that of array objects. There is a small performance penalty when you access the data through views.

There are three remote usage scenarios:

  • A view to a system memory pointer is passed by means of a parallel_for_each call to an accelerator and accessed on the accelerator.

  • A view to an array located on an accelerator is passed by means of a parallel_for_each call to another accelerator and is accessed there.

  • A view to an array located on an accelerator is accessed on the CPU.

In any one of these scenarios, the referenced views are copied by the runtime to the remote location and, if modified by the calls to the array_view object, are copied back to the local location. The runtime might optimize the process of copying changes back, might copy only changed elements, or might copy unchanged portions also. Overlapping array_view objects on one data source are not guaranteed to maintain referential integrity in a remote location.

You must synchronize any multithreaded access to the same data source.

The runtime makes the following guarantees regarding the caching of data in array_view objects:

  • All well-synchronized accesses to an array object and an array_view object on it in program order obey a serial happens-before relationship.

  • All well-synchronized accesses to overlapping array_view objects on the same accelerator on a single array object are aliased through the array object. They induce a total occurs-before relationship which obeys program order. There is no caching. If the array_view objects are executing on different accelerators, the order of access is undefined, creating a race condition.

When you create an array_view object using a pointer in system memory, you must change the view array_view object only through the array_view pointer. Alternatively, you must call refresh() on one of the array_view objects that are attached to the system pointer, if the underlying native memory is changed directly, instead of through the array_view object.

Either action notifies the array_view object that the underlying native memory is changed and that any copies that are located on an accelerator are outdated. If you follow these guidelines, the pointer-based views are identical to those provided to views of data-parallel arrays.

_Array_view_shape

_Array_view_base

array_view

Header: amp.h

Namespace: Concurrency

Destroys the array_view object.

~array_view()restrict(amp,cpu);

Initializes a new instance of the array_view class.

array_view(
    array<value_type, _Rank>& _Src)restrict(amp,cpu);

 
array_view(
    const array_view& _Other)restrict(amp,cpu);

 
explicit array_view(
    const Concurrency::extent<_Rank>& _Extent) restrict(cpu);

 
template <
    typename _Container  
>  
array_view(
    const Concurrency::extent<_Rank>& _Extent,  
    _Container& _Src) restrict(cpu);

 
array_view(
    const Concurrency::extent<_Rank>& _Extent,  
    value_type* _Src)restrict(amp,cpu);

 
explicit array_view(
    int _E0) restrict(cpu);

 
template <
    typename _Container  
>  
explicit array_view(
    _Container& _Src,  
    typename std::enable_if<details::_Is_container<_Container>::type::value, void **>::type = 0) restrict(cpu);

 
template <
    typename _Container  
>  
explicit array_view(
    int _E0,  
    _Container& _Src) restrict(cpu);

 
explicit array_view(
    int _E0,  
    int _E1) __CPU_ONLY;  
 
template <
    typename _Container  
>  
explicit array_view(
    int _E0,  
    int _E1,  
    _Container& _Src) restrict(cpu);

 
explicit array_view(
    int _E0,  
    int _E1,  
    int _E2) __CPU_ONLY;  
 
template <
    typename _Container  
>  
explicit array_view(
    int _E0,  
    int _E1,  
    int _E2,  
    _Container& _Src);

 
explicit array_view(
    int _E0,  
    _In_ value_type* _Src)restrict(amp,cpu);

 
template <
    typename _Arr_type,  
    int _Size  
>  
explicit array_view(
    _In_ _Arr_type (& _Src) [_Size]) restrict(amp,cpu);

 
explicit array_view(
    int _E0,  
    int _E1,  
    _In_ value_type* _Src)restrict(amp,cpu);

 
explicit array_view(
    int _E0,  
    int _E1,  
    int _E2,  
    _In_ value_type* _Src)restrict(amp,cpu);

 
array_view(
    const array<value_type, _Rank>& _Src)restrict(amp,cpu);

 
array_view(
    const array_view<value_type, _Rank>& _Src)restrict(amp,cpu);

 
array_view(
    const array_view<const value_type, _Rank>& _Src)restrict(amp,cpu);

 
template <
    typename _Container  
>  
array_view(
    const Concurrency::extent<_Rank>& _Extent,  
    const _Container& _Src) restrict(cpu);

 
template <
    typename _Container  
>  
explicit array_view(
    const _Container& _Src,  
    typename std::enable_if<details::_Is_container<_Container>::type::value, void **>::type = 0) restrict(cpu);

 
array_view(
    const Concurrency::extent<_Rank>& _Extent,  
    const value_type* _Src)restrict(amp,cpu);

 
template <
    typename _Arr_type,  
    int _Size  
>  
explicit array_view(
    const _In_ _Arr_type (& _Src) [_Size]) restrict(amp,cpu);

 
template <
    typename _Container  
>  
array_view(
    int _E0,  
    const _Container& _Src);

 
template <
    typename _Container  
>  
array_view(
    int _E0,  
    int _E1,  
    const _Container& _Src);

 
template <
    typename _Container  
>  
array_view(
    int _E0,  
    int _E1,  
    int _E2,  
    const _Container& _Src);

 
array_view(
    int _E0,  
    const value_type* _Src)restrict(amp,cpu);

 
array_view(
    int _E0,  
    int _E1,  
    const value_type* _Src) restrict(amp,cpu);

 
array_view(
    int _E0,  
    int _E1,  
    int _E2,  
    const value_type* _Src) restrict(amp,cpu);

 

Parameters

_Arr_type
The element type of a C-style array from which data is supplied.

_Container
A template argument that must specify a linear container that supports data() and size() members.

_E0
The most significant component of the extent of this section.

_E1
The next-to-most-significant component of the extent of this section.

_E2
The least significant component of the extent of this section.

_Extent
The extent in each dimension of this array_view.

_Other
An object of type array_view<T,N> from which to initialize the new array_view.

_Size
The size of a C-style array from which data is supplied.

_Src
A pointer to the source data that will be copied into the new array.

Copies the contents of the array_view object to the specified destination object by calling copy(*this, dest).

void copy_to(
    array<value_type, _Rank>& _Dest) const;

 
 
void copy_to(
    array_view<value_type, _Rank>& _Dest) const;

 

Parameters

_Dest
The object to copy to.

Returns a pointer to the raw data of the array_view.

value_type* data() const restrict(amp,
    cpu);

 
const value_type* data() const restrict(amp,
    cpu);

Return Value

A pointer to the raw data of the array_view.

Discards the current data underlying this view. This is an optimization hint to the runtime used to avoid copying the current contents of the view to a target accelerator_view that it is accessed on, and its use is recommended if the existing content is not needed. This method is a no-op when used in a restrict(amp) context

void discard_data() const restrict(cpu);

Gets the extent object that defines the shape of the array_view object.

__declspec(property(get= get_extent)) Concurrency::extent<_Rank> extent;  

Returns the extent object of the array_view object.

Concurrency::extent<_Rank> get_extent() const restrict(cpu, amp);

Return Value

The extent object of the array_view object

Get a reference to the element indexed by _Index. Unlike the other indexing operators for accessing the array_view on the CPU, this method does not implicitly synchronize this array_view's contents to the CPU. After accessing the array_view on a remote location or performing a copy operation involving this array_view users are responsible to explicitly synchronize the array_view to the CPU before calling this method. Failure to do so results in undefined behavior.

value_type& get_ref(
    const index<_Rank>& _Index) const restrict(amp, cpu);

Parameters

_Index
The index.

Return Value

Reference to the element indexed by _Index

Returns the accelerator_view where the data source of the array_view is located. If the array_view does not have a data source, this API throws a runtime_exception

accelerator_view get_source_accelerator_view() const;

 

Return Value

Returns the value of the element that is specified by the parameter or parameters.

value_type& operator() (
    const index<_Rank>& _Index) const restrict(amp,cpu);

 
typename details::_Projection_result_type<value_type,_Rank>::_Result_type operator() (
    int _I) const restrict(amp,cpu);

 
value_type& operator() (
    int _I0,  
    int _I1) const restrict(amp,cpu);

 
value_type& operator() (
    int _I0,  
    int _I1,  
    int _I2) const restrict(amp,cpu);

 
typename details::_Projection_result_type<value_type,_Rank>::_Const_result_type operator() (
    int _I) const restrict(amp,cpu);

Parameters

_Index
The location of the element.

_I0
The index in the first dimension.

_I1
The index in the second dimension.

_I2
The index in the third dimension.

_I
The location of the element.

Return Value

The value of the element that is specified by the parameter or parameters.

Returns the element that is specified by the parameters.

typename details::_Projection_result_type<value_type,_Rank>::_Const_result_type operator[] (
    int _I) const restrict(amp,cpu);

 
value_type& operator[] (
    const index<_Rank>& _Index) const restrict(amp,cpu);

Parameters

_Index
The index.

_I
The index.

Return Value

The value of the element at the index, or an array_view projected on the most-significant dimension.

Copies the contents of the specified array_view object to this one.

array_view& operator= (
    const array_view& _Other) restrict(amp,cpu);

 
array_view& operator= (
    const array_view<value_type, _Rank>& _Other) restrict(amp,cpu);

Parameters

_Other
The array_view object to copy from.

Return Value

A reference to this array_view object.

Stores the rank of the array_view object.

static const int rank = _Rank;  

Notifies the array_view object that its bound memory has been modified outside the array_view interface. A call to this method renders all cached information stale.

void refresh() const restrict(cpu);

Returns a subsection of the array_view object that's at the specified origin and, optionally, that has the specified extent.

array_view section(
    const Concurrency::index<_Rank>& _Section_origin,  
    const Concurrency::extent<_Rank>& _Section_extent) const restrict(amp,cpu);

 
array_view section(
    const Concurrency::index<_Rank>& _Idx) const restrict(amp,cpu);

 
array_view section(
    const Concurrency::extent<_Rank>& _Ext) const restrict(amp,cpu);

 
array_view section(
    int _I0,  
    int _E0) const restrict(amp,cpu);

 
array_view section(
    int _I0,  
    int _I1,  
    int _E0,  
    int _E1) const restrict(amp,cpu);

 
array_view section(
    int _I0,  
    int _I1,  
    int _I2,  
    int _E0,  
    int _E1,  
    int _E2) const restrict(amp,cpu);

Parameters

_E0
The most significant component of the extent of this section.

_E1
The next-to-most-significant component of the extent of this section.

_E2
The least significant component of the extent of this section.

_Ext
The extent object that specifies the extent of the section. The origin is 0.

_Idx
The index object that specifies the location of the origin. The subsection is the rest of the extent.

_I0
The most significant component of the origin of this section.

_I1
The next-to-most-significant component of the origin of this section.

_I2
The least significant component of the origin of this section.

_Rank
The rank of the section.

_Section_extent
The extent object that specifies the extent of the section.

_Section_origin
The index object that specifies the location of the origin.

Return Value

A subsection of the array_view object that's at the specified origin and, optionally, that has the specified extent. When only the index object is specified, the subsection contains all elements in the associated extent that have indexes that are larger than the indexes of the elements in the index object.

Gets the source accelerator_view that this array_view is associated with.

__declspec(property(get= get_source_accelerator_view)) accelerator_view source_accelerator_view;  

Synchronizes any modifications made to the array_view object back to its source data.

void synchronize(access_type _Access_type = access_type_read) const restrict(cpu);

 
void synchronize() const restrict(cpu);

Parameters

_Access_type
The intended access_type on the target accelerator_view. This parameter has a default value of access_type_read.

Asynchronously synchronizes any modifications made to the array_view object back to its source data.

concurrency::completion_future synchronize_async(access_type _Access_type = access_type_read) const restrict(cpu);

 
concurrency::completion_future synchronize_async() const restrict(cpu);

Parameters

_Access_type
The intended access_type on the target accelerator_view. This parameter has a default value of access_type_read.

Return Value

A future upon which to wait for the operation to complete.

Synchronizes any modifications made to this array_view to the specified accelerator_view.

void synchronize_to(
    const accelerator_view& _Accl_view,  
    access_type _Access_type = access_type_read) const restrict(cpu);

 
void synchronize_to(
    const accelerator_view& _Accl_view) const restrict(cpu);

Parameters

_Accl_view
The target accelerator_view to synchronize to.

_Access_type
The desired access_type on the target accelerator_view. This parameter has a default value of access_type_read.

Asynchronously synchronizes any modifications made to this array_view to the specified accelerator_view.

concurrency::completion_future synchronize_to_async(
    const accelerator_view& _Accl_view,  
    access_type _Access_type = access_type_read) const restrict(cpu);

 
concurrency::completion_future synchronize_to_async(
    const accelerator_view& _Accl_view) const restrict(cpu);

Parameters

_Accl_view
The target accelerator_view to synchronize to.

_Access_type
The desired access_type on the target accelerator_view. This parameter has a default value of access_type_read.

Return Value

A future upon which to wait for the operation to complete.

The value type of the array_view and the bound array.

typedef typenamevalue_type value_type;  

Reinterprets this array_view as an array_view of a different rank.

template <
    int _New_rank  
>  
array_view<value_type,_New_rank> view_as(
    const Concurrency::extent<_New_rank>& _View_extent) const restrict(amp,cpu);

 
template <
    int _New_rank  
>  
array_view<const value_type,_New_rank> view_as(
    const Concurrency::extent<_New_rank> _View_extent) const restrict(amp,cpu);

Parameters

_New_rank
The rank of the new array_view object.

_View_extent
The reshaping extent.

value_type
The data type of the elements in both the original array object and the returned array_view object.

Return Value

The array_view object that is constructed.

Concurrency Namespace (C++ AMP)

Show:
© 2016 Microsoft