已注册到 cufile 的打开文件句柄。更多...

#include <file_handle.hpp>

公共成员函数
	FileHandle (std::string const &file_path, std::string const &flags="r", mode_t mode=m644, CompatMode compat_mode=defaults::compat_mode())
	从文件路径构造文件句柄。更多...

	FileHandle (FileHandle const &)=delete
	FileHandle 支持移动语义，但不可复制。

FileHandle &	operator= (FileHandle const &)=delete

	FileHandle (FileHandle &&o) noexcept

FileHandle &	operator= (FileHandle &&o) noexcept

bool	closed () const noexcept
	文件是否根据其初始化状态关闭。更多...

void	close () noexcept
	注销文件并关闭两个文件。

CUfileHandle_t	handle ()
	获取底层的 cuFile 文件句柄。更多...

int	fd (bool o_direct=false) const noexcept
	获取文件描述符之一。更多...

int	fd_open_flags (bool o_direct=false) const
	获取文件描述符之一的标志（参见 open(2)）。更多...

std::size_t	nbytes () const
	获取文件大小。更多...

std::size_t	read (void *devPtr_base, std::size_t size, std::size_t file_offset, std::size_t devPtr_offset, bool sync_default_stream=true)
	将文件中指定的字节读取到设备内存中。更多...

std::size_t	write (void const *devPtr_base, std::size_t size, std::size_t file_offset, std::size_t devPtr_offset, bool sync_default_stream=true)
	将设备内存中指定的字节写入文件。更多...

std::future< std::size_t >	pread (void *buf, std::size_t size, std::size_t file_offset=0, std::size_t task_size=defaults::task_size(), std::size_t gds_threshold=defaults::gds_threshold(), bool sync_default_stream=true)
	并行地将文件中指定的字节读取到设备或主机内存中。更多...

std::future< std::size_t >	pwrite (void const *buf, std::size_t size, std::size_t file_offset=0, std::size_t task_size=defaults::task_size(), std::size_t gds_threshold=defaults::gds_threshold(), bool sync_default_stream=true)
	并行地将设备或主机内存中指定的字节写入文件。更多...

void	read_async (void devPtr_base, std::size_t size_p, off_t file_offset_p, off_t devPtr_offset_p, ssize_t *bytes_read_p, CUstream stream)
	异步地将文件中指定的字节读取到设备内存中。更多...

StreamFuture	read_async (void *devPtr_base, std::size_t size, off_t file_offset=0, off_t devPtr_offset=0, CUstream stream=nullptr)
	异步地将文件中指定的字节读取到设备内存中。更多...

void	write_async (void devPtr_base, std::size_t size_p, off_t file_offset_p, off_t devPtr_offset_p, ssize_t *bytes_written_p, CUstream stream)
	异步地将设备内存中指定的字节写入文件。更多...

StreamFuture	write_async (void *devPtr_base, std::size_t size, off_t file_offset=0, off_t devPtr_offset=0, CUstream stream=nullptr)
	异步地将设备内存中指定的字节写入文件。更多...

const CompatModeManager &	get_compat_mode_manager () const noexcept
	获取关联的兼容模式管理器，可用于查询原始请求的兼容模式或同步和异步 I/O 的预期兼容模式。更多...

公共静态属性
static constexpr mode_t	m644 = S_IRUSR \| S_IWUSR \| S_IRGRP \| S_IROTH

友元
class	CompatModeManager

详细描述

已注册到 cufile 的打开文件句柄。

为了利用 cufile 和 GDS，文件必须注册到 cufile。

定义于文件 file_handle.hpp 的第 47 行。

构造函数与析构函数文档

◆ FileHandle()

kvikio::FileHandle::FileHandle	(	std::string const &	file_path,
		std::string const &	flags = `"r"`,
		mode_t	mode = `m644`,
		CompatMode	compat_mode = `defaults::compat_mode()`
	)

从文件路径构造文件句柄。

FileHandle 会打开文件两次并维护两个文件描述符。一个文件使用指定的 flags 打开，另一个文件使用 flags 加上 O_DIRECT 标志打开。

参数

