OpenCL运行时:内存

class pyopencl.MemoryObject
info

的小写版本 mem_info 常量可以用作此类实例上的属性,以直接查询信息属性。

hostbuf
get_info(param)

mem_info 对于价值 param .

release()
get_host_array(shape, dtype, order='C')

将内存对象的关联主机内存区域作为 numpy.ndarray 给定的 形状D型秩序 .

static from_int_ptr(int_ptr_value: int, retain: bool = True)object

(静态方法)返回一个引用C级的新Python对象 cl_mem 对象指向的位置 int_ptr_value . 相关的 clRetain* 函数将被调用,如果 保持 是是的,如果对象的前所有者将 not 释放引用, 保持 应设置为 ,有效地将所有权转移给 pyopencl .

2013.2 新版功能.

在 2016.1 版更改: 保持 补充。

int_ptr

返回与基础 cl_mem . 使用 from_int_ptr() 返回到Python对象。

2013.2 新版功能.

Instances of this class are hashable, and two instances of this class may be compared using "==" and "!=". (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

内存迁移

pyopencl.enqueue_migrate_mem_objects(queue, mem_objects, flags=0, wait_for=None)
参数

flags -- 从 mem_migration_flags

2011.2 新版功能.

仅适用于CL 1.2。

缓冲区

class pyopencl.Buffer(context, flags, size=0, hostbuf=None)

创建一个 Buffer . 见 mem_flags 对于价值 旗帜 .如果 霍斯特布夫 已指定, size 如果指定的缓冲区作为零传递,则默认为该缓冲区的大小。

Buffer 继承自 MemoryObject .

注解

Python还定义了一种 buffer object ,而PyOpenCL也与之交互,作为的主机端目标 enqueue_copy() . 确保始终清楚 Buffer 或者需要Python缓冲区对象。

请注意,OpenCL中的实际内存分配可能会延迟。缓冲器连接到 Context 只有在设备上使用了缓冲区后,才会将和移动到该设备。这也是发生内存不足错误的时间点。如果您想确保有足够的内存用于分配,可以使用 enqueue_migrate_mem_objects() (如果可用)或只是执行一个小的传输到缓冲区。另请参见 pyopencl.tools.ImmediateAllocator .

get_sub_region(origin, size, flags=0)

仅在OpenCL1.1及更新版本中可用。

__getitem__(slc)

slc 是一个 slice 对象,指示要从哪个字节索引范围创建子缓冲区。这个 旗帜 的参数 get_sub_region() 设置为与 self 创建。

pyopencl.enqueue_fill_buffer(queue, mem, pattern, offset, size, wait_for=None)
参数
  • mem -- 在设备上 Buffer

  • pattern -- 缓冲对象(可能是 numpy.ndarray 例如。 np.uint32(0) )与…有关的记忆 模式 函数完成后可以重用或释放。

  • size -- 要填充的区域的大小(字节)。必须是图案大小的倍数。

  • offset -- 正在填充的区域的位置(以字节为单位) mem . 必须是图案大小的倍数。

用提供的模式填充缓冲区

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting exeuction.

仅适用于CL 1.2。

2011.2 新版功能.

共享虚拟内存(SVM)

共享虚拟内存允许主机和计算设备共享地址空间,因此主机和设备上的指针可能具有相同的含义。此外,它允许主机和设备访问相同的内存。 Coarse-grain SVM要求在主机上访问缓冲区之前映射缓冲区, fine-grain SVM取消了这个要求。

SVM需要OpenCL2.0。

class pyopencl.SVM(mem)

标记显示Python缓冲区接口的对象(例如 numpy.ndarray )指的是共享虚拟内存。

根据OpenCL实现的特性,可以将以下类型的对象传递给该类型或包装为该类型:

  • 由(例如)返回的粗粒度共享内存 csvm_empty() 对于OpenCL2.0的任何实现。

    这就是如何从主机和设备使用粗粒度支持向量机:

    svm_ary = cl.SVM(
        cl.csvm_empty(ctx, 1000, np.float32, alignment=64))
    assert isinstance(svm_ary.mem, np.ndarray)
    
    with svm_ary.map_rw(queue) as ary:
        ary.fill(17)  # use from host
    
    prg.twice(queue, svm_ary.mem.shape, None, svm_ary)
    
  • 返回的细粒度共享内存(例如) fsvm_empty() ,如果实现支持细粒度共享虚拟内存。此内存可以直接传递给内核:

    ary = cl.fsvm_empty(ctx, 1000, np.float32)
    assert isinstance(ary, np.ndarray)
    
    prg.twice(queue, ary.shape, None, cl.SVM(ary))
    queue.finish() # synchronize
    print(ary) # access from host
    

    观察如何映射(如粗粒度支持向量机所需)不再是必需的。

  • 任何 numpy.ndarray (或其他带有缓冲区接口的Python对象)如果实现支持细粒度 系统 共享虚拟内存。

    这是多么简单 numpy 数组可以直接传递给内核:

    ary = np.zeros(1000, np.float32)
    prg.twice(queue, ary.shape, None, cl.SVM(ary))
    queue.finish() # synchronize
    print(ary) # access from host
    

这种类型的对象可以传递给内核调用和 enqueue_copy() . 粗粒度共享内存 must 映射到主机地址空间 map() 在通过 numpy 接口。

注解

这个对象只是作为一个“标记”来改变它所传递到的函数的行为。它与它标记的内存没有特殊的管理关系。例如,可以抓取 numpy.ndarray 由于 SVM.mem 一个的 SVM 实例并使用数组构造另一个。两个标签都不需要保存。

2016.2 新版功能.

mem

包裹的对象。

__init__(mem)

初始化自身。请参阅帮助(键入(self))以获得准确的签名。

map(queue, flags, is_blocking=True, wait_for=None)
参数
  • is_blocking -- 如果 ,后续代码必须等待 SVMMap.event 在访问映射内存之前返回对象。

  • flags -- 组合 pyopencl.map_flags ,默认为读写。

返回

一个 SVMMap 实例

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting exeuction.

map_ro(queue, is_blocking=True, wait_for=None)

喜欢 map() 但是 旗帜 设置为只读映射。

map_rw(queue, is_blocking=True, wait_for=None)

喜欢 map() 但是 旗帜 设置为只读映射。

as_buffer(ctx, flags=None)
参数
返回

Buffer 对应于 self .

在返回之前,不能释放此对象引用的内存 Buffer 被释放。

class pyopencl.SVMMap(svm, queue, event)
event

2016.2 新版功能.

release(queue=None, wait_for=None)
参数

queue -- 一 pyopencl.CommandQueue . 默认为创建映射时使用的映射(如果未指定)。

返回

pyopencl.Event

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting exeuction.

该类也可以用作 with 语句。 release() 将在退出 with 地区。返回给 as 上下文管理器的一部分是映射的Python对象(例如 numpy 阵列)。

分配支持向量机

pyopencl.svm_empty(ctx, flags, shape, dtype, order='C', alignment=None)

分配一个空的 numpy.ndarray 给定的 形状D型秩序 . (见 numpy.empty() 数组将被分配到属于的共享虚拟内存中 ctx .

参数
返回

numpy.ndarray 谁的 numpy.ndarray.base 属性是 SVMAllocation .

将结果数组传递给OpenCL内核或 enqueue_copy() ,您可能希望将返回的数组包装在 SVM 标签。

2016.2 新版功能.

pyopencl.svm_empty_like(ctx, flags, ary, alignment=None)

Allocate an empty numpy.ndarray like the existing numpy.ndarray ary. The array will be allocated in shared virtual memory belonging to ctx.

参数
返回

numpy.ndarray 谁的 numpy.ndarray.base 属性是 SVMAllocation .

将结果数组传递给OpenCL内核或 enqueue_copy() ,您可能希望将返回的数组包装在 SVM 标签。

2016.2 新版功能.

pyopencl.csvm_empty(ctx, shape, dtype, order='C', alignment=None)

喜欢 svm_empty() 但是 旗帜 为粗粒度读写缓冲区设置。

2016.2 新版功能.

pyopencl.csvm_empty_like(ctx, ary, alignment=None)

喜欢 svm_empty_like() 但是 旗帜 为粗粒度读写缓冲区设置。

2016.2 新版功能.

pyopencl.fsvm_empty(ctx, shape, dtype, order='C', alignment=None)

喜欢 svm_empty() 但是 旗帜 设置为细粒度读写缓冲区。

2016.2 新版功能.

pyopencl.fsvm_empty_like(ctx, ary, alignment=None)

喜欢 svm_empty_like() 但是 旗帜 设置为细粒度读写缓冲区。

2016.2 新版功能.

支持向量机的运算

(也见) 转移

pyopencl.enqueue_svm_memfill(queue, dest, pattern, byte_count=None, wait_for=None)

用模式填充共享虚拟内存。

参数
  • dest -- Python缓冲区对象,可选地包装在 SVM 对象

  • pattern -- Python缓冲区对象(例如 numpy.ndarray 使用填充图案。

  • byte_count -- 要填充的内存大小。默认为 dest .

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting exeuction.

2016.2 新版功能.

pyopencl.enqueue_svm_migratemem(queue, svms, flags, wait_for=None)
参数
  • svms -- Python缓冲区对象的集合(例如。 numpy arrrays),可选择包裹在 SVM 物体。

  • flags -- 组合 mem_migration_flags

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting exeuction.

2016.2 新版功能.

此函数需要opencl2.1。

支持向量机分配持有者

class pyopencl.SVMAllocation(ctx, size, alignment, flags, _interface=None)

一种对象,其生存期与共享虚拟内存的分配有关。

注解

很可能,您不想直接使用它,而是 svm_empty() 以及相关函数,这些函数允许使用更友好、更Pythonic的界面访问此功能。

2016.2 新版功能.

__init__(self, ctx, size, alignment, flags=None)
参数
release(self: pyopencl._cl.SVMAllocation)None
enqueue_release(self: pyopencl._cl.SVMAllocation, arg0: pyopencl._cl.CommandQueue, arg1: object)None
返回

pyopencl.Event

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting exeuction.

图像

class pyopencl.ImageFormat([channel_order, channel_type])
channel_order

channel_order 对于可能的值。

channel_data_type

channel_type 对于可能的值。

channel_count

0.91.5 新版功能.

dtype_size

0.91.5 新版功能.

itemsize

0.91.5 新版功能.

__repr__()

返回A str 图像格式的表示。

0.91 新版功能.

Instances of this class are hashable, and two instances of this class may be compared using "==" and "!=". (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

在 0.91 版更改: 已添加构造函数参数。

在 2013.2 版更改: ImageFormat 使之具有可比性和可散列性

pyopencl.get_supported_image_formats(context, flags, image_type)

mem_flags 对于可能的值 旗帜mem_object_type 对于可能的值 image_type .

class pyopencl.Image(context, flags, format, shape=None, pitches=None, hostbuf=None, is_array=False, buffer=None)

mem_flags 对于价值 旗帜 . 形状 是2元组或3元组。 格式 是的实例 ImageFormat . 投球 是用于2D图像的1元组和用于3D图像的2元组,以字节表示从一个扫描线到下一个扫描线以及从一个2D图像切片到下一个扫描线的距离。

如果 霍斯特布夫 被给予和 形状None 然后 hostbuf.shape 用作 形状 参数。

Image 继承自 MemoryObject .

注解

如果要从加载图像 numpy.ndarray 实例或将图像读回实例中,请注意OpenCL图像期望 x 尺寸变化最快,而在默认(C)顺序 numpy 数组中,最后一个索引变化最快。如果数组在内存中的排列顺序错误,则有两种可能的解决方法:

  • 使用将数组转换为Fortran(列主)顺序 numpy.asarray() .

  • 通过 副本() 图像创建功能。

0.91 新版功能.

在 2011.2 版更改: 补充 is_array缓冲区 ,仅在CL 1.2及更新版本上可用。

info

的小写版本 mem_infoimage_info 常量可以用作此类实例上的属性,以直接查询信息属性。

shape

返回的值 形状 构造函数参数作为 tuple .

get_image_info(param)

image_info 对于价值 param .

release()

Instances of this class are hashable, and two instances of this class may be compared using "==" and "!=". (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

pyopencl.image_from_array(ctx, ary, num_channels=None, mode='r', norm_int=False)

Build a 2D or 3D Image from the numpy.ndarray ary. If num_channels is greater than one, the last dimension of ary must be identical to num_channels. ary must be in C order. If num_channels is not given, it defaults to 1 for scalar types and the number of entries for 向量类型.

这个 ImageFormat 被选为第一个 num_channels “RGBA”的组成部分。

参数

mode -- “r”或“w”表示读/写

注解

从图像对象读取时,索引传递给 read_imagef 与访问时的顺序相反 ary 从 Python 。

如果 norm_intTrue ,则在读取时,整数值被标准化为0..1的浮点刻度。

2011.2 新版功能.

pyopencl.enqueue_fill_image(queue, mem, color, origin, region, wait_for=None)
参数

color -- 缓冲对象(可能是 numpy.ndarray

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting exeuction.

仅适用于CL 1.2。

2011.2 新版功能.

转移

pyopencl.enqueue_copy(queue, dest, src, **kwargs)

复制自 ImageBuffer 或是主人 ImageBuffer 或者是主人。(注意:不支持主机到主机的副本。)

以下关键字参数可用:

参数
  • wait_for -- (可选,默认为空)

  • is_blocking -- 等待完成。默认为 True . (可在任何涉及主机内存的副本上使用)

返回

A NannyEvent 如果传输涉及主机端缓冲区,则 Event .

注解

请注意,删除 NannyEvent 如果传输涉及主机端缓冲区,则函数将返回该值,直到传输完成为止,因此请确保保留对此的引用 Event 直到转移完成。

注解

此函数的参数中有两种类型的“buffer”, Buffer 和“主机侧缓冲区”。后者由Python定义,通常称为 buffer objects . numpy 数组是一个非常常见的例子。确保始终清楚 Buffer 或者需要Python缓冲区对象。

换乘 Buffer ↔ 主办

参数

device_offset -- 偏移量(字节)(可选)

注解

传输的大小由主机端缓冲区的大小控制。如果主机端缓冲区是 numpy.ndarray ,您可以通过传输到目标数组的较小“视图”来控制传输大小,如下所示:

cl.enqueue_copy(queue, large_dest_numpy_array[:15], src_buffer)

换乘 BufferBuffer

参数
  • byte_count -- (可选)如果未指定,则默认为版本2012.x及更早版本中源的大小,以及2013.1以后源和目标的最小大小。

  • src_offset -- (可选)

  • dest_offset -- (可选)

矩形 Buffer ↔ 主机传输(CL 1.1及更新版本)

参数
  • buffer_origin -- tuple 属于 int 长度三或更短的。(强制性)

  • host_origin -- tuple 属于 int 长度三或更短的。(强制性)

  • region -- tuple 属于 int 长度三或更短的。(强制性)

  • buffer_pitches -- tuple 属于 int 长度为2或更短的。(可选,如果未指定,则“紧密包装”)

  • host_pitches -- tuple 属于 int 长度为2或更短的。(可选,如果未指定,则“紧密包装”)

矩形 BufferBuffer 转让(CL 1.1及更新版本)

参数
  • src_origin -- tuple 属于 int 长度三或更短的。(强制性)

  • dst_origin -- tuple 属于 int 长度三或更短的。(强制性)

  • region -- tuple 属于 int 长度三或更短的。(强制性)

  • src_pitches -- tuple 属于 int 长度为2或更短的。(可选,如果未指定,则“紧密包装”)

  • dst_pitches -- tuple 属于 int 长度为2或更短的。(可选,如果未指定,则“紧密包装”)

换乘 Image ↔ 主办

参数
  • origin -- tuple 属于 int 长度三或更短的。(强制性)

  • region -- tuple 属于 int 长度三或更短的。(强制性)

  • pitches -- tuple 属于 int 长度为2或更短的。(可选)

换乘 BufferImage

参数
  • offset -- 缓冲区中的偏移量(强制)

  • origin -- tuple 属于 int 长度三或更短的。(强制性)

  • region -- tuple 属于 int 长度三或更短的。(强制性)

换乘 ImageImage

参数
  • src_origin -- tuple 属于 int 长度三或更短的。(强制性)

  • dest_origin -- tuple 属于 int 长度三或更短的。(强制性)

  • region -- tuple 属于 int 长度三或更短的。(强制性)

换乘 SVM /主持人↔ SVM /主持人

参数

byte_count -- (可选)如果未指定,则默认为版本2012.x及更早版本中源的大小,以及2013.1以后源和目标的最小大小。

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting exeuction.

2011.1 新版功能.

将内存映射到主机地址空间

class pyopencl.MemoryMap

该类也可以用作 with 声明。删除或删除此对象时,将取消映射与此对象对应的内存 release() 被称为。

release(self: pyopencl._cl.MemoryMap, queue: pyopencl._cl.CommandQueue = None, wait_for: object = None)pyopencl._cl.Event
pyopencl.enqueue_map_buffer(queue, buf, flags, offset, shape, dtype, order='C', strides=None, wait_for=None, is_blocking=True)

wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting exeuction. 形状D型秩序 与中的含义相同 numpy.empty() . 见 map_flags 对于可能的值 旗帜 . 大步 ,如果给定,则重写 秩序 .

返回

元组 (数组,事件) . 数组 是一个 numpy.ndarray 表示地图的主机端。它 .底座 成员包含 MemoryMap .

在 2011.1 版更改: is_blocking 现在默认为True。

在 2013.1 版更改: 秩序 现在默认为“C”。

在 2013.2 版更改: 补充 大步 争论。

样品使用情况:

mapped_buf = cl.enqueue_map_buffer(queue, buf, ...)
with mapped_buf.base:
    # work with mapped_buf
    ...

# memory will be unmapped here
pyopencl.enqueue_map_image(queue, buf, flags, origin, region, shape, dtype, order='C', strides=None, wait_for=None, is_blocking=True)

wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting exeuction. 形状D型秩序 与中的含义相同 numpy.empty() . 见 map_flags 对于可能的值 旗帜 . 大步 ,如果给定,则重写 秩序 .

返回

元组 (数组,事件) . 数组 是一个 numpy.ndarray 表示地图的主机端。它 .底座 成员包含 MemoryMap .

在 2011.1 版更改: is_blocking 现在默认为True。

在 2013.1 版更改: 秩序 现在默认为“C”。

在 2013.2 版更改: 补充 大步 争论。

采样器

class pyopencl.Sampler
__init__(context, normalized_coords, addressing_mode, filter_mode)

normalized_coords 是一个 bool 指示是否使用0和1之间的坐标( True )或者纹理的自然像素大小( )见 addressing_modefilter_mode 可能的参数值。

还支持备用签名 (context, properties) .

参数

properties -- 来自的键和值的序列 sampler_properties 已被接受 clCreateSamplerWithProperties() (有关详细信息,请参见OpenCL规范)。尾随 0 是自动添加的,不需要包括在内。

此签名需要OpenCL 2或更新版本。

在 2018.2 版更改: 添加了基于属性的签名。

info

的小写版本 sampler_info 常量可以用作此类实例上的属性,以直接查询信息属性。

get_info(param)

sampler_info 对于价值 param .

static from_int_ptr(int_ptr_value: int, retain: bool = True)pyopencl._cl.Sampler

(静态方法)返回一个引用C级的新Python对象 cl_sampler 对象指向的位置 int_ptr_value . 相关的 clRetain* 函数将被调用,如果 保持 是是的,如果对象的前所有者将 not 释放引用, 保持 应设置为 ,有效地将所有权转移给 pyopencl .

2013.2 新版功能.

在 2016.1 版更改: 保持 补充。

int_ptr

返回与基础 cl_sampler . 使用 from_int_ptr() 返回到Python对象。

2013.2 新版功能.

Instances of this class are hashable, and two instances of this class may be compared using "==" and "!=". (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

class pyopencl.Pipe(context, flags, packet_size, max_packets, properties)

mem_flags 对于价值 旗帜 .

参数

properties -- 来自的键和值的序列 pipe_properties 已被接受 clCreatePipe() . 尾随 0 是自动添加的,不需要包括在内。

此函数需要OpenCL 2或更新版本。

2020.3 新版功能.

get_pipe_info(param)

pipe_info 对于价值 param .