Mio, a header-only C++11 memory mapping library, released!

3 min read

Mio, a cross-platform header-only C++11 memory mapping library with an MIT license, got released yesterday.

Mio has been created with an objective of getting easily integrated into any C++ project. It uses a memory-mapped file IO without the need to pull in Boost libraries.

The users faced issues with the Boost.Iostreams library as it didn’t work efficiently with respect to memory mapping. However, Mio has a lot of advantages over Boost.Iostreams.

Advantages of Mio over Boost.Iostreams

With Mio, the support for establishing a memory mapping with an already open file handle/descriptor became possible, which otherwise didn’t work with the Boost.Iostreams.

Mio makes the memory mapping process easier by accepting any offset and finding the nearest page boundary. Whereas, Boost.Iostreams requires the user to pick offsets exactly at page boundaries, which may lead to errors.

Boost.Iostreams implements a memory mapped file IO with a std::shared_ptr to provide shared semantics, even when it is not needed. This may lead to an overhead of the heap allocation, which may not be required. On the other hand, Mio solves this problem with its two use-cases, one that is move-only, which is a zero-cost abstraction over the system specific mapping functions and the other one which is similar to its Boost.Iostreams counterpart, with shared semantics.

How does the memory mapping in Mio work?

The three ways to map a file into memory are:

  1. Use the constructor, which throws on failure:
mio::mmap_source mmap(path, offset, size_to_map
  1. Use the factory function:
std::error_code error;
mio::mmap_source mmap = mio::make_mmap_source(path, offset, size_to_map, error);
  1. Use the map member function:
std::error_code error;
mio::mmap_source mmap;
mmap.map(path, offset, size_to_map, error);

In each of the cases, you can either provide some string type for the file’s path or you can simply use an existing, valid file handle.

Mio does not check if the provided file descriptor has the same access permissions as the desired mapping, so the mapping process might fail. Such errors are reported via the std::error_code out parameter which is passed to the mapping function.

CMake: A build system to help Mio

As Mio is a header-only library, it has no compiled components. CMake build system assists Mio, by providing easy testing, installation, and subproject composition on many platforms and operating systems.

In Testing

When Mio is configured as the highest level CMake project, the suite of executables is built by default. Mio’s test executables are integrated with the CMake test driver program, CTest.

In Installation

The CMake’s find package intrinsic function helps Mio’s build system to provide an installation target and support for downstream consumption to an arbitrary location. This can be specified by defining CMAKE_INSTALL_PREFIX at the time of configuration.  CMake will install Mio to conventional location based on the platform operating system in the absence of a user specification.

Read more about Mio, in detail on the official GitHub page.

Read Next

Google releases Oboe, a C++ library to build high-performance Android audio apps

Graph Nets – DeepMind’s library for graph networks in Tensorflow and Sonnet

Ebiten 1.8, a 2D game library in Go, is here with experimental WebAssembly support and newly added APIs