[Boost-commit] svn:boost r86296 - trunk/libs/log/doc

Subject: [Boost-commit] svn:boost r86296 - trunk/libs/log/doc
From: andrey.semashev_at_[hidden]
Date: 2013-10-14 07:00:49

Author: andysem
Date: 2013-10-14 07:00:48 EDT (Mon, 14 Oct 2013)
New Revision: 86296
URL: http://svn.boost.org/trac/boost/changeset/86296

Log:
Added a FAQ entry about problems with file sinks on process termination.

Text files modified: 
   trunk/libs/log/doc/rationale.qbk     |    29 +++++++++++++++++++++++++++++           
   trunk/libs/log/doc/sink_backends.qbk |     2 ++                                      
   trunk/libs/log/doc/utilities.qbk     |     2 ++                                      
   3 files changed, 33 insertions(+), 0 deletions(-)

Modified: trunk/libs/log/doc/rationale.qbk
==============================================================================
--- trunk/libs/log/doc/rationale.qbk	Sun Oct 13 16:10:25 2013	(r86295)
+++ trunk/libs/log/doc/rationale.qbk	2013-10-14 07:00:48 EDT (Mon, 14 Oct 2013)	(r86296)
@@ -166,6 +166,35 @@
 
 [endsect]
 
+[section:why_crash_on_term Why my application crashes on process termination when file sinks are used?]
+
+There are known problems with __boost_filesystem__ (for example, [ticket 8642] and [ticket 9219]), which affect Boost.Log file sink backends. When the file sink is destroyed, it attempts to perform a final log file rotation, which involves __boost_filesystem__ for moving files. This typically happens when Boost.Log core is deinitialized, at the global deinitialization stage, after leaving `main()`. The crux of the problem is that __boost_filesystem__ uses a global locale object internally to perform character code conversion for `path`s, and this locale may get destroyed before Boost.Log is deinitialized, which results in a crash.
+
+There is no way for Boost.Log to influence the order of global deinitialization, but the problem can be worked around on the user's side. One solution is to make sure the locale is initialized /before/ Boost.Log. This can be achieved by calling `boost::filesystem::path::codecvt()` or `boost::filesystem::path::imbue()` early during the application startup, before performing any calls to Boost.Log. For example:
+
+    int main(int argc, char* argv[])
+    {
+        boost::filesystem::path::imbue(std::locale("C"));
+        initialize_log();
+
+        // ...
+    }
+
+Note that in this case you can't use Boost.Log in global constructors or you have to make sure that `boost::filesystem::path::imbue()` is still called first.
+
+Another solution is to remove and destroy file sinks from the logging core before returning from `main()`. This way file rotation will happen before leaving `main()`, while the locale is still valid. The file sinks can be removed either individually or as a part of the `remove_all_sinks()` call:
+
+    int main(int argc, char* argv[])
+    {
+        // ...
+
+        logging::core::get()->remove_all_sinks();
+
+        return 0;
+    }
+
+[endsect]
+
 [section:namespace_mangling Why my application fails to link with Boost.Log? What's the fuss about library namespaces?]
 
 The library declares the `boost::log` namespace which should be used in client code to access library components. However, internally the library uses another nested namespace for actual implementation. The namespace name is configuration and platform dependent, it can change between different releases of the library, so it should never be used in the user side code. This is done in order to make the library configuration synchronized with the application as much as possible and eliminate problems caused by configuration mismatch.

Modified: trunk/libs/log/doc/sink_backends.qbk
==============================================================================
--- trunk/libs/log/doc/sink_backends.qbk	Sun Oct 13 16:10:25 2013	(r86295)
+++ trunk/libs/log/doc/sink_backends.qbk	2013-10-14 07:00:48 EDT (Mon, 14 Oct 2013)	(r86296)
@@ -34,6 +34,8 @@
 
 The backend is called [class_sinks_text_file_backend].
 
+[warning This sink uses __boost_filesystem__ internally, which may cause problems on process termination. See [link log.rationale.why_crash_on_term here] for more details.]
+
 [heading File rotation]
 
 File rotation is implemented by the sink backend itself. The file name pattern and rotation thresholds can be specified when the [class_sinks_text_file_backend] backend is constructed.

Modified: trunk/libs/log/doc/utilities.qbk
==============================================================================
--- trunk/libs/log/doc/utilities.qbk	Sun Oct 13 16:10:25 2013	(r86295)
+++ trunk/libs/log/doc/utilities.qbk	2013-10-14 07:00:48 EDT (Mon, 14 Oct 2013)	(r86296)
@@ -526,6 +526,8 @@
 ]
 ]
 
+[warning The text file sink uses __boost_filesystem__ internally, which may cause problems on process termination. See [link log.rationale.why_crash_on_term here] for more details.]
+
 The time-based rotation can be set up with one of the two parameters: RotationInterval or RotationTimePoint. Not more than one of these parameters should be specified for a given sink. If none is specified, no time-based rotation will be performed.
 
 The RotationTimePoint parameter should have one of the following formats, according to the __boost_date_time_format__ format notation: