boost_mirror/filesystem
1
0
Fork 0
mirror of https://github.com/boostorg/filesystem.git synced 2025-05-12 13:41:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document the reimplementation of path::codecvt() and path::imbue(), adding a section on path usage concerns.

Browse Source 
[SVN r83062]
This commit is contained in:
Beman Dawes 2013-02-21 14:27:10 +00:00
parent f74de6c268
commit 7f7769d16d
4 changed files with 718 additions and 413 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1066
doc/reference.html
View File

File diff suppressed because it is too large Load Diff

11
doc/release_history.html
View File

@ -36,6 +36,15 @@
</tr>
</table>
<h2>1.54.0</h2>
<ul>
<li>Reimplement <code>path::codecvt()</code> and <code>path::imbue()</code>
with portable code that is intended to be much more robust and maintainable. A
section on <a href="reference.html#path-Usage">path usage concerns</a> has
been added to the reference documentation describing several concerns that
arise in the context of multithreading and <code>path::codecvt()</code>.</li>
</ul>
<h2>1.52.0</h2>
<ul>
<li>Fix <a href="http://svn.boost.org/trac/boost/ticket/7239">#7239</a>, Stack
@ -191,7 +200,7 @@
</ul>
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->28 August, 2012<!--webbot bot="Timestamp" endspan i-checksum="34454" --></p>
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->20 February, 2013<!--webbot bot="Timestamp" endspan i-checksum="40526" --></p>
<p>© Copyright Beman Dawes, 2011</p>
<p> Use, modification, and distribution are subject to the Boost Software
License, Version 1.0. See <a href="http://www.boost.org/LICENSE_1_0.txt">

2
doc/src/build.bat
View File

@ -2,7 +2,9 @@
rem Copyright Beman Dawes 2012
rem Distributed under the Boost Software License, Version 1.0.
del tr2.html 2>nul
echo building tr2.html
mmp TARGET=TR2 source.html tr2.html
del reference.html 2>nul
echo building reference.html
mmp TARGET=BOOST source.html reference.html
echo run "hoist" to hoist reference.html to doc directory

52
doc/src/source.html
View File

@ -903,6 +903,58 @@ $endif; template &lt;class InputIterator&gt;
$NAMESPACE_END;</pre>
<p><code><a name="value_type">value_type</a></code> is a <code>typedef</code> for the
character type used by the operating system to represent pathnames.</p>
$if $TARGET; == BOOST
<h3><a name="path-Usage"><code>path</code> Usage concerns</a> [path.usage]</h3>
<h4>Multithreading concerns</h4>
<p>Filesystem library functions are not protected against data races. [Modifying
an object of a Filesystem library type that is shared between threads risks
undefined behavior unless objects of that type are explicitly specified as being
sharable without data races or the user supplies a locking mechanism. <i>—end
note</i>] [<i>Note:</i> Thus the Filesystem library behaves as if it were part
of the standard library, and C++ standard 17.6.4.10 <i>Shared objects and the
library</i> [res.on.objects] would thus apply.&nbsp; <i>—end note</i>]</p>
<h4>Windows concerns</h4>
<p>Visual C++ at least through version 2012 does not employ C++11-style static
initialization locks, so the initialization of <code>path::codecvt()</code> can
race, either with itself or <code>path::imbue::()</code> if they are called from
a different thread. A workaround is to call:</p>
<blockquote>
<p><code>path::codecvt();&nbsp; // ensure VC++ does not race during
initialization.</code></p>
</blockquote>
<p>in the main thread before launching any additional threads. [<i>Note:</i> The
obvious fix of the Filesystem implementation doing the locking doesn't work
because of unrelated problems with the Microsoft compiler; for static linking
the runtime tries to do the initialization before main() starts, but doesn't
permit operating system lock calls at that time.&nbsp; <i>—end note</i>]</p>
<h4 dir="ltr">POSIX concerns</h4>
<p dir="ltr">Filesystem library initialization may throw an exception on POSIX
systems (e.g. Linux, but not Mac OS X) that use environmental variables to
determine the encoding of paths. This happens when <code>std::locale(&quot;&quot;)</code>
throws because an environmental variable such as LANG is set to an invalid
value, so it can affect any use of&nbsp; <code>std::locale(&quot;&quot;)</code>, not just
the Filesystem library. Filesystem uses lazy initialization so the exception is
only thrown if a valid <code>std::locale(&quot;&quot;)</code> is actually needed, and also
so that the exception is thrown after <code>main()</code> starts.</p>
<p>Rather than waiting until a call to some Filesystem library function
unexpectedly triggers the exception when it calls <code>path::codecvt()</code>,
a program that needs be highly robust against environmental variable problems
may want to preemptively call <code>std::locale(&quot;&quot;)</code> within a try block,
catch the exception, and diagnose or repair the invalid environmental variable.</p>
$endif
<h3><a name="path-Conversions"><code>path</code> Conversions</a> [path.cvt]</h3>
<h4><code>path</code> argument conversions [<a name="path.arg.convert">path.arg.cvt</a>]</h4>
<h5><a name="path-Conversions-to-native-format"><code>path</code> argument