file_path	文件路径
flags	打开标志（另见 `fopen(3)`）："r" -> "以只读方式打开（默认）" "w" -> "以只写方式打开，先清空文件" "a" -> "以只写方式打开，如果文件存在则追加到末尾" "+" -> "以更新方式打开（读写）"
mode	访问模式（参见 `open(2)`）。
compat_mode	为此文件设置 KvikIO 的兼容模式。

成员函数文档

◆ closed()

bool kvikio::FileHandle::closed ( ) const

noexcept

文件是否根据其初始化状态关闭。

返回值: 布尔值结果。

◆ fd()

int kvikio::FileHandle::fd ( bool o_direct = false ) const

noexcept

获取文件描述符之一。

请注意，FileHandle 维护两个文件描述符 - 一个使用 O_DIRECT 标志打开，一个不使用。

参数

o_direct 是否获取使用 O_DIRECT 标志打开的文件描述符。

返回值: 文件描述符

◆ fd_open_flags()

int kvikio::FileHandle::fd_open_flags ( bool o_direct = false ) const

获取文件描述符之一的标志（参见 open(2)）

请注意，FileHandle 维护两个文件描述符 - 一个使用 O_DIRECT 标志打开，一个不使用。

参数

o_direct 是否获取使用 O_DIRECT 标志打开的文件描述符的标志。

返回值: 文件描述符

◆ get_compat_mode_manager()

const CompatModeManager& kvikio::FileHandle::get_compat_mode_manager ( ) const

noexcept

获取关联的兼容模式管理器，可用于查询原始请求的兼容模式或同步和异步 I/O 的预期兼容模式。

返回值: 关联的兼容模式管理器。

◆ handle()

CUfileHandle_t kvikio::FileHandle::handle ( )

获取底层的 cuFile 文件句柄。

文件句柄必须是打开的且不处于兼容模式，即 closed() 和 is_compat_mode_preferred() 都必须为 false。

返回值: cuFile 的文件句柄

◆ nbytes()

std::size_t kvikio::FileHandle::nbytes ( ) const

获取文件大小。

该值已缓存。

返回值: 字节数

◆ pread()

std::future<std::size_t> kvikio::FileHandle::pread	(	void *	buf,
		std::size_t	size,
		std::size_t	file_offset = `0`,
		std::size_t	task_size = `defaults::task_size()`,
		std::size_t	gds_threshold = `defaults::gds_threshold()`,
		bool	sync_default_stream = `true`
	)

并行地将文件中指定的字节读取到设备或主机内存中。

此 API 是 .read() 的并行异步版本，它将操作分割成 task_size 大小的任务，并在默认线程池中执行。

为了提高小缓冲区的性能，当 size < gds_threshold 时，会使用直接绕过线程池并直接使用 POSIX 后端的快捷方式。

注意: 对于 cuFile 读取，分配的 buf 基地址是使用的部分。这意味着注册缓冲区时，请使用分配的基地址。memory_register 和 memory_deregister 会自动执行此操作。

参数

buf	设备或主机内存地址。
size	要读取的字节大小。
file_offset	文件中的读取偏移量。
task_size	每个任务的字节大小。
gds_threshold	使用 GDS 和线程池所需的最小缓冲区大小。
sync_default_stream	在调用 cuFile 之前同步 CUDA 默认（空）流。与大多数非异步 CUDA API 不同，cuFile 在默认流中与其他非 cuFile 工作没有顺序语义。通过启用 `sync_default_stream`，KvikIO 将同步默认流并使操作与空流中的其他工作有序。当处于 KvikIO 的兼容模式或访问主机内存时，操作始终像其他非异步 CUDA API 一样按照默认流顺序执行。在这种情况下，`sync_default_stream` 的值将被忽略。

返回值: 完成时返回成功读取的字节数的 future 对象。

注意: FileHandle 对象的生命周期结束后，不应调用 std::future 对象的 wait() 或 get()。否则，行为未定义。

◆ pwrite()

std::future<std::size_t> kvikio::FileHandle::pwrite	(	void const *	buf,
		std::size_t	size,
		std::size_t	file_offset = `0`,
		std::size_t	task_size = `defaults::task_size()`,
		std::size_t	gds_threshold = `defaults::gds_threshold()`,
		bool	sync_default_stream = `true`
	)

并行地将设备或主机内存中指定的字节写入文件。

