diff options
Diffstat (limited to 'classllfio__v2__xxx_1_1map__handle.html')
| -rw-r--r-- | classllfio__v2__xxx_1_1map__handle.html | 22 |
1 files changed, 15 insertions, 7 deletions
diff --git a/classllfio__v2__xxx_1_1map__handle.html b/classllfio__v2__xxx_1_1map__handle.html index 2afc22f7..41d1d3ec 100644 --- a/classllfio__v2__xxx_1_1map__handle.html +++ b/classllfio__v2__xxx_1_1map__handle.html @@ -234,6 +234,10 @@ byte * </td><td class="memItemRight" valign="bottom"><a class="el" href="cl <a class="el" href="classllfio__v2__xxx_1_1handle.html#aed9587571c3fb932adadddc1beeeed58">size_type</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classllfio__v2__xxx_1_1map__handle.html#ad2fce2bd5cd3798196c0dcf87f569ef7">length</a> () const noexcept</td></tr> <tr class="memdesc:ad2fce2bd5cd3798196c0dcf87f569ef7"><td class="mdescLeft"> </td><td class="mdescRight">The size of the memory map. This is the accessible size, NOT the reservation size. <br /></td></tr> <tr class="separator:ad2fce2bd5cd3798196c0dcf87f569ef7"><td class="memSeparator" colspan="2"> </td></tr> +<tr class="memitem:a7224b586e457183ebcb0a694e282d0fc"><td class="memItemLeft" align="right" valign="top"><a id="a7224b586e457183ebcb0a694e282d0fc"></a> +<a class="el" href="classllfio__v2__xxx_1_1handle.html#aed9587571c3fb932adadddc1beeeed58">size_type</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classllfio__v2__xxx_1_1map__handle.html#a7224b586e457183ebcb0a694e282d0fc">page_size</a> () const noexcept</td></tr> +<tr class="memdesc:a7224b586e457183ebcb0a694e282d0fc"><td class="mdescLeft"> </td><td class="mdescRight">The page size used by the map, in bytes. <br /></td></tr> +<tr class="separator:a7224b586e457183ebcb0a694e282d0fc"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a77452c0f4be2e1c9cdda5a59512b1887"><td class="memItemLeft" align="right" valign="top"><a id="a77452c0f4be2e1c9cdda5a59512b1887"></a> bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classllfio__v2__xxx_1_1map__handle.html#a77452c0f4be2e1c9cdda5a59512b1887">is_nvram</a> () const noexcept</td></tr> <tr class="memdesc:a77452c0f4be2e1c9cdda5a59512b1887"><td class="mdescLeft"> </td><td class="mdescRight">True if the map is of non-volatile RAM. <br /></td></tr> @@ -246,11 +250,11 @@ result< <a class="el" href="classllfio__v2__xxx_1_1handle.html#aed9587571c3fb <tr class="separator:a1fb1c874bdab5540c3310e468e41325a"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a9b3f12d17a9fc0cfbe15d389f896caa7"><td class="memItemLeft" align="right" valign="top"><a id="a9b3f12d17a9fc0cfbe15d389f896caa7"></a> result< <a class="el" href="structllfio__v2__xxx_1_1io__handle_1_1buffer__type.html">buffer_type</a> > </td><td class="memItemRight" valign="bottom"><a class="el" href="classllfio__v2__xxx_1_1map__handle.html#a9b3f12d17a9fc0cfbe15d389f896caa7">commit</a> (<a class="el" href="structllfio__v2__xxx_1_1io__handle_1_1buffer__type.html">buffer_type</a> region, section_handle::flag flag=section_handle::flag::readwrite) noexcept</td></tr> -<tr class="memdesc:a9b3f12d17a9fc0cfbe15d389f896caa7"><td class="mdescLeft"> </td><td class="mdescRight">Ask the system to commit the system resources to make the memory represented by the buffer available with the given permissions. addr and length should be page aligned (see utils::page_sizes()), if not the returned buffer is the region actually committed. <br /></td></tr> +<tr class="memdesc:a9b3f12d17a9fc0cfbe15d389f896caa7"><td class="mdescLeft"> </td><td class="mdescRight">Ask the system to commit the system resources to make the memory represented by the buffer available with the given permissions. addr and length should be page aligned (see <code>page_size()</code>), if not the returned buffer is the region actually committed. <br /></td></tr> <tr class="separator:a9b3f12d17a9fc0cfbe15d389f896caa7"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a518ff43602ac8e32ae48a198d0de1d75"><td class="memItemLeft" align="right" valign="top"><a id="a518ff43602ac8e32ae48a198d0de1d75"></a> result< <a class="el" href="structllfio__v2__xxx_1_1io__handle_1_1buffer__type.html">buffer_type</a> > </td><td class="memItemRight" valign="bottom"><a class="el" href="classllfio__v2__xxx_1_1map__handle.html#a518ff43602ac8e32ae48a198d0de1d75">decommit</a> (<a class="el" href="structllfio__v2__xxx_1_1io__handle_1_1buffer__type.html">buffer_type</a> region) noexcept</td></tr> -<tr class="memdesc:a518ff43602ac8e32ae48a198d0de1d75"><td class="mdescLeft"> </td><td class="mdescRight">Ask the system to make the memory represented by the buffer unavailable and to decommit the system resources representing them. addr and length should be page aligned (see utils::page_sizes()), if not the returned buffer is the region actually decommitted. <br /></td></tr> +<tr class="memdesc:a518ff43602ac8e32ae48a198d0de1d75"><td class="mdescLeft"> </td><td class="mdescRight">Ask the system to make the memory represented by the buffer unavailable and to decommit the system resources representing them. addr and length should be page aligned (see <code>page_size()</code>), if not the returned buffer is the region actually decommitted. <br /></td></tr> <tr class="separator:a518ff43602ac8e32ae48a198d0de1d75"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a0b87515430eb0220950b4c17a3da745f"><td class="memItemLeft" align="right" valign="top">result< void > </td><td class="memItemRight" valign="bottom"><a class="el" href="classllfio__v2__xxx_1_1map__handle.html#a0b87515430eb0220950b4c17a3da745f">zero_memory</a> (<a class="el" href="structllfio__v2__xxx_1_1io__handle_1_1buffer__type.html">buffer_type</a> region) noexcept</td></tr> <tr class="separator:a0b87515430eb0220950b4c17a3da745f"><td class="memSeparator" colspan="2"> </td></tr> @@ -415,6 +419,9 @@ byte * </td><td class="memItemRight" valign="bottom"><b>_addr</b> {nullptr} <tr class="memitem:a67fb29deeca27a58ca3d78c792ca5435"><td class="memItemLeft" align="right" valign="top"><a id="a67fb29deeca27a58ca3d78c792ca5435"></a> <a class="el" href="classllfio__v2__xxx_1_1handle.html#aed9587571c3fb932adadddc1beeeed58">size_type</a> </td><td class="memItemRight" valign="bottom"><b>_length</b> {0}</td></tr> <tr class="separator:a67fb29deeca27a58ca3d78c792ca5435"><td class="memSeparator" colspan="2"> </td></tr> +<tr class="memitem:ae44bc69b964c2140a3bab80dd8aed205"><td class="memItemLeft" align="right" valign="top"><a id="ae44bc69b964c2140a3bab80dd8aed205"></a> +<a class="el" href="classllfio__v2__xxx_1_1handle.html#aed9587571c3fb932adadddc1beeeed58">size_type</a> </td><td class="memItemRight" valign="bottom"><b>_pagesize</b> {0}</td></tr> +<tr class="separator:ae44bc69b964c2140a3bab80dd8aed205"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a68216d4c582fc817fa86229dce397146"><td class="memItemLeft" align="right" valign="top"><a id="a68216d4c582fc817fa86229dce397146"></a> section_handle::flag </td><td class="memItemRight" valign="bottom"><b>_flag</b> {section_handle::flag::none}</td></tr> <tr class="separator:a68216d4c582fc817fa86229dce397146"><td class="memSeparator" colspan="2"> </td></tr> @@ -439,6 +446,7 @@ class </td><td class="memItemRight" valign="bottom"><b>mapped_file_handle</ <p>An important concept to realise with mapped regions is that they can far exceed the size of their backing storage. This allows one to reserve address space for a file which may grow in the future. This is how <code>mapped_file_handle</code> is implemented to provide very fast memory mapped file i/o of a potentially growing file.</p> <p>The size you specify when creating the map handle is the address space reservation. The map's <code>length()</code> will return the last known <b>valid</b> length of the mapped data i.e. the backing storage's length at the time of construction. This length is used by <code>read()</code> and <code>write()</code> to prevent reading and writing off the end of the mapped region. You can update this length to the backing storage's length using <code>update_map()</code> up to the reservation limit.</p> <p>You can attempt to modify the address space reservation after creation using <code>truncate()</code>. If successful, this will be more efficient than tearing down the map and creating a new larger map.</p> +<dl class="section note"><dt>Note</dt><dd>On Microsoft Windows, it is not permitted to reserve address space using large pages. Any attempt to do so will fail. Note also that on that kernel, you must have granted the ability to lock memory to the user or users running the process for large page support to be made available to that process and user. Finally, as of Windows 10 1803, using large pages in file backed memory maps is not supported. If a future kernel changes this, the existing code should "just work".</dd></dl> <p>The native handle returned by this map handle is always that of the backing storage, but closing this handle does not close that of the backing storage, nor does releasing this handle release that of the backing storage. Locking byte ranges of this handle is therefore equal to locking byte ranges in the original backing storage, which can be very useful.</p> <h2>Barriers:</h2> <p><code>map_handle</code>, because it implements <code>io_handle</code>, implements <code>barrier()</code> in a very conservative way to account for OS differences i.e. it calls <code>msync()</code>, and then the <code>barrier()</code> implementation for the backing file (probably <code>fsync()</code> or equivalent on most platforms, which synchronises the entire file).</p> @@ -555,7 +563,7 @@ class </td><td class="memItemRight" valign="bottom"><b>mapped_file_handle</ </dd> </dl> <p>Upon return, one knows that memory in the returned buffer has been barriered (it may be empty if there is no support for this operation in LLFIO, or if the current CPU does not support this operation). You may find the <code>is_nvram()</code> observer of particular use here. </p> -<div class="fragment"><div class="line"><a name="l00364"></a><span class="lineno"> 364</span>  {</div><div class="line"><a name="l00365"></a><span class="lineno"> 365</span>  <span class="keyword">auto</span> *tp = (<a class="code" href="structllfio__v2__xxx_1_1io__handle_1_1const__buffer__type.html#a56b1347a75286b1b21af8082faacabb7">const_buffer_type::pointer</a>)(((uintptr_t) req.data()) & 31);</div><div class="line"><a name="l00366"></a><span class="lineno"> 366</span>  const_buffer_type ret{tp, (size_t)(req.data() + req.size() - tp)};</div><div class="line"><a name="l00367"></a><span class="lineno"> 367</span>  <span class="keywordflow">for</span>(<a class="code" href="structllfio__v2__xxx_1_1io__handle_1_1const__buffer__type.html#a56b1347a75286b1b21af8082faacabb7">const_buffer_type::pointer</a> addr = ret.data(); addr < ret.data() + ret.size(); addr += 32)</div><div class="line"><a name="l00368"></a><span class="lineno"> 368</span>  {</div><div class="line"><a name="l00369"></a><span class="lineno"> 369</span>  <span class="comment">// Slightly UB ...</span></div><div class="line"><a name="l00370"></a><span class="lineno"> 370</span>  <span class="keyword">auto</span> *p = <span class="keyword">reinterpret_cast<</span><span class="keyword">const </span>persistent<byte> *<span class="keyword">></span>(addr);</div><div class="line"><a name="l00371"></a><span class="lineno"> 371</span>  <span class="keywordflow">if</span>(memory_flush_none == p->flush(evict ? memory_flush_evict : memory_flush_retain))</div><div class="line"><a name="l00372"></a><span class="lineno"> 372</span>  {</div><div class="line"><a name="l00373"></a><span class="lineno"> 373</span>  ret = {tp, 0};</div><div class="line"><a name="l00374"></a><span class="lineno"> 374</span>  <span class="keywordflow">break</span>;</div><div class="line"><a name="l00375"></a><span class="lineno"> 375</span>  }</div><div class="line"><a name="l00376"></a><span class="lineno"> 376</span>  }</div><div class="line"><a name="l00377"></a><span class="lineno"> 377</span>  <span class="keywordflow">return</span> ret;</div><div class="line"><a name="l00378"></a><span class="lineno"> 378</span>  }</div><div class="ttc" id="structllfio__v2__xxx_1_1io__handle_1_1const__buffer__type_html_a56b1347a75286b1b21af8082faacabb7"><div class="ttname"><a href="structllfio__v2__xxx_1_1io__handle_1_1const__buffer__type.html#a56b1347a75286b1b21af8082faacabb7">llfio_v2_xxx::io_handle::const_buffer_type::pointer</a></div><div class="ttdeci">const byte * pointer</div><div class="ttdoc">Type of the pointer to memory. </div><div class="ttdef"><b>Definition:</b> io_handle.hpp:109</div></div> +<div class="fragment"><div class="line"><a name="l00387"></a><span class="lineno"> 387</span>  {</div><div class="line"><a name="l00388"></a><span class="lineno"> 388</span>  <span class="keyword">auto</span> *tp = (<a class="code" href="structllfio__v2__xxx_1_1io__handle_1_1const__buffer__type.html#a56b1347a75286b1b21af8082faacabb7">const_buffer_type::pointer</a>)(((uintptr_t) req.data()) & 31);</div><div class="line"><a name="l00389"></a><span class="lineno"> 389</span>  const_buffer_type ret{tp, (size_t)(req.data() + req.size() - tp)};</div><div class="line"><a name="l00390"></a><span class="lineno"> 390</span>  <span class="keywordflow">for</span>(<a class="code" href="structllfio__v2__xxx_1_1io__handle_1_1const__buffer__type.html#a56b1347a75286b1b21af8082faacabb7">const_buffer_type::pointer</a> addr = ret.data(); addr < ret.data() + ret.size(); addr += 32)</div><div class="line"><a name="l00391"></a><span class="lineno"> 391</span>  {</div><div class="line"><a name="l00392"></a><span class="lineno"> 392</span>  <span class="comment">// Slightly UB ...</span></div><div class="line"><a name="l00393"></a><span class="lineno"> 393</span>  <span class="keyword">auto</span> *p = <span class="keyword">reinterpret_cast<</span><span class="keyword">const </span>persistent<byte> *<span class="keyword">></span>(addr);</div><div class="line"><a name="l00394"></a><span class="lineno"> 394</span>  <span class="keywordflow">if</span>(memory_flush_none == p->flush(evict ? memory_flush_evict : memory_flush_retain))</div><div class="line"><a name="l00395"></a><span class="lineno"> 395</span>  {</div><div class="line"><a name="l00396"></a><span class="lineno"> 396</span>  ret = {tp, 0};</div><div class="line"><a name="l00397"></a><span class="lineno"> 397</span>  <span class="keywordflow">break</span>;</div><div class="line"><a name="l00398"></a><span class="lineno"> 398</span>  }</div><div class="line"><a name="l00399"></a><span class="lineno"> 399</span>  }</div><div class="line"><a name="l00400"></a><span class="lineno"> 400</span>  <span class="keywordflow">return</span> ret;</div><div class="line"><a name="l00401"></a><span class="lineno"> 401</span>  }</div><div class="ttc" id="structllfio__v2__xxx_1_1io__handle_1_1const__buffer__type_html_a56b1347a75286b1b21af8082faacabb7"><div class="ttname"><a href="structllfio__v2__xxx_1_1io__handle_1_1const__buffer__type.html#a56b1347a75286b1b21af8082faacabb7">llfio_v2_xxx::io_handle::const_buffer_type::pointer</a></div><div class="ttdeci">const byte * pointer</div><div class="ttdoc">Type of the pointer to memory. </div><div class="ttdef"><b>Definition:</b> io_handle.hpp:109</div></div> </div><!-- fragment --> </div> </div> @@ -709,7 +717,7 @@ For portability, you can only assume that barriers write order for a single hand </tr> </table> </div><div class="memdoc"> -<p>Ask the system to unset the dirty flag for the memory represented by the buffer. This will prevent any changes not yet sent to the backing storage from being sent in the future, also if the system kicks out this page and reloads it you may see some edition of the underlying storage instead of what was here. addr and length should be page aligned (see utils::page_sizes()), if not the returned buffer is the region actually undirtied.</p> +<p>Ask the system to unset the dirty flag for the memory represented by the buffer. This will prevent any changes not yet sent to the backing storage from being sent in the future, also if the system kicks out this page and reloads it you may see some edition of the underlying storage instead of what was here. <code>addr</code> and <code>length</code> should be page aligned (see<code>page_size()</code>), if not the returned buffer is the region actually undirtied.</p> <dl class="section warning"><dt>Warning</dt><dd>This function destroys the contents of unwritten pages in the region in a totally unpredictable fashion. Only use it if you don't care how much of the region reaches physical storage or not. Note that the region is not necessarily zeroed, and may be randomly zeroed.</dd></dl> <dl class="section note"><dt>Note</dt><dd>Microsoft Windows does not support unsetting the dirty flag on file backed maps, so on Windows this call does nothing. </dd></dl> @@ -900,7 +908,7 @@ For portability, you can only assume that barriers write order for a single hand </div><div class="memdoc"> <p>Map unused memory into view, creating new memory if insufficient unused memory is available. Note that the memory mapped by this call may contain non-zero bits (recycled memory) unless <code>zeroed</code> is true. </p><dl class="params"><dt>Parameters</dt><dd> <table class="params"> - <tr><td class="paramname">bytes</td><td>How many bytes to map. Typically will be rounded up to a multiple of the page size (see <code>utils::page_sizes()</code>) on POSIX, 64Kb on Windows. </td></tr> + <tr><td class="paramname">bytes</td><td>How many bytes to map. Typically will be rounded up to a multiple of the page size (see <code>page_size()</code>). </td></tr> <tr><td class="paramname">zeroed</td><td>Set to true if only all bits zeroed memory is wanted. </td></tr> <tr><td class="paramname">_flag</td><td>The permissions with which to map the view. <code>flag::none</code> can be useful for reserving virtual address space without committing system resources, use commit() to later change availability of memory.</td></tr> </table> @@ -960,7 +968,7 @@ For portability, you can only assume that barriers write order for a single hand <table class="params"> <tr><td class="paramname">section</td><td>A memory section handle specifying the backing storage to use. </td></tr> <tr><td class="paramname">bytes</td><td>How many bytes to reserve (0 = the size of the section). Rounded up to nearest 64Kb on Windows. </td></tr> - <tr><td class="paramname">offset</td><td>The offset into the backing storage to map from. Typically needs to be at least a multiple of the page size (see utils::page_sizes()), on Windows it needs to be a multiple of the kernel memory allocation granularity (typically 64Kb). </td></tr> + <tr><td class="paramname">offset</td><td>The offset into the backing storage to map from. Typically needs to be at least a multiple of the page size (see <code>page_size()</code>), on Windows it needs to be a multiple of the kernel memory allocation granularity (typically 64Kb). </td></tr> <tr><td class="paramname">_flag</td><td>The permissions with which to map the view which are constrained by the permissions of the memory section. <code>flag::none</code> can be useful for reserving virtual address space without committing system resources, use commit() to later change availability of memory.</td></tr> </table> </dd> @@ -1023,7 +1031,7 @@ For portability, you can only assume that barriers write order for a single hand </table> </div><div class="memdoc"> <p>This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. </p> -<div class="fragment"><div class="line"><a name="l00501"></a><span class="lineno"> 501</span>  {</div><div class="line"><a name="l00502"></a><span class="lineno"> 502</span>  OUTCOME_TRY(ret, <a class="code" href="classllfio__v2__xxx_1_1map__handle.html#a25dcce3a7127c5552687c540c37b9f27">prefetch</a>(span<buffer_type>(&region, 1)));</div><div class="line"><a name="l00503"></a><span class="lineno"> 503</span>  <span class="keywordflow">return</span> *ret.data();</div><div class="line"><a name="l00504"></a><span class="lineno"> 504</span>  }</div><div class="ttc" id="classllfio__v2__xxx_1_1map__handle_html_a25dcce3a7127c5552687c540c37b9f27"><div class="ttname"><a href="classllfio__v2__xxx_1_1map__handle.html#a25dcce3a7127c5552687c540c37b9f27">llfio_v2_xxx::map_handle::prefetch</a></div><div class="ttdeci">static result< span< buffer_type > > prefetch(span< buffer_type > regions) noexcept</div><div class="ttdoc">Ask the system to begin to asynchronously prefetch the span of memory regions given, returning the regions actually prefetched. Note that on Windows 7 or earlier the system call to implement this was not available, and so you will see an empty span returned. </div></div> +<div class="fragment"><div class="line"><a name="l00529"></a><span class="lineno"> 529</span>  {</div><div class="line"><a name="l00530"></a><span class="lineno"> 530</span>  OUTCOME_TRY(ret, <a class="code" href="classllfio__v2__xxx_1_1map__handle.html#a25dcce3a7127c5552687c540c37b9f27">prefetch</a>(span<buffer_type>(&region, 1)));</div><div class="line"><a name="l00531"></a><span class="lineno"> 531</span>  <span class="keywordflow">return</span> *ret.data();</div><div class="line"><a name="l00532"></a><span class="lineno"> 532</span>  }</div><div class="ttc" id="classllfio__v2__xxx_1_1map__handle_html_a25dcce3a7127c5552687c540c37b9f27"><div class="ttname"><a href="classllfio__v2__xxx_1_1map__handle.html#a25dcce3a7127c5552687c540c37b9f27">llfio_v2_xxx::map_handle::prefetch</a></div><div class="ttdeci">static result< span< buffer_type > > prefetch(span< buffer_type > regions) noexcept</div><div class="ttdoc">Ask the system to begin to asynchronously prefetch the span of memory regions given, returning the regions actually prefetched. Note that on Windows 7 or earlier the system call to implement this was not available, and so you will see an empty span returned. </div></div> </div><!-- fragment --> </div> </div> |