You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>Albeit a minor nitpick, Boost.Iostreams implements memory mapped file IO with a <spanclass="tt">std::shared_ptr</span> 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.</p>
<p>Note : the file must exist before creating a mapping. </p>
141
-
</blockquote>
142
-
</blockquote>
138
+
<dlclass="section note"><dt>Note</dt><dd>The file must exist before creating a mapping.</dd></dl>
143
139
<p>There are three ways to map a file into memory:</p>
144
140
<ul>
145
141
<li>Using the constructor, which throws a <spanclass="tt">std::system_error</span> on failure: <divclass="fragment"><divclass="line"><aclass="code hl_typedef" href="namespacemio.html#a16e95fe46bbad947821a1c4d58c80b84">mio::mmap_source</a> mmap(path, offset, size_to_map);</div>
</div><!-- fragment --> or: <divclass="fragment"><divclass="line">mmap.<aclass="code hl_function" href="structmio_1_1basic__mmap.html#a0e0448c6898bfe229e5f6f7f83d9536f">map</a>(path, error);</div>
159
-
</div><!-- fragment --><blockquoteclass="doxtable">
160
-
<blockquoteclass="doxtable">
161
-
<p><b>Note:</b> The constructors <b>require</b> exceptions to be enabled. If you prefer to build your projects with <spanclass="tt">-fno-exceptions</span>, you can still use the other ways. </p>
162
-
</blockquote>
163
-
</blockquote>
164
-
</li>
155
+
</div><!-- fragment --><dlclass="section note"><dt>Note</dt><dd>The constructors <b>require</b> exceptions to be enabled. If you prefer to build your projects with <spanclass="tt">-fno-exceptions</span>, you can still use the other ways.</dd></dl>
156
+
Moreover, in each case, you can provide either some string type for the file's path, or you can use an existing, valid file handle.</li>
165
157
</ul>
166
-
<p>Moreover, in each case, you can provide either some string type for the file's path, or you can use an existing, valid file handle.</p>
</div><!-- fragment --><p> However, mio does not check whether the provided file descriptor has the same access permissions as the desired mapping, so the mapping may fail. Such errors are reported via the <spanclass="tt">std::error_code</span> out parameter that is passed to the mapping function.</p>
184
-
<p><b>WINDOWS USERS</b>: This library <em>does</em> support the use of wide character types for functions where character strings are expected (e.g. path parameters).</p>
169
+
<dlclass="section note"><dt>Note</dt><dd><b>WINDOWS USERS</b>: This library <em>does</em> support the use of wide character types for functions where character strings are expected (e.g. path parameters).</dd></dl>
</div><!-- fragment --><p><spanclass="tt"><aclass="el" href="structmio_1_1basic__mmap.html">mio::basic_mmap</a></span> is move-only, but if multiple copies to the same mapping are needed, use <spanclass="tt"><aclass="el" href="classmio_1_1basic__shared__mmap.html">mio::basic_shared_mmap</a></span> which has <spanclass="tt">std::shared_ptr</span> semantics and has the same interface as <spanclass="tt"><aclass="el" href="structmio_1_1basic__mmap.html">mio::basic_mmap</a></span>. </p><divclass="fragment"><divclass="line"><spanclass="preprocessor">#include <<aclass="code" href="shared__mmap_8hpp.html">mio/shared_mmap.hpp</a>></span></div>
248
+
</div><!-- fragment --><p><spanclass="tt"><aclass="el" href="structmio_1_1basic__mmap.html">mio::basic_mmap</a></span> is move-only, but if multiple copies to the same mapping are needed, use <spanclass="tt"><aclass="el" href="classmio_1_1basic__shared__mmap.html">mio::basic_shared_mmap</a></span> which has <spanclass="tt">std::shared_ptr</span> semantics and has the same interface as <spanclass="tt"><aclass="el" href="structmio_1_1basic__mmap.html">mio::basic_mmap</a></span>. </p><divclass="fragment"><divclass="line"><spanclass="preprocessor">#include <mio/mio.hpp></span></div>
<divclass="line"><aclass="code hl_typedef" href="namespacemio.html#abfdbe8a7a9bad7666e05cb2f774df6fd">mio::shared_mmap_source</a> shared_mmap2(std::move(mmap1)); <spanclass="comment">// or use operator=</span></div>
</div><!-- fragment --><p>It's possible to define the type of a byte (which has to be the same width as <spanclass="tt">char</span>), though aliases for the most common ones are provided by default: </p><divclass="fragment"><divclass="line"><spanclass="keyword">using </span>mmap_source = basic_mmap_source<char>;</div>
</div><!-- fragment --><p>Though generally not needed, since mio maps users requested offsets to page boundaries, you can query the underlying system's page allocation granularity by invoking <spanclass="tt"><aclass="el" href="namespacemio.html#a5fa19e76f930339fbeb51ad691b0bfd3">mio::page_size()</a></span>, which is located in <spanclass="tt"><aclass="el" href="page_8hpp.html">mio/page.hpp</a></span>.</p>
<p>Mio can be added to your project as a single header file simply by including <spanclass="tt">\single_include\<aclass="el" href="namespacemio.html">mio</a>\<aclass="el" href="mio_8hpp.html">mio.hpp</a></span>. Single header files can be regenerated at any time by running the <spanclass="tt">amalgamate.py</span> script within <spanclass="tt">\third_party</span>. <br/>
<p>Mio can be added to your project as a single header file simply by including <ahref="/single_include/mio/mio.hpp">mio.hpp</a>. Single header files can be regenerated at any time by running the <ahref="third_party/amalgamate/amalgamate.py">amalgamate.py</a> script within <ahref="/third_party/">\third_party</a> directory.</p>
</div><!-- fragment --><h2class="doxsection"><aclass="anchor" id="autotoc_md5"></a>
290
272
CMake</h2>
291
273
<p>As a header-only library, mio has no compiled components. Nevertheless, a <ahref="https://cmake.org/overview/">CMake</a> build system is provided to allow easy testing, installation, and subproject composition on many platforms and operating systems.</p>
<divclass="line">target_link_libraries( MyTarget PUBLIC mio::mio )</div>
364
-
</div><!-- fragment --><p><b>WINDOWS USERS</b>: The <spanclass="tt">mio::mio</span> target <spanclass="tt">#define</span>s <spanclass="tt">WIN32_LEAN_AND_MEAN</span> and <spanclass="tt">NOMINMAX</span>. The former ensures the imported surface area of the Win API is minimal, and the latter disables Windows' <spanclass="tt">min</span> and <spanclass="tt">max</span> macros so they don't intefere with <spanclass="tt">std::min</span> and <spanclass="tt">std::max</span>. Because <em>mio</em> is a header only library, these defintions will leak into downstream CMake builds. If their presence is causing problems with your build then you can use the alternative <spanclass="tt">mio::mio_full_winapi</span> target, which adds none of these defintions.</p>
346
+
</div><!-- fragment --><dlclass="section note"><dt>Note</dt><dd><b>WINDOWS USERS</b>: The <spanclass="tt">mio::mio</span> target <spanclass="tt">#define</span>s <spanclass="tt">WIN32_LEAN_AND_MEAN</span> and <spanclass="tt">NOMINMAX</span>. The former ensures the imported surface area of the Win API is minimal, and the latter disables Windows' <spanclass="tt">min</span> and <spanclass="tt">max</span> macros so they don't intefere with <spanclass="tt">std::min</span> and <spanclass="tt">std::max</span>. Because <em>mio</em> is a header only library, these defintions will leak into downstream CMake builds. If their presence is causing problems with your build then you can use the alternative <spanclass="tt">mio::mio_full_winapi</span> target, which adds none of these defintions.</dd></dl>
365
347
<p>If mio was installed to a non-conventional location, it may be necessary for downstream projects to specify the mio installation root directory via either</p>
0 commit comments