array_view 类

项目
10/16/2023

表示另一个容器中保存的数据的 N 维视图。

语法

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)>;

参数

value_type
array_view 对象中元素的数据类型。

_Rank
array_view 对象的排名。

成员

公共构造函数

名称	描述
array_view 构造函数	初始化 `array_view` 类的新实例。没有 `array<T,N>` 的默认构造函数。所有构造函数仅限于在 CPU 上运行，不能在 Direct3D 目标上执行。
~array_view 析构函数	销毁 `array_view` 对象。

公共方法

名称	描述
copy_to	通过调用 `copy(*this, dest)` 将 `array_view` 对象的内容复制到指定的目标。
data	返回一个指向 `array_view` 的原始数据的指针。
discard_data	放弃此视图的当前基础数据。
get_extent	返回 array_view 对象的盘区对象。
get_ref	返回对索引元素的引用。
get_source_accelerator_view	返回 `array_view` 的数据源所在的 accelerator_view。
刷新	通知 `array_view` 对象其绑定的内存已在 `array_view` 接口之外进行了修改。调用此方法会使所有缓存的信息过时。
reinterpret_as	返回一个包含 `array_view` 对象中的所有元素的一维数组。
section	返回位于指定原点以及（可选）具有指定范围的 `array_view` 对象的一个子部分。
synchronize	将对 `array_view` 对象所做的任何修改同步回其源数据。
synchronize_async	将对 `array_view` 对象所做的任何修改以异步方式同步回其源数据。
synchronize_to	将对 `array_view` 对象所做的任何修改同步到指定的 accelerator_view。
synchronize_to_async	将对 `array_view` 对象所做的任何修改以异步方式同步到指定的 accelerator_view。
view_as	使用此 `array_view` 对象的数据生成不同排名的 `array_view` 对象。

公共运算符

“属性”	描述
operator()	返回由一个或多个参数指定的元素的值。
operator[]	返回由参数指定的元素。
operator=	将指定 `array_view` 对象的内容复制到此对象中。

公共常量

“属性”	描述
rank 常量	存储 `array_view` 对象的秩。

数据成员

名称	描述
extent	获取定义 `extent` 对象形状的 `array_view` 对象。
source_accelerator_view	获取 `array_view` 的数据源所在的 accelerator_view
value_type	`array_view` 的值类型和绑定数组。

注解

array_view 类表示对包含在 array 对象或 array 对象的子部分中的数据的视图。

可以访问源数据所在的array_view 对象（本地），或者不同的加速器或一致性域上的该对象（远程）。远程访问该对象时，会根据需要复制和缓存视图。除了自动缓存的影响之外，array_view 对象的性能配置文件类似于 array 对象的性能配置文件。通过视图访问数据时，性能会降低。

有三种远程使用方案：

系统内存指针的视图通过 parallel_for_each 调用传递给加速器并在加速器上访问。
位于加速器上的阵列的视图通过 parallel_for_each 调用传递给另一个加速器并在那里访问。
在 CPU 上访问位于加速器上的阵列的视图。

在任何一种情况下，引用的视图都由运行时复制到远程位置，如果通过对 array_view 对象的调用进行修改，则将其复制回本地位置。运行时可能会优化将更改复制回来的过程，可能只复制更改的元素，或者也可能复制未更改的部分。不能保证一个数据源上的重叠 array_view 对象在远程位置保持引用完整性。

必须同步对同一个数据源的所有多线程访问。

运行时对 array_view 对象中的数据缓存做出以下保证：

所有按程序顺序对 array 对象及其上的 array_view 对象进行良好同步访问都遵循串行发生前的关系。
对单个 array 对象上同一个加速器上重叠 array_view 对象的所有良好同步访问都通过 array 对象进行别名化。它们引发了一个完全的先发生关系，该关系遵从程序顺序。没有缓存。如果 array_view 对象在不同的加速器上执行，则未定义访问顺序，从而创建争用条件。

使用系统内存中的指针创建 array_view 对象时，必须仅通过 array_view 指针更改视图 array_view 对象。或者，如果基础本机内存直接更改，而不是通过 array_view 对象更改，则必须对附加到系统指针的 array_view 对象之一调用 refresh()。

任一操作都会通知 array_view 对象基础本机内存已更改，并且位于加速器上的任何副本都已过时。如果遵循这些准则，则基于指针的视图与提供给数据并行数组视图的视图相同。

继承层次结构

_Array_view_shape

_Array_view_base

array_view

要求

标头： amp.h

命名空间： 并发

~array_view

销毁 array_view 对象。

~array_view()restrict(amp,cpu);

array_view

初始化 array_view 类的新实例。

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);

参数

_Arr_type
从中提供数据的 C 样式数组的元素类型。

_Container
必须指定支持 data() 和 size() 成员的线性容器的模板参数。

_E0
本部分盘区中最重要的组成部分。

_E1
本部分盘区中次重要的组成部分。

_E2
本部分盘区中最不重要的组成部分。

_Extent
此 array_view 的每个维度中的盘区。

_Other
用于初始化新 array_view 的 array_view<T,N> 类型的对象。

_Size
从中提供数据的 C 样式数组的大小。

_Src
指向将被复制到新数组中的源数据的指针。

copy_to

