Libosmium  2.10.3
Fast and flexible C++ library for working with OpenStreetMap data
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
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:
Inheritance graph
[legend]

Public Types

enum  mapping_mode { mapping_mode::readonly = 0, mapping_mode::write_private = 1, mapping_mode::write_shared = 2 }
 

Public Member Functions

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

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)
 

Static Private Member Functions

static size_t check_size (size_t size)
 

Private Attributes

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(...);
{
// 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

Member Enumeration Documentation

Enumerator
readonly 
write_private 
write_shared 

Constructor & Destructor Documentation

osmium::util::MemoryMapping::MemoryMapping ( 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
sizeSize of the mapping in bytes
modeMapping mode: readonly, or writable (shared or private)
fdOpen file descriptor of a file we want to map
offsetOffset into the file where the mapping should start
Exceptions
std::system_errorif the mapping fails
OSMIUM_DEPRECATED osmium::util::MemoryMapping::MemoryMapping ( size_t  size,
bool  writable = true,
int  fd = -1,
off_t  offset = 0 
)
inline
Deprecated:
For backwards compatibility only. Use the constructor taking a mapping_mode as second argument instead.
osmium::util::MemoryMapping::MemoryMapping ( const MemoryMapping )
delete

You can not copy construct a MemoryMapping.

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

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

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

static size_t osmium::util::MemoryMapping::check_size ( size_t  size)
inlinestaticprivate
int osmium::util::MemoryMapping::fd ( ) const
inlinenoexcept

The file descriptor this mapping was created from.

Returns
file descriptor, -1 for anonymous mappings
template<typename T = void>
T* osmium::util::MemoryMapping::get_addr ( ) const
inline

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

Exceptions
std::runtime_errorif the mapping is invalid
int osmium::util::MemoryMapping::get_flags ( ) const
inlineprivatenoexcept
int osmium::util::MemoryMapping::get_protection ( ) const
inlineprivatenoexcept
bool osmium::util::MemoryMapping::is_valid ( ) const
inlineprivatenoexcept
void osmium::util::MemoryMapping::make_invalid ( )
inlineprivatenoexcept
osmium::util::MemoryMapping::operator bool ( ) const
inlineexplicitnoexcept

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

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

You can not copy a MemoryMapping.

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

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

void osmium::util::MemoryMapping::resize ( 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_sizeNumber of bytes to resize to (must be > 0).
Exceptions
std::system_errorif the remapping fails.
int osmium::util::MemoryMapping::resize_fd ( int  fd)
inlineprivate
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.

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

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

Exceptions
std::system_errorif the unmapping fails
bool osmium::util::MemoryMapping::writable ( ) const
inlinenoexcept

Was this mapping created as a writable mapping?

Member Data Documentation

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

The address where the memory is mapped.

int osmium::util::MemoryMapping::m_fd
private

File handle we got the mapping from.

mapping_mode osmium::util::MemoryMapping::m_mapping_mode
private

Mapping mode.

off_t osmium::util::MemoryMapping::m_offset
private

Offset into the file.

size_t osmium::util::MemoryMapping::m_size
private

The size of the mapping.


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