此 API 是 .write() 的并行异步版本，它将操作分割成 task_size 大小的任务，并在默认线程池中执行。

为了提高小缓冲区的性能，当 size < gds_threshold 时，会使用直接绕过线程池并直接使用 POSIX 后端的快捷方式。

注意: 对于 cuFile 读取，分配的 buf 基地址是使用的部分。这意味着注册缓冲区时，请使用分配的基地址。memory_register 和 memory_deregister 会自动执行此操作。

参数

buf	设备或主机内存地址。
size	要写入的字节大小。
file_offset	文件中的写入偏移量。
task_size	每个任务的字节大小。
gds_threshold	使用 GDS 和线程池所需的最小缓冲区大小。
sync_default_stream	在调用 cuFile 之前同步 CUDA 默认（空）流。与大多数非异步 CUDA API 不同，cuFile 在默认流中与其他非 cuFile 工作没有顺序语义。通过启用 `sync_default_stream`，KvikIO 将同步默认流并使操作与空流中的其他工作有序。当处于 KvikIO 的兼容模式或访问主机内存时，操作始终像其他非异步 CUDA API 一样按照默认流顺序执行。在这种情况下，`sync_default_stream` 的值将被忽略。

返回值: 完成时返回成功写入的字节数的 future 对象。

注意: FileHandle 对象的生命周期结束后，不应调用 std::future 对象的 wait() 或 get()。否则，行为未定义。

◆ read()

std::size_t kvikio::FileHandle::read	(	void *	devPtr_base,
		std::size_t	size,
		std::size_t	file_offset,
		std::size_t	devPtr_offset,
		bool	sync_default_stream = `true`
	)

将文件中指定的字节读取到设备内存中。

此 API 使用 GDS 功能将 GPU 内存中的数据按指定偏移量和大小读取到文件。该 API 对于未对齐的偏移量和数据大小也能正常工作，但性能不如对齐读取。这是一个同步调用，会阻塞直到 I/O 完成。

注意: 对于 devPtr_offset，如果数据将从通过 buffer_register 注册的 devPtr_base 精确开始读取，则 devPtr_offset 应设置为 0。要从注册的缓冲区范围内的偏移量开始读取，应在 devPtr_offset 中指定相对偏移量，并且 devPtr_base 必须保持设置为 buffer_register 调用中使用的基地址。

参数

devPtr_base	设备内存中缓冲区的基地址。对于注册的缓冲区，`devPtr_base` 必须保持设置为 `buffer_register` 调用中使用的基地址。
size	要读取的字节大小。
file_offset	文件中的读取偏移量。
devPtr_offset	相对于 `devPtr_base` 指针的读取偏移量。此参数仅应与注册的缓冲区一起使用。
sync_default_stream	在调用 cuFile 之前同步 CUDA 默认（空）流。与大多数非异步 CUDA API 不同，cuFile 在默认流中与其他非 cuFile 工作没有顺序语义。通过启用 `sync_default_stream`，KvikIO 将同步默认流并使操作与空流中的其他工作有序。当处于 KvikIO 的兼容模式或访问主机内存时，操作始终像其他非异步 CUDA API 一样按照默认流顺序执行。在这种情况下，`sync_default_stream` 的值将被忽略。

返回值: 成功读取的字节数。

◆ read_async() [1/2]

void kvikio::FileHandle::read_async	(	void *	devPtr_base,
		std::size_t *	size_p,
		off_t *	file_offset_p,
		off_t *	devPtr_offset_p,
		ssize_t *	bytes_read_p,
		CUstream	stream
	)

异步地将文件中指定的字节读取到设备内存中。

这是 .read() 的异步版本，将在指定流中按顺序执行。

在运行 CUDA v12.1 或更早版本时，此函数会在 stream 同步后回退使用 .read()。

这些参数的含义与 .read() 中相同，但其中一些被延迟执行。也就是说，size_p、file_offset_p 和 devPtr_offset_p 指向的值直到执行时才会求值。请注意，可以使用 cuFile 的 cuFileStreamRegister API 更改此行为。

参数

