osmium::util::MemoryMapping Class Reference

#include <memory_mapping.hpp>

Inheritance diagram for osmium::util::MemoryMapping:

Public Types
enum class	mapping_mode { readonly = 0 , write_private = 1 , write_shared = 2 }

Public Member Functions
	MemoryMapping (std::size_t size, mapping_mode mode, int fd=-1, off_t offset=0)
	MemoryMapping (const MemoryMapping &)=delete
	You can not copy construct a MemoryMapping. More...
MemoryMapping &	operator= (const MemoryMapping &)=delete
	You can not copy a MemoryMapping. More...
	MemoryMapping (MemoryMapping &&other) noexcept
MemoryMapping &	operator= (MemoryMapping &&other) noexcept
	~MemoryMapping () noexcept
void	unmap ()
void	resize (std::size_t new_size)
	operator bool () const noexcept
std::size_t	size () const noexcept
int	fd () const noexcept
bool	writable () const noexcept
template<typename T = void>
T *	get_addr () const noexcept

Private Types
using	flag_type = int

Private Member Functions
bool	is_valid () const noexcept
void	make_invalid () noexcept
flag_type	get_protection () const noexcept
flag_type	get_flags () const noexcept
int	resize_fd (int fd) const

Static Private Member Functions
static std::size_t	check_size (std::size_t size)
static std::size_t	available_space (int fd)

Private Attributes
std::size_t	m_size
	The size of the mapping. More...
off_t	m_offset
	Offset into the file. More...
int	m_fd
	File handle we got the mapping from. More...
mapping_mode	m_mapping_mode
	Mapping mode. More...
void *	m_addr
	The address where the memory is mapped. More...

Detailed Description

Class for wrapping memory mapping system calls.

Usage for anonymous mapping:

MemoryMapping mapping{1024};          // create anonymous mapping with size
auto ptr = mapping.get_addr<char*>(); // get pointer to memory
mapping.unmap();                      // release mapping by calling unmap() (or at end of scope)

Or for file-backed mapping:

int fd = ::open(...);
{
    MemoryMapping mapping{1024, MemoryMapping::mapping_mode::write_shared, fd, offset};
    // use mapping
}
::close(fd);

If the file backing a file-backed mapping is not large enough, it will be resized. This works, of course, only for writable files, so for read-only files you have to make sure they are large enough for any mapping you want.

If you ask for a zero-sized mapping, a mapping of the systems page size will be created instead. For file-backed mapping this will only work if the file is writable.

There are different implementations for Unix and Windows systems. On Unix systems this wraps the mmap(), munmap(), and the mremap() system calls. On Windows it wraps the CreateFileMapping(), CloseHandle(), MapViewOfFile(), and UnmapViewOfFile() functions.

On Windows the file will be set to binary mode before the memory mapping.

Member Typedef Documentation

flag_type

using osmium::util::MemoryMapping::flag_type = int

private

Member Enumeration Documentation

mapping_mode

enum class osmium::util::MemoryMapping::mapping_mode

strong

Enumerator
readonly
write_private
write_shared

Constructor & Destructor Documentation

MemoryMapping() [1/3]

osmium::util::MemoryMapping::MemoryMapping ( std::size_t  size, mapping_mode  mode, int  fd = -1, off_t  offset = 0  )

inline

Create memory mapping of given size.

If fd is not set (or fd == -1), an anonymous mapping will be created, otherwise a mapping based on the file descriptor will be created.

Precondition

size > 0 

or

mode == write_shared || mode == write_private 

Parameters

size	Size of the mapping in bytes
mode	Mapping mode: readonly, or writable (shared or private)
fd	Open file descriptor of a file we want to map
offset	Offset into the file where the mapping should start

Exceptions

std::system_error

if the mapping fails

MemoryMapping() [2/3]

osmium::util::MemoryMapping::MemoryMapping ( const MemoryMapping &  )

delete

You can not copy construct a MemoryMapping.

MemoryMapping() [3/3]

osmium::util::MemoryMapping::MemoryMapping ( MemoryMapping &&  other )

inlinenoexcept

Move construct a mapping from another one. The other mapping will be marked as invalid.

~MemoryMapping()

osmium::util::MemoryMapping::~MemoryMapping ( )

inlinenoexcept

Releases the mapping by calling unmap(). Will never throw. Call unmap() instead if you want to be notified of any error.

Member Function Documentation

available_space()

static std::size_t osmium::util::MemoryMapping::available_space ( int  fd )

inlinestaticprivate

check_size()

static std::size_t osmium::util::MemoryMapping::check_size ( std::size_t  size )

inlinestaticprivate

fd()

int osmium::util::MemoryMapping::fd ( ) const

inlinenoexcept

The file descriptor this mapping was created from.

Returns

file descriptor, -1 for anonymous mappings

get_addr()

template<typename T = void>

T * osmium::util::MemoryMapping::get_addr ( ) const

inlinenoexcept

Get the address of the mapping as any pointer type you like.

Precondition

is_valid()

get_flags()

int osmium::util::MemoryMapping::get_flags ( ) const

inlineprivatenoexcept

get_protection()

int osmium::util::MemoryMapping::get_protection ( ) const

inlineprivatenoexcept

is_valid()

bool osmium::util::MemoryMapping::is_valid ( ) const

inlineprivatenoexcept

make_invalid()

void osmium::util::MemoryMapping::make_invalid ( )

inlineprivatenoexcept

operator bool()

osmium::util::MemoryMapping::operator bool ( ) const

inlineexplicitnoexcept

In a boolean context a MemoryMapping is true when it is a valid existing mapping.

operator=() [1/2]

MemoryMapping & osmium::util::MemoryMapping::operator= ( const MemoryMapping &  )

delete

You can not copy a MemoryMapping.

operator=() [2/2]

osmium::util::MemoryMapping & osmium::util::MemoryMapping::operator= ( MemoryMapping &&  other )

inlinenoexcept

Move a mapping. The other mapping will be marked as invalid.

resize()

void osmium::util::MemoryMapping::resize ( std::size_t  new_size )

inline

Resize a mapping to the given new size.

On Linux systems this will use the mremap() function. On other systems it will unmap and remap the memory. This can only be done for file-based mappings, not anonymous mappings!

Parameters

new_size

Number of bytes to resize to (must be > 0).

Exceptions

std::system_error

if the remapping fails.

resize_fd()

int osmium::util::MemoryMapping::resize_fd ( int  fd ) const

inlineprivate

size()

std::size_t osmium::util::MemoryMapping::size ( ) const

inlinenoexcept

The number of bytes mapped. This is the same size you created the mapping with. The actual mapping will probably be larger because the system will round it to the page size.

unmap()

void osmium::util::MemoryMapping::unmap ( )

inline

Unmap a mapping. If the mapping is not valid, it will do nothing.

Exceptions

std::system_error

if the unmapping fails

writable()

bool osmium::util::MemoryMapping::writable ( ) const

inlinenoexcept

Was this mapping created as a writable mapping?

Member Data Documentation

m_addr

void* osmium::util::MemoryMapping::m_addr

private

The address where the memory is mapped.

m_fd

int osmium::util::MemoryMapping::m_fd

private

File handle we got the mapping from.

m_mapping_mode

mapping_mode osmium::util::MemoryMapping::m_mapping_mode

private

Mapping mode.

m_offset

off_t osmium::util::MemoryMapping::m_offset

private

Offset into the file.

m_size

std::size_t osmium::util::MemoryMapping::m_size

private

The size of the mapping.

---

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

• include/osmium/util/memory_mapping.hpp