[Boost-commit] svn:boost r43048 - sandbox/logging/boost/logging/detail/raw_doc

From: john.groups_at_[hidden]
Date: 2008-02-01 15:13:06

Author: jtorjo
Date: 2008-02-01 15:13:05 EST (Fri, 01 Feb 2008)
New Revision: 43048
URL: http://svn.boost.org/trac/boost/changeset/43048

Log:
[logging]
v0.21.13, 1 feb 2008
- added known_issues section
- added getting_started section

Added:
   sandbox/logging/boost/logging/detail/raw_doc/getting_started.hpp   (contents, props changed)
   sandbox/logging/boost/logging/detail/raw_doc/known_issues.hpp   (contents, props changed)
Text files modified: 
   sandbox/logging/boost/logging/detail/raw_doc/changelog.hpp                   |     5 ++++-                                   
   sandbox/logging/boost/logging/detail/raw_doc/defining_your_logger_filter.hpp |     6 +++---                                  
   sandbox/logging/boost/logging/detail/raw_doc/table_of_contents.hpp           |    16 ++++++++++++----                        
   sandbox/logging/boost/logging/detail/raw_doc/todo.hpp                        |    15 +++++++--------                         
   4 files changed, 26 insertions(+), 16 deletions(-)

Modified: sandbox/logging/boost/logging/detail/raw_doc/changelog.hpp
==============================================================================
--- sandbox/logging/boost/logging/detail/raw_doc/changelog.hpp	(original)
+++ sandbox/logging/boost/logging/detail/raw_doc/changelog.hpp	2008-02-01 15:13:05 EST (Fri, 01 Feb 2008)
@@ -1,7 +1,10 @@
 /** 
 @page page_changelog Changelog
 
-_at_section changelog_cur_ver Current Version: v0.21.10, 31 jan 2008
+@section changelog_cur_ver Current Version: v0.21.13, 1 feb 2008
+- added known_issues section
+- added getting_started section
+- fixed scoped logs and added test
 - added test_on_dedicated_thread
 - updated Jamfile.v2 files for examples and test, for them to compile all files tests/examples
 - updated Jamfile.v2 to actually build the tests + the tests to use BOOST_CHECK

Modified: sandbox/logging/boost/logging/detail/raw_doc/defining_your_logger_filter.hpp
==============================================================================
--- sandbox/logging/boost/logging/detail/raw_doc/defining_your_logger_filter.hpp	(original)
+++ sandbox/logging/boost/logging/detail/raw_doc/defining_your_logger_filter.hpp	2008-02-01 15:13:05 EST (Fri, 01 Feb 2008)
@@ -172,8 +172,8 @@
 @code
 #include <boost/logging/format_fwd.hpp>
 
-namespace b_l = boost::logging;
-typedef b_l::logger_format_write< b_l::default_, b_l::default_, b_l::writer::threading::on_dedicated_thread > logger_type;
+namespace bl = boost::logging;
+typedef bl::logger_format_write< bl::default_, bl::default_, bl::writer::threading::on_dedicated_thread > logger_type;
 
 // declare
 BOOST_DECLARE_LOG(g_l, logger_type) 
@@ -370,7 +370,7 @@
 logger_type * g_l() { static logger_type l; return &l; }
 @endcode
 
-When fast compile is off, BOOST_DEFINE_LOG will generate code similar to this:
+When fast compile is on, BOOST_DEFINE_LOG will generate code similar to this:
 
 @code
 logger_holder<logger_type> & g_l() { static logger_holder_by_value<logger_type> l; return l; }

Added: sandbox/logging/boost/logging/detail/raw_doc/getting_started.hpp
==============================================================================
--- (empty file)
+++ sandbox/logging/boost/logging/detail/raw_doc/getting_started.hpp	2008-02-01 15:13:05 EST (Fri, 01 Feb 2008)
@@ -0,0 +1,76 @@
+namespace boost { namespace logging {
+
+/** 
+@page getting_started Getting started - the Fast & Furious way...
+
+
+- @ref getting_started_basics 
+- @ref getting_started_code
+- @ref getting_started_example_no_levels 
+- @ref getting_started_example_use_levels
+- @ref getting_started_other_examples 
+
+
+
+So, you don't have time to spend (at least not right now), to read the @ref log_tutorial "tutorial", but still want to use the Boost Logging Lib.
+
+\n\n
+@section getting_started_basics The basics
+
+Here are the quick facts:
+- We use the folloging concepts:
+  - logger : the class that does the logging. You can have several logger objects in your code, but usually one will suffice.
+    - writer : an object, part of the logger, that is in charge of writing the message
+  - filter : the class that does the filtering - that is, it knows if a message should be logged or not
+
+There are several @ref writer "writers". The most common uses the concept of formatters and destinations:
+- formatter : formats the message before writing it (for instance, by prepending time to it, an index, etc.)
+- destination : represents a place where the message is to be written to (like, console, a file, debug window, etc.)
+
+Once you have a %writer, you can add several formatters and/or destinations. The %writer object knows how to call them.
+The common (and default) one calls them like this:
+- first, all formatters (in the order they were added)
+- second, all destinations (in the order they were added)
+
+The easiest %writer is the @ref boost::logging::writer::named_write "Named Writer". It's an easy interface to using formatters and destinations.
+In other words, you set @ref format_string_syntax "a format string" and @ref dest_string_syntax "a destination string".
+
+
+\n\n
+@section getting_started_code Structuring your code
+
+You'll use macros to:
+- declare and define the filters and loggers
+- do %logging.
+
+You should structure your code like this:
+- have a header file, in which you @c \#include the Boost Logging Lib forward classes, and you declare your loggers and filters
+- have a source file, in which you define your loggers and filters, and eventually initialize them
+- in the rest of the code, when you intend to do %logging, just include the above header file
+
+\n\n 
+@section getting_started_example_no_levels Example 1 : Have one Named Writer, No levels
+
+Assume you want one logger and one filter - the filter is a simple filter that can only be turned on/off (the filter is not thread-safe). \n
+This is something you can copy-paste into your program.
+
+@include fast_start/no_levels.h
+
+
+\n\n 
+@section getting_started_example_use_levels Example 2 : Have one Named Writer , Use Levels
+
+Assume you want one logger and one filter - the filter is a based on levels (the filter is not thread-safe). \n
+This is something you can copy-paste into your program.
+
+@include fast_start/use_levels.h
+
+
+@section getting_started_other_examples Other examples...
+
+Yup, we have @ref common_scenarios "other examples" as well. We also have a @ref starter_project "starter project".
+
+
+*/
+
+}}

Added: sandbox/logging/boost/logging/detail/raw_doc/known_issues.hpp
==============================================================================
--- (empty file)
+++ sandbox/logging/boost/logging/detail/raw_doc/known_issues.hpp	2008-02-01 15:13:05 EST (Fri, 01 Feb 2008)
@@ -0,0 +1,103 @@
+namespace boost { namespace logging {
+
+/** 
+@page known_issues Known Issues
+
+- @ref known_issue_modifying_manipulator 
+
+
+
+@note
+This section assumes you're quite familiar with Boost Logging Lib v2, thus the concepts used here are not explained.
+
+
+\n
+@section known_issue_modifying_manipulator Modifying a manipulator while it's used
+
+\n
+@subsection known_issue_modifying_manipulator_code Sample code
+
+@code
+#define L_(lvl) BOOST_LOG_USE_LOG_IF_LEVEL(g_l(), g_log_level(), lvl )
+
+destination::stream out(std::cout);
+g_l()->writer().add_destination(out);
+...
+
+
+// Thread 1
+out.stream(std::cerr);
+
+// Thread 2
+L_ << "whatever";
+@endcode
+
+\n
+@subsection known_issue_modifying_manipulator_resolution Resolution
+
+If the above code executes concurrently on Threads 1 and 2, we could get in trouble.
+
+This happens because the thread-safe access is guaranteed :
+- only if you specify it - when defining the writer (see @ref scenario::usage "scenario based on usage" and logger_format_write)
+- it's guaranteed only for <em>adding and deleting</em> manipulators, not for modifying manipulators.
+
+If we were to allow modifying manipulators, we'd have to:
+-# either allow a way to pause()/resume() the logger(s) that use a given manipulator or
+-# allow thread-safe access to the manipulator objects (meaning each public method would use a mutex, and keep it locked)
+
+In case of the former, pitfalls:
+- When modifying a manipulator, you'd need to pause() all loggers that use it. You need to know them.
+- This pause()/resume() mechanism will slow the logging process a bit
+- This will mean tight coupling between the writer and its member data. 
+- In case a lot of logging happens while a logger is paused, could cause either a lot of caching, or a performance hit
+  (a lot of threads would have to wait for the resume() to happen)
+
+In case of the latter, pitfalls:
+- This will incur a big speed penalty - each time you invoke operator() on the manipulator, will involve a mutex lock/unlock
+- The more manipulators a logger uses, the more mutex lock/unlocks will happen. Thus, the speed penalty will be even bigger.
+
+As a side-note, if I were a well known company, I'd just say "This behavior is by design".
+
+\n
+@subsection known_issue_modifying_manipulator_when When does it happen?
+
+I would say seldom. This can happen to you only if you want to modify loggers @em after you've initialized - thus, while
+you're logging. 
+
+The usual scenario is :
+- you initialize Logging once, at beginning of program
+- you perform %logging (you don't modify the loggers once they've been initialized)
+
+In the above scenario, this issue will never happen. However, if you do run into it, see @ref known_issue_modifying_manipulator_workaround "below".
+
+
+\n
+@subsection known_issue_modifying_manipulator_workaround Solution
+
+The solution is dead-simple. Just delete this %manipulator, create one of the same type, modify that one, and then add it
+to your logger(s). In the original @ref known_issue_modifying_manipulator_code "scenario", you'd do this:
+
+@code
+#define L_(lvl) BOOST_LOG_USE_LOG_IF_LEVEL(g_l(), g_log_level(), lvl )
+
+destination::stream out(std::cout);
+g_l()->writer().add_destination(out);
+...
+
+
+// Thread 1
+destination::stream out2(std::cerr);
+g_l()->writer().del_destination(out);
+g_l()->writer().add_destination(out2);
+
+// Thread 2 - all good
+L_ << "whatever";
+
+@endcode
+
+
+
+
+*/
+
+}}