devPtr_base	设备内存中缓冲区的基地址。对于注册的缓冲区，`devPtr_base` 必须保持设置为 `buffer_register` 调用中使用的基地址。
size_p	指向要读取的字节大小的指针。如果在提交 I/O 时不知道确切大小，则必须将其设置为该流 I/O 的最大可能 I/O 大小。稍后，可以在流 I/O 执行之前设置实际大小。
file_offset_p	指向文件中开始读取的偏移量的指针。除非使用 cuFileStreamRegister API 另行设置，否则此值直到执行时才会求值。
devPtr_offset_p	指向相对于 bufPtr_base 的写入偏移量的指针。除非使用 cuFileStreamRegister API 另行设置，否则此值直到执行时才会求值。
bytes_read_p	指向从文件读取的字节数的指针。此指针应为非 NULL 值，并且 bytes_read_p 应设置为 0。bytes_read_p 内存应使用 cuMemHostAlloc/malloc/mmap 分配或使用 cuMemHostRegister 注册。在流中成功执行操作后，bytes_read_p 的值将包含以下之一：成功读取的字节数。 -1（发生 I/O 错误时）。所有其他错误返回 CUfileOpError 枚举值的负整数值。
stream	将操作排入队列的 CUDA 流。如果为 NULL，则使此操作同步。

◆ read_async() [2/2]

StreamFuture kvikio::FileHandle::read_async	(	void *	devPtr_base,
		std::size_t	size,
		off_t	file_offset = `0`,
		off_t	devPtr_offset = `0`,
		CUstream	stream = `nullptr`
	)

异步地将文件中指定的字节读取到设备内存中。

这是 .read() 的异步版本，将在指定流中按顺序执行。

在运行 CUDA v12.1 或更早版本时，此函数会在 stream 同步后回退使用 .read()。

这些参数的含义与 .read() 中相同，但返回一个 StreamFuture 对象，调用者必须使其保持活动状态，直到所有数据从磁盘读取完毕。一种方法是调用 StreamFuture.check_bytes_done()，它将同步关联的流并返回读取的字节数。

参数

devPtr_base	设备内存中缓冲区的基地址。对于注册的缓冲区，`devPtr_base` 必须保持设置为 `buffer_register` 调用中使用的基地址。
size	要读取的字节大小。
file_offset	文件中的读取偏移量。
devPtr_offset	相对于 `devPtr_base` 指针的读取偏移量。此参数仅应与注册的缓冲区一起使用。
stream	将操作排入队列的 CUDA 流。如果为 NULL，则使此操作同步。

返回值: 必须保持活动状态的 future 对象，直到所有数据已读取到磁盘，例如通过同步 stream。

◆ write()

std::size_t kvikio::FileHandle::write	(	void const *	devPtr_base,
		std::size_t	size,
		std::size_t	file_offset,
		std::size_t	devPtr_offset,
		bool	sync_default_stream = `true`
	)

将设备内存中指定的字节写入文件。

此 API 使用 GDS 功能将 GPU 内存中的数据按指定偏移量和大小写入文件。该 API 对于未对齐的偏移量和数据大小也能正常工作，但性能不如对齐写入。这是一个同步调用，会阻塞直到 I/O 完成。

注意: GDS 功能修改了 SysMem 中的标准文件系统元数据。但是，GDS 功能不承担将该元数据写回永久存储的特殊责任。除非应用程序显式调用 fsync(2)，否则无法保证系统崩溃后数据仍然存在。如果文件以 O_SYNC 标志打开，元数据将在调用完成前写入磁盘。有关 devPtr_offset 的更多信息，请参阅 read 中的注释。

参数

devPtr_base	设备内存中缓冲区的基地址。对于注册的缓冲区，`devPtr_base` 必须保持设置为 `buffer_register` 调用中使用的基地址。
size	要写入的字节大小。
file_offset	文件中的写入偏移量。
devPtr_offset	相对于 `devPtr_base` 指针的写入偏移量。此参数仅应与注册的缓冲区一起使用。
sync_default_stream	在调用 cuFile 之前同步 CUDA 默认（空）流。与大多数非异步 CUDA API 不同，cuFile 在默认流中与其他非 cuFile 工作没有顺序语义。通过启用 `sync_default_stream`，KvikIO 将同步默认流并使操作与空流中的其他工作有序。当处于 KvikIO 的兼容模式或访问主机内存时，操作始终像其他非异步 CUDA API 一样按照默认流顺序执行。在这种情况下，`sync_default_stream` 的值将被忽略。

