Merge branch 'master' of https://github.com/mandreyel/mio

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 <mio/mmap.hpp>
 #include <system_error> // for std::error_code
@@ -128,5 +136,5 @@ using mmap_sink = mio::basic_mmap_sink<std::byte>;
 
 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.