Modified: sandbox/logging/boost/logging/detail/raw_doc/table_of_contents.hpp
==============================================================================
--- sandbox/logging/boost/logging/detail/raw_doc/table_of_contents.hpp	(original)
+++ sandbox/logging/boost/logging/detail/raw_doc/table_of_contents.hpp	2008-02-01 15:13:05 EST (Fri, 01 Feb 2008)
@@ -14,6 +14,7 @@
       - @ref breaking_change_v_20
     - @ref misc_compilers 
 
+- @ref getting_started
 
 - @ref workflow
     - @ref workflow_introduction 
@@ -31,8 +32,10 @@
     - @ref scenario_multiple_files
     - @ref starter_project 
 
+
 \n
-- @b Tutorial
+@section log_tutorial Tutorial
+
     - @ref headers_to_include "Headers to #include"
     - @ref defining_your_logger_filter 
     - @ref defining_logger_macros
@@ -41,13 +44,17 @@
     - @ref tag "Using tags"
     - @ref profile "Profiling - computing the time spent while logging"
 
+
+
 \n
-- <b>Special cases</b>
+@section special_cases Special Cases
+
     - @ref caching 
     - @ref after_destruction 
 
-\n\n
-Advanced concepts
+\n
+@section advanced_concepts Advanced concepts
+
 - @ref thread_safety 
 - @ref misc_unicode
 - @ref macros
@@ -84,6 +91,7 @@
 - @ref boost_logging_requirements 
 - @ref page_todo 
 - @ref rationale 
+- @ref known_issues 
 
 */
 

Modified: sandbox/logging/boost/logging/detail/raw_doc/todo.hpp
==============================================================================
--- sandbox/logging/boost/logging/detail/raw_doc/todo.hpp	(original)
+++ sandbox/logging/boost/logging/detail/raw_doc/todo.hpp	2008-02-01 15:13:05 EST (Fri, 01 Feb 2008)
@@ -26,16 +26,16 @@
 - @c normal         destination::stream_ptr - just like stream, but hold the stream as a shared pointer. Thus , we won't have to worry
                     about outliving the stream.
 
+- @c normal         make it possible to initialize from a file - thus we'd need no caching!
+                    also allow for extra syntax for the named_writer - {} - to be applied to a destination
+                    this way, you can specify some extra formatters to be applied only to a specific destination
+
 - @c normal         on_dedicated_thead - remove dependency on boost::thread
 
 - @c normal         on_dedicated_thead - I should see it I use logger::always_accurate increases logging time as opposed to some caching strategy.
                     I'm asking this because even if we were to use a critical section on the base_type writer's operator(), this will
                     *always* happen on the dedicated thread. Thus, I would think it should have very small overhead
 
-- @c high           bug: if using named_writer on top of on_dedicated_thread writer, and I reset the format or destination strings,
-                    I might end up modifying a formatter or destination, while some other thread is using it
-                    perhaps it's not a bug - but pause()/resume() need to be called on it. Perhaps I can automate this!
-
 - @c normal         must have helper to call on on_destructed - like, to be able to write to cout,etc
 
 - @c normal         turn_cache_off() -> find better name, like mark_init_complete()  (add a function named like this to call turn_cache_off()).
@@ -53,12 +53,11 @@
 - @c normal         make it so that I use BOOST_LOG_USE_WCHAR_T as little as possible
                     for instance, it's not needed in cout_t, cerr_t.
 
-- @c high           should see that if I have a tss* object, if used AFTER destruction, will not crash the application.
-                    in other words, if I have tss_with_cache<int>, after this is destroyed, I should always reference the original int or so.
-                    I need this when using a filter using TSS, after the filter has been destroyed. 
-
 - @c high           cut down compile time: make it compile faster (most likely improve use_format_write, etc)
 
+- @c high           named_write<> - due to @ref known_issue_modifying_manipulator - whenever I modify the format and/or destination string,
+                    i need to add/delete all formatters and/or destinations in order to avoid that scenario TOTHINK
+
 - @c high           logger_format_write<> should be just like other find classes - have logger_format_write<>::type
                     this should uncomplicate code a bit - at least specializing logger_to_gather/writer for logger_format_write<>. \n
                     I will first need to see if this will cut down compilation time or not.