kvikio::MmapHandle Class Reference

Handle of a memory-mapped file. More...

#include <mmap.hpp>

Public Member Functions
	MmapHandle () noexcept=default
	Construct an empty memory-mapped file.
	MmapHandle (std::string const &file_path, std::string const &flags="r", std::optional< std::size_t > initial_map_size=std::nullopt, std::size_t initial_map_offset=0, mode_t mode=FileHandle::m644, std::optional< int > map_flags=std::nullopt)
	Construct a new memory-mapped file. More...
	MmapHandle (MmapHandle const &)=delete
MmapHandle &	operator= (MmapHandle const &)=delete
	MmapHandle (MmapHandle &&o) noexcept
MmapHandle &	operator= (MmapHandle &&o) noexcept
std::size_t	initial_map_size () const noexcept
	Size in bytes of the mapped region when the mapping handle was constructed. More...
std::size_t	initial_map_offset () const noexcept
	File offset of the mapped region when the mapping handle was constructed. More...
std::size_t	file_size () const
	Get the file size if the file is open. Returns 0 if the file is closed. More...
std::size_t	nbytes () const
	Alias of file_size More...
bool	closed () const noexcept
	Whether the mapping handle is closed. More...
void	close () noexcept
	Close the mapping handle if it is open; do nothing otherwise.
std::size_t	read (void *buf, std::optional< std::size_t > size=std::nullopt, std::size_t offset=0)
	Sequential read size bytes from the file (with the offset offset) to the destination buffer buf More...
std::future< std::size_t >	pread (void *buf, std::optional< std::size_t > size=std::nullopt, std::size_t offset=0, std::size_t task_size=defaults::task_size())
	Parallel read size bytes from the file (with the offset offset) to the destination buffer buf More...

Detailed Description

Handle of a memory-mapped file.

This utility class facilitates the use of file-backed memory by providing a performant method pread() to read a range of data into user-provided memory residing on the host or device.

File-backed memory can be considered when a large number of nonadjacent file ranges (specified by the offset and size pair) are to be frequently accessed. It can potentially reduce memory usage due to demand paging (compared to reading the entire file with read(2)), and may improve I/O performance compared to frequent calls to read(2).

Definition at line 38 of file mmap.hpp.

Constructor & Destructor Documentation

MmapHandle()

kvikio::MmapHandle::MmapHandle	(	std::string const &	file_path,
		std::string const &	flags = "r",
		std::optional< std::size_t >	initial_map_size = std::nullopt,
		std::size_t	initial_map_offset = 0,
		mode_t	mode = FileHandle::m644,
		std::optional< int >	map_flags = std::nullopt
	)

Construct a new memory-mapped file.

Parameters

file_path	File path
flags	Open flags (see also fopen(3)): "r": "open for reading (default)" "w": "open for writing, truncating the file first" "a": "open for writing, appending to the end of file if it exists" "+": "open for updating (reading and writing)"
initial_map_size	Size in bytes of the mapped region. If not specified, map the region starting from initial_map_offset to the end of file
initial_map_offset	File offset of the mapped region
mode	Access mode
map_flags	Flags to be passed to the system call mmap. See mmap(2) for details

Member Function Documentation

closed()

bool kvikio::MmapHandle::closed ( ) const

noexcept

Whether the mapping handle is closed.

Returns

Boolean answer

file_size()

std::size_t kvikio::MmapHandle::file_size

(

)

const

Get the file size if the file is open. Returns 0 if the file is closed.

The behavior of this method is consistent with FileHandle::nbytes.

Returns

The file size in bytes

initial_map_offset()

std::size_t kvikio::MmapHandle::initial_map_offset ( ) const

noexcept

File offset of the mapped region when the mapping handle was constructed.

Returns

Initial file offset of the mapped region

initial_map_size()

std::size_t kvikio::MmapHandle::initial_map_size ( ) const

noexcept

Size in bytes of the mapped region when the mapping handle was constructed.

Returns

Initial size of the mapped region

nbytes()

std::size_t kvikio::MmapHandle::nbytes

(

)

const

Alias of file_size

Returns

The file size in bytes

pread()

std::future<std::size_t> kvikio::MmapHandle::pread	(	void *	buf,
		std::optional< std::size_t >	size = std::nullopt,
		std::size_t	offset = 0,
		std::size_t	task_size = defaults::task_size()
	)

Parallel read size bytes from the file (with the offset offset) to the destination buffer buf

Parameters

buf	Address of the host or device memory (destination buffer)
size	Size in bytes to read. If not specified, read starts from offset to the end of file
offset	File offset
task_size	Size of each task in bytes

Returns

Future that on completion returns the size of bytes that were successfully read.

Exceptions

std::out_of_range	if the read region specified by offset and size is outside the initial region specified when the mapping handle was constructed
std::invalid_argument	if the size is given but is 0
std::runtime_error	if the mapping handle is closed

Note

The std::future object's wait() or get() should not be called after the lifetime of the MmapHandle object ends. Otherwise, the behavior is undefined.

read()

std::size_t kvikio::MmapHandle::read	(	void *	buf,
		std::optional< std::size_t >	size = std::nullopt,
		std::size_t	offset = 0
	)

Sequential read size bytes from the file (with the offset offset) to the destination buffer buf

Parameters

buf	Address of the host or device memory (destination buffer)
size	Size in bytes to read. If not specified, read starts from offset to the end of file
offset	File offset

Returns

Number of bytes that have been read

Exceptions

std::out_of_range	if the read region specified by offset and size is outside the initial region specified when the mapping handle was constructed
std::invalid_argument	if the size is given but is 0
std::runtime_error	if the mapping handle is closed

---

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

• mmap.hpp