Libosmium: osmium::util::MemoryMapping Class Reference

Libosmium Fast and flexible C++ library for working with OpenStreetMap data

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Private Types | Private Member Functions | Static Private Member Functions | Private Attributes | List of all members
osmium::util::MemoryMapping Class Reference

`#include <memory_mapping.hpp>`

Inheritance diagram for osmium::util::MemoryMapping:
[legend]

## 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.
MemoryMapping & | operator= (const MemoryMapping &)=delete
| You can not copy a MemoryMapping.
| 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.
off_t | m_offset
| Offset into the file.
int | m_fd
| File handle we got the mapping from.
mapping_mode | m_mapping_mode
| Mapping mode.
void * | m_addr
| The address where the memory is mapped.

## 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)
osmium::util::MemoryMapping::unmap
void unmap()
Definition memory_mapping.hpp:607
osmium::util::MemoryMapping::get_addr
T * get_addr() const noexcept
Definition memory_mapping.hpp:296
osmium::util::MemoryMapping::MemoryMapping
MemoryMapping(std::size_t size, mapping_mode mode, int fd=-1, off_t offset=0)
Definition memory_mapping.hpp:570

Or for file-backed mapping:

int fd = ::open(...);
{
MemoryMapping mapping{1024, MemoryMapping::mapping_mode::write_shared, fd, offset};
// use mapping
}
::close(fd);
osmium::util::MemoryMapping::mapping_mode::write_shared
@ write_shared
Definition memory_mapping.hpp:102
osmium::util::MemoryMapping::fd
int fd() const noexcept
Definition memory_mapping.hpp:279

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
  osmium::util::MemoryMapping::size
  std::size_t size() const noexcept
  Definition memory_mapping.hpp:270
  or
  mode == write_shared || mode == write_private
  osmium::util::MemoryMapping::mapping_mode::write_private
  @ write_private
  Definition memory_mapping.hpp:101

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

std::size_t osmium::util::MemoryMapping::available_space | ( | int | fd | ) |
| inlinestaticprivate

## ◆ check_size()

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