通过调用 copy(*this, dest) 将 array_view 对象的内容复制到指定的目标对象。

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

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

参数

_Dest
要复制到的对象。

数据

返回一个指向 array_view 的原始数据的指针。

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

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

返回值

指向 array_view 原始数据的指针。

discard_data

放弃此视图的当前基础数据。这是运行时的优化提示，用于避免将视图的当前内容复制到访问它的目标 accelerator_view，如果不需要现有内容，建议使用它。此方法在 restrict(amp) 上下文中使用时是无操作的

void discard_data() const restrict(cpu);

extent

获取定义 extent 对象形状的 array_view 对象。

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

get_extent

返回 array_view 对象的 extent 对象。

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

返回值

extent 对象的 array_view 对象。

get_ref

获取对由 _Index 索引的元素的引用。与其他用于访问 CPU 上的 array_view 的索引运算符不同，此方法不会将此 array_view 的内容隐式同步到 CPU。在远程访问 array_view 或执行涉及此 array_view 的复制操作后，用户有责任在调用此方法之前将 array_view 显式同步到 CPU。不这样做会导致未定义的行为。

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

参数

_Index
索引。

返回值

对由 _Index 索引的元素的引用

get_source_accelerator_view

返回 array_view 的数据源所在的 accelerator_view。如果 array_view 没有数据源，此 API 将引发 runtime_exception

accelerator_view get_source_accelerator_view() const;

返回值

operator()

返回由一个或多个参数指定的元素的值。

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);

参数

_Index
元素的位置。

_I0
第一个维度中的索引。

_I1
第二个维度中的索引。

_I2
第三个维度中的索引。

_I
元素的位置。

返回值

由一个或多个参数指定的元素的值。

operator[]

返回由参数指定的元素。

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);

参数

_Index
索引。

_I
索引。

返回值

索引处元素的值，或投影在最重要维度上的 array_view。

operator=

将指定 array_view 对象的内容复制到此对象中。

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

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

参数

_Other
要从其复制的 array_view 对象。

返回值

对此 array_view 对象的引用。

rank

存储 array_view 对象的秩。

static const int rank = _Rank;

刷新

通知 array_view 对象其绑定的内存已在 array_view 接口之外进行了修改。调用此方法会使所有缓存的信息过时。

void refresh() const restrict(cpu);

reinterpret_as

通过一维 array_view 重新解释 array_view，作为一个选项，它可以具有与源 array_view 不同的值类型。

语法

template <
    typename _Value_type2
>
array_view< _Value_type2, _Rank> reinterpret_as() const restrict(amp,cpu);

template <
    typename _Value_type2
>
array_view<const _Value_type2, _Rank> reinterpret_as() const restrict(amp,cpu);

参数

_Value_type2
新 array_view 对象的数据类型。

返回值

基于此 array_view 的 array_view 对象或 const array_view 对象，元素类型从 T 转换为 _Value_type2，排名从 N 减少到 1。

注解

有时，将多维数组视为线性的一维数组会很方便，它的值类型可能与源数组不同。可以使用此方法在 array_view 上实现此目的。

警告使用不同的值类型重新解释 array_view 对象是一种潜在的不安全操作。此功能应谨慎使用。

下面是一个示例：

struct RGB { float r; float g; float b; };

array<RGB,3>  a = ...;
array_view<float,1> v = a.reinterpret_as<float>();

assert(v.extent == 3*a.extent);

section

返回位于指定原点以及（可选）具有指定范围的 array_view 对象的一个子部分。

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);

参数

_E0
本部分盘区中最重要的组成部分。

_E1
本部分盘区中次重要的组成部分。

_E2
本部分盘区中最不重要的组成部分。

_Ext
指定该部分的盘区的 extent 对象。原点为 0。

_Idx
指定原点位置的 index 对象。子部分是盘区的其余部分。

_I0
本部分原点的最重要的组成部分。

_I1
本部分原点的次重要的组成部分。

_I2
本部分原点的最不重要的组成部分。

_Rank
节的排名。

_Section_extent
指定该部分的盘区的 extent 对象。

_Section_origin
指定原点位置的 index 对象。

返回值

位于指定原点以及（可选）具有指定范围的 array_view 对象的一个子部分。当仅指定 index 对象时，该子部分包含关联盘区中的所有元素，其索引大于 index 对象中元素的索引。

source_accelerator_view

获取与此 array_view 关联的源 accelerator_view。

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

synchronize

将对 array_view 对象所做的任何修改同步回其源数据。

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

void synchronize() const restrict(cpu);

参数

_Access_type
目标 accelerator_view 上的预期 access_type。此参数的默认值为 access_type_read。

synchronize_async

将对 array_view 对象所做的任何修改以异步方式同步回其源数据。

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

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

参数

_Access_type
目标 accelerator_view 上的预期 access_type。此参数的默认值为 access_type_read。

返回值

等待操作完成的未来。

synchronize_to

将对此 array_view 所做的任何修改同步到指定的 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);

参数

_Accl_view
要同步到的目标 accelerator_view。

_Access_type
目标 accelerator_view 上的预期 access_type。此参数的默认值为 access_type_read。

synchronize_to_async

将对此 array_view 所做的任何修改以异步方式同步到指定的 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);

参数