返回值: 成功写入的字节数。

◆ write_async() [1/2]

void kvikio::FileHandle::write_async	(	void *	devPtr_base,
		std::size_t *	size_p,
		off_t *	file_offset_p,
		off_t *	devPtr_offset_p,
		ssize_t *	bytes_written_p,
		CUstream	stream
	)

异步地将设备内存中指定的字节写入文件。

这是 .write() 的异步版本，将在指定流中按顺序执行。

在运行 CUDA v12.1 或更早版本时，此函数会在 stream 同步后回退使用 .read()。

这些参数的含义与 .write() 中相同，但其中一些被延迟执行。也就是说，size_p、file_offset_p 和 devPtr_offset_p 指向的值直到执行时才会求值。请注意，可以使用 cuFile 的 cuFileStreamRegister API 更改此行为。

参数

devPtr_base	设备内存中缓冲区的基地址。对于注册的缓冲区，`devPtr_base` 必须保持设置为 `buffer_register` 调用中使用的基地址。
size_p	指向要读取的字节大小的指针。如果在提交 I/O 时不知道确切大小，则必须将其设置为该流 I/O 的最大可能 I/O 大小。稍后，可以在流 I/O 执行之前设置实际大小。
file_offset_p	指向文件中开始读取的偏移量的指针。除非使用 cuFileStreamRegister API 另行设置，否则此值直到执行时才会求值。
devPtr_offset_p	指向相对于 bufPtr_base 的偏移量指针，从该位置写入。除非使用 cuFileStreamRegister API 另行设置，否则此值直到执行时才会求值。
bytes_written_p	指向写入文件的字节数的指针。此指针应为非 NULL 值，并且 bytes_written_p 应设置为 0。bytes_written_p 内存应使用 cuMemHostAlloc/malloc/mmap 分配或使用 cuMemHostRegister 注册。在流中成功执行操作后，bytes_written_p 的值将包含以下之一：成功读取的字节数。 -1（发生 I/O 错误时）。所有其他错误返回 CUfileOpError 枚举值的负整数值。
stream	将操作排入队列的 CUDA 流。如果为 NULL，则使此操作同步。

◆ write_async() [2/2]

StreamFuture kvikio::FileHandle::write_async	(	void *	devPtr_base,
		std::size_t	size,
		off_t	file_offset = `0`,
		off_t	devPtr_offset = `0`,
		CUstream	stream = `nullptr`
	)

异步地将设备内存中指定的字节写入文件。

这是 .write() 的异步版本，将在指定流中按顺序执行。

在运行 CUDA v12.1 或更早版本时，此函数会在 stream 同步后回退使用 .read()。

这些参数的含义与 .write() 中相同，但返回一个 StreamFuture 对象，调用者必须使其保持活动状态，直到所有数据写入磁盘。一种方法是调用 StreamFuture.check_bytes_done()，它将同步关联的流并返回写入的字节数。

参数

devPtr_base	设备内存中缓冲区的基地址。对于注册的缓冲区，`devPtr_base` 必须保持设置为 `buffer_register` 调用中使用的基地址。
size	要写入的字节大小。
file_offset	文件中的写入偏移量。
devPtr_offset	相对于 `devPtr_base` 指针的写入偏移量。此参数仅应与注册的缓冲区一起使用。
stream	将操作排入队列的 CUDA 流。如果为 NULL，则使此操作同步。

返回值: 必须保持活动状态的 future 对象，直到所有数据已写入磁盘，例如通过同步 stream。

本类的文档生成自以下文件

file_handle.hpp

公共成员函数

公共静态属性

友元

详细描述

构造函数与析构函数文档

◆ FileHandle()

成员函数文档

◆ closed()

◆ fd()

◆ fd_open_flags()

◆ get_compat_mode_manager()

◆ handle()

◆ nbytes()

◆ pread()

◆ pwrite()

◆ read()

◆ read_async() [1/2]

◆ read_async() [2/2]

◆ write()

◆ write_async() [1/2]

◆ write_async() [2/2]