|
|
Boost-Commit : |
From: john.groups_at_[hidden]
Date: 2008-01-17 03:35:27
Author: jtorjo
Date: 2008-01-17 03:35:26 EST (Thu, 17 Jan 2008)
New Revision: 42831
URL: http://svn.boost.org/trac/boost/changeset/42831
Log:
[logging]
v0.20.3, 17 jan 2008
- explained the breaking change in the docs
Added:
sandbox/logging/boost/logging/detail/raw_doc/breaking_changes.hpp (contents, props changed)
Text files modified:
sandbox/logging/boost/logging/detail/raw_doc/changelog.hpp | 6 ++++--
sandbox/logging/boost/logging/detail/raw_doc/rationale.hpp | 22 ++++++++++++++++++++++
sandbox/logging/boost/logging/detail/raw_doc/table_of_contents.hpp | 3 +++
sandbox/logging/lib/logging/internal/vc8/loggingvc8/loggingvc8.vcproj | 11 ++++-------
4 files changed, 33 insertions(+), 9 deletions(-)
Added: sandbox/logging/boost/logging/detail/raw_doc/breaking_changes.hpp
==============================================================================
--- (empty file)
+++ sandbox/logging/boost/logging/detail/raw_doc/breaking_changes.hpp 2008-01-17 03:35:26 EST (Thu, 17 Jan 2008)
@@ -0,0 +1,86 @@
+namespace boost { namespace logging {
+
+/**
+@page breaking_changes Breaking changes
+
+- @ref breaking_change_v_20
+
+@section breaking_change_v_20 v0.20.1 - Use filters/loggers as functions: append "()" to them
+
+@subsection breaking_change_v_20_what_changed What changed?
+
+Now, for every call to a filter/logger, you need to append "()" to it. You'll need to do this:
+- when initializing the logs
+- when you've defined your macros
+ - any usage of BOOST_LOG_USE_LOG_IF_LEVEL, BOOST_LOG_USE_LOG_IF_FILTER, BOOST_LOG_USE_SIMPLE_LOG_IF_FILTER
+- when dealing with filters (turning them on/off, changing filter levels)
+
+
+Example
+
+Before:
+
+@code
+#define L_ BOOST_LOG_USE_LOG_IF_FILTER(g_l, g_log_filter->is_enabled() )
+
+g_l->writer().add_formatter( formatter::idx(), "[%] " );
+g_l->writer().add_formatter( formatter::append_newline_if_needed() );
+g_l->writer().add_destination( destination::file("out.txt") );
+g_l->turn_cache_off();
+
+g_log_filter->set_enabled(false);
+
+@endcode
+
+After:
+
+@code
+#define L_ BOOST_LOG_USE_LOG_IF_FILTER(g_l(), g_log_filter()->is_enabled() )
+
+g_l()->writer().add_formatter( formatter::idx(), "[%] " );
+g_l()->writer().add_formatter( formatter::append_newline_if_needed() );
+g_l()->writer().add_destination( destination::file("out.txt") );
+g_l()->turn_cache_off();
+
+g_log_filter()->set_enabled(false);
+
+@endcode
+
+
+
+@subsection breaking_change_v_20_why Why?
+
+Yes, I know it's near review time and I should not do this, but...
+
+I've gotten a bit of feedback on my extensive use of macros, and some of those being rather complex.
+And lately I've re-analyzed the library, see where implementation could be simpler, etc., and the main part was - macros.
+
+More to the point, declaring/defining a log/filter should be simpler - the macros for doing this should be simpler.
+
+Previously, I wanted to abstract away the fact that when using BOOST_LOG_DECLARE/DEFINE, internally we'd be creating a @ref rationale_use_functions "function",
+but use it as a variable:
+
+@code
+// before version v0.20
+
+BOOST_DEFINE_LOG(g_l, log_type)
+
+// in code, "g_l" is used like a variable
+g_l->writer().add_formatter( formatter::idx(), "[%] " );
+@endcode
+
+However, @c g_l was a variable which always forwarded to a @ref rationale_use_functions "function". Making this possible required quite a bit of trickery,
+and complicated the implementation of BOOST_LOG_DECLARE/DEFINE.
+
+And even worse, extending them would be a nightmare: Basically I wanted to allow exporting a logger, for instance, from a DLL to an application.
+With the previous syntax, it would be very complex to implement.
+
+So, to make it easier, now, BOOST_LOG_DECLARE/DEFINE declare/define the function directly (as opposed to before, when they did define a function
+with a different name, and then define a variable referencing that function).
+
+To understand why BOOST_LOG_DECLARE/DEFINE declare/defines a @b function, as opposed to a @b variable, see @ref rationale_use_functions.
+
+
+*/
+
+}}
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-01-17 03:35:26 EST (Thu, 17 Jan 2008)
@@ -1,8 +1,10 @@
/**
@page page_changelog Changelog
-_at_section changelog_cur_ver Current Version: v0.20.1, 17 jan 2008
-- *** BREAKING CHANGE : when you use the filters/loggers, use them as function names (append "()" to them)
+@section changelog_cur_ver Current Version: v0.20.3, 17 jan 2008
+- explained the breaking change in the docs
+- updated the tests to compile (after the breaking change)
+- @ref breaking_change_v_20 "BREAKING CHANGE" : when you use the filters/loggers, use them as function names (append "()" to them)
- Please take a look at the updated examples or at the online help. Thanks for understanding.
v0.14.1, 17 jan 2008
Modified: sandbox/logging/boost/logging/detail/raw_doc/rationale.hpp
==============================================================================
--- sandbox/logging/boost/logging/detail/raw_doc/rationale.hpp (original)
+++ sandbox/logging/boost/logging/detail/raw_doc/rationale.hpp 2008-01-17 03:35:26 EST (Thu, 17 Jan 2008)
@@ -27,8 +27,30 @@
+@section rationale_use_functions Rationale for - Why BOOST_LOG_DECLARE/DEFINE define a function, instead of a variable
+Note: this section applies to both loggers and filters.
+When using BOOST_LOG_DECLARE/DEFINE, they internally declare/define a function:
+
+@code
+BOOST_DECLARE_LOG(g_l, log_type)
+
+// equivalent to:
+implementation_defined g_l();
+@endcode
+
+The reason we're defining a @b function that returns something (logger/filter), instead of a @b variable of the same type, is
+that if we were in the latter case, we could end up using a logger/filter @b before it's initialized.
+
+We could end up with this scenario:
+- have 2 translation units: T1 and T2
+ - in T1 I define a logger
+ - in T2 I create a static object, which in its constructor, uses the logger defined in T1
+
+The order of initialization between translation units is unspecified, so you could end up using the logger from T1, before its constructor is called.
+
+When using a function, this problem is avoided.
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-01-17 03:35:26 EST (Thu, 17 Jan 2008)
@@ -10,6 +10,9 @@
- @ref page_changelog
- @ref changelog_cur_ver
- @ref acknowledgements
+ - @ref breaking_changes
+ - @ref breaking_change_v_20
+
- @ref workflow
- @ref workflow_introduction
Modified: sandbox/logging/lib/logging/internal/vc8/loggingvc8/loggingvc8.vcproj
==============================================================================
--- sandbox/logging/lib/logging/internal/vc8/loggingvc8/loggingvc8.vcproj (original)
+++ sandbox/logging/lib/logging/internal/vc8/loggingvc8/loggingvc8.vcproj 2008-01-17 03:35:26 EST (Thu, 17 Jan 2008)
@@ -702,6 +702,10 @@
>
</File>
<File
+ RelativePath="..\..\..\..\..\boost\logging\detail\raw_doc\breaking_changes.hpp"
+ >
+ </File>
+ <File
RelativePath="..\..\..\..\..\boost\logging\detail\raw_doc\caching.hpp"
>
</File>
@@ -864,13 +868,6 @@
<File
RelativePath="..\..\..\samples\scenarios\mul_levels_one_logger.cpp"
>
- <FileConfiguration
- Name="Test|Win32"
- >
- <Tool
- Name="VCCLCompilerTool"
- />
- </FileConfiguration>
</File>
<File
RelativePath="..\..\..\samples\scenarios\mul_loggers_one_filter.cpp"
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk