diff --git a/README.md b/README.md index 717a0d7..cfad9c9 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,16 @@ It has been created with the goal to be easily includable in any C++ project tha Please feel free to open an issue, I'll try to address any concerns as best I can. -## Example -There are three ways to a create a mapping: +### Why? +mio has been created with the goal to be easily includable (i.e. no dependencies) in any C++ project that needs memory mapped file IO without the need to pull in Boost. + +The primary motivation for writing this library instead of using Boost.Iostreams, was the lack of support for establishing a memory mapping with an already open file handle/descriptor. This is possible with mio. + +Albeit a minor nitpick, Boost.Iostreams implements memory mapped file IO with a `std::shared_ptr` to provide shared semantics, even if not needed, and the overhead of the heap allocation may be unnecessary and/or unwanted. +In mio, there are two classes to cover the two use-cases: one that is move-only (basically a zero-cost abstraction over the system specific mmapping functions), and the other that acts just like its Boost.Iostreams counterpart, with shared semantics. + +### How to create a mapping +There are three ways to do that: - Using the constructor, which throws on failure: ```c++ @@ -43,7 +51,7 @@ int main() ``` However, mio does not check whether the provided file descriptor has the same access permissions as the desired mapping, so the mapping may fail. -General usage: +### Example ```c++ #include #include // for std::error_code @@ -128,5 +136,5 @@ using mmap_sink = mio::basic_mmap_sink; You can query the underlying system's page allocation granularity by invoking `mio::page_size()`, which is located in `mio/page.hpp`. -## Installation +### Installation mio is a header-only library, so just copy the contents in `mio/include` into your system wide include path, such as `/usr/include`, or into your project's lib folder.