...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
General changes:
text_file_backend
,
added support for appending to a previously written log file, when file
rotation is used and log file names use file counters. For this to work,
the target storage directory must be the same as the directory where the
active log file is written, and text_file_backend::scan_for_files
must be called prior to emitting any log records to discover the last file
counter used in the target storage directory. Previously, in such a configuration
the sink backend would generate a new file name instead of appending to
the last written one.
collector
interface has changed:
scan_for_files
method
returns a scan_result
structure that contains information collected during the scan;
is_in_storage
method
added for testing if a path refers to a file within the target storage
directory.
invoke_manip
stream manipulator
that can be used for injecting user's function into a stream output expression.
Bug fixes:
text_file_backend::scan_for_files
multiple times,
and the second and the following calls don't find any new files. (GH#179)
General changes:
std::codecvt
specializations for char16_t
and char32_t
for compatibility
with C++17 and later. (PR#159)
std::byte
type to receive methods of the inter-process
message queue.
nt62
tag in the
version namespace to denote the target OS ABI. For example, the version
namespace could be named as v2_mt_nt62
.
This name will be part of all symbols exported by the library. Use the
BOOST_USE_WINAPI_VERSION
macro consistenly when building Boost and your code to request the minimum
target Windows version.
dump
stream manipulator.
Bug fixes:
reliable_message_queue::open_or_create
or the equivalent
constructor. Multiple threads or processes calling open_or_create
concurrently with sending or receiving messages from the same queue could
end up corrupting the queue contents and potentially crashing the process.
(GH#162)
b2 install
failing on Windows because of
missing boost_log_setup
library if BOOST_LOG_WITHOUT_SETTINGS_PARSERS
is defined. (GH#164)
Bug fixes:
std::ios_base::app
file open mode in text_file_backend
now also implies
std::ios_base::ate
. This fixes incorrect accounting
for the initial size of the log file opened for appending. (GH#151)
Bug fixes:
unbounded_fifo_queue
policy of the asynchronous_sink
frontend. The race could be detected by TSAN, but it was not a real problem
on most current CPU architectures and compilers. (GH#139)
channel_logger
),
the channel attribute is now deep-copied from the original logger. This
means that modifying the channel in the new logger will no longer affect
the original logger.
std::allocator<void>
in template parameters with a new tag
type boost::log::use_std_allocator
to silence libc++ warnings
about the former being deprecated in C++17 and later. The tag indicates
that the instantiated template should be using a specialization of std::allocator
internally to allocate dynamic
memory, so the change has no functional effect. (GH#141)
__MSVCRT_VERSION__
macro on MinGW and MinGW-w64. This macro is used to select the target C
runtime library. Defining this macro caused incompatibility with UCRT,
which is available as an option in recent MinGW-w64. (PR#149)
Bug fixes:
text_file_backend
when generating
the target file name (based on the pattern set by set_target_file_name_pattern
method) when the log file is rotated. The backend used to use the next
value of file counter, which could cause some counter values to be skipped
on application restarts. (GH#125)
basic_sink_frontend
with an atomic. This should silence clang-cl warnings about deprecated
uses of volatile
. (GH#128)
asynchronous_sink
frontend, resolved a possible conflict between flush
and run
methods, if run
is called from a user's thread instead
of the internal dedicated thread spawned by the frontend. run
and feed_records
methods will wait for flush
to complete, if one is in progress. Additionally, stop
now explicitly doesn't wait for the ongoing record feeding operation to
complete. (GH#131)
Bug fixes:
ip_version
named parameter
on the sink backend construction (by default, IPv4 is assumed). When an
address is obtained as a result of host name resolution, only addresses
with matching IP version are considered. (GH#119)
New Features:
noexcept
.
range_manip
stream manipulator
that can be used for outputting elements of a range, optionally separated
by a delimiter.
tuple_manip
stream manipulator
that can be used for outputting elements of a tuple or any other heterogeneous
sequence, optionally separated by a delimiter.
optional_manip
stream manipulator
that can be used for outputting optionally present values.
New Features:
core::flush
now performs a flush on the default
sink used for trivial logging, when no sinks are registered.
Bug fixes:
openlog
call. Such implementations could access already freed memory on each syslog
call, resulting in undefined behavior.
(GH#97)
rotation_at_time_point(boost::gregorian::greg_day(1))
) could
be silently ignored and not happen. (GH#98)
text_file_backend
::rotate_file
could throw if there were no log records written yet and target file name
pattern was set. The method would attempt to rename a missing file, which
would result in an exception. Note that rotate_file
may still throw because of a missing log file, if the file being rotated
is removed by a third party.
std::allocator_traits
to improve compatibility with C++20 allocators.
New features:
std::string_view
in basic_formatting_ostream
.
The string view can now participate in character code conversion on output.
auto_newline
formatter
and stream
manipulator. It can be used to ensure that formatted output always
ends with a newline while avoiding duplicate newlines.
auto_newline_mode
enum either
in the auto_newline_mode
named parameter of the backend constructor or by calling the set_auto_newline_mode
method on the backend
post-construction. The auto_newline_mode
named parameter is also supported in the convenience
functions for initializing sinks. When initializing from settings
or a config file, the behavior is controlled by the new "AutoNewline"
parameter of the sink.
Note | |
---|---|
The default behavior with regard to trailing newlines has changed slightly
compared to the previous Boost.Log releases. The backends will now only add
a trailing newline if there isn't one in the formatted log message string
already. In previous releases a newline was added unconditionally. In general,
users are advised to configure their formatters so that the trailing newline
is added there, if needed (e.g. by using |
filter
and format
named parameters
to sink constructors and convenience
functions for initializing sinks. For example, it is now possible
to specify C++11 lambda functions directly in these parameters. (GH#63)
boost::log::trivial::severity_level
. For filters,
the support is limited to attributes with "Severity" name. This
relieves the user from having to register filter and formatter factories
in order to use boost::log::trivial::severity_level
with filters and formatters
parsed from strings or settings.
Note that any other custom severity level enums must still be registered,
as before.
Bug fixes:
scan_for_files
method would not find files matching that pattern in the target storage,
leaving them unmanaged. In particular, such files would not be deleted
to free target storage. (GH#78)
basic_formatting_ostream
and basic_record_ostream
to make it possible to overload stream output operators for pointers to
user-defined types. User-defined operator<<
overloads taking std::basic_ostream
and a pointer argument
should now be picked up by the compiler when the pointer is being written
to one of Boost.Log streams. (GH#84)
New features:
target_file_name
named parameter, text_file_backend::set_target_file_name_pattern
method call
or "TargetFileName" sink parameter in the settings).
This pattern will be used to generate a new file name when the file is
finished writing and is about to be collected. Therefore, the original
(active) file name can be set to a stable pattern (e.g. "app.log")
so that appending to a previously written file works. Then the target file
name can include a timestamp or a counter (e.g. "app-2019-01-05.log"),
so that different rotated files don't conflict in the target storage.
General changes:
Bug fixes:
file_collector::scan_for_files
.
Note that this configuration is still not fully supported and may result
in premature file deletion if multiple sinks write files directly into
the common target storage directory. It is recommended to configure sinks
to write log files into directories different from the target storage directory.
General changes:
General changes:
std::allocator_traits
where possible to work with allocators. This should improve compatibility
with C++ post C++17.
Bug fixes:
file_collector::scan_for_files
that caused zero file counter to be returned if the target directory contained
a file with the maximum counter value in the name. This used to cause incorrectly
named log files in the target directory after the user's application restart.
General changes:
General changes:
type_info_wrapper
.
As previously suggested, Boost.TypeIndex
is recommended as a replacement.
New features:
get_current_file_name
method.
enable_final_rotation
backend constructor parameter or similarly named method, or with the EnableFinalRotation
parameter in the
settings.
Bug fixes:
New features:
BOOST_LOG_WITHOUT_IPC
macro at library build time. Thanks to Lingxi Li for the initial patch.
max_size_decor
. The new decorator
allows to limit the output of its adopted formatter up to the specified
length. This can be useful with the new inter-process sink backend.
Bug fixes:
General changes:
boost::basic_string_ref
and its specializations
is deprecated; users are encouraged to switch to boost::basic_string_view
,
which is now supported for output to the formatting streams. The support
for boost::basic_string_ref
will be removed in future
releases.
max_files
named parameter to the make_collector
or add_file_log
calls or as the "MaxFiles" parameter for the sink in the settings
file. Thanks to Erich Keane for the patch. (#8746)
Bug fixes:
General changes:
BOOST_LOG_USE_WINNT6_API
is no longer used by the library. The target Windows version should be
configured by defining macro BOOST_USE_WINAPI_VERSION
to the desired WinAPI version (e.g. 0x0501 for Windows XP). This macro
is used in multiple different Boost libraries besides Boost.Log.
unbounded_fifo_queue
policy. The updated queue has improved performance in case of heavy thread
contention (hundreds and thousands of logging threads) on POSIX-compatible
systems.
Bug fixes:
formatting_ostream
.
(#11549)
formatting_ostream
.
(#11545)
wchar_t
type is disabled. Added a note of discouragement to the configuration
section. (#11541)
boost_log_setup
library on POSIX-like systems.
General changes:
invalid_type
exceptions
thrown by the library now have typeindex::type_index
attached as the description of the offending type. The type was previously
identified by type_info_wrapper
.
type_info_info
error
information now contains typeindex::type_index
instead of type_info_wrapper
.
This is the error info that can be used to obtain the type info from
invalid_type
exceptions.
attribute_value::get_type()
now returns typeindex::type_index
instead of type_info_wrapper
.
If the attribute_value
object is empty, the returned type_index
is default-constructed (i.e. refers to the void
type). User-defined attribute value implementations should be similarly
changed (the attribute_value::impl::get_type()
virtual method now also returns
typeindex::type_index
).
type_info_wrapper
component
has been deprecated and will be removed in future releases. Boost.TypeIndex
is recommended as a replacement.
boost/log/utility/intrusive_ref_counter.hpp
,
boost/log/utility/explicit_operator_bool.hpp
, boost/log/utility/empty_deleter.hpp
.
Bug fixes:
attribute_value_set::insert()
and attribute_value_set
constructor in some cases. The inserted elements could have made some previously
inserted elements not findable. The constructor from attribute_set
s
could leave some of the attribute values acquired from attributes not findable.
(#11190)
Bug fixes:
attribute_set::insert()
in some cases. The inserted elements
could have made some previously inserted elements not findable. (#11106)
attribute_value_set::size()
if a large number of attribute values
are inserted into the set. (#11148)
Bug fixes:
General changes:
attribute_name
arguments to record
and
record_view
. The operators
behave the same way as the similar operators of attribute_value_set
(i.e. return an attribute_value
identified by the name).
basic_formatting_ostream
.
(#9389)
depth
named parameter. (#9123)
std::regex
.
If boost/log/support/std_regex.hpp
is included, one can use std::regex
expressions with string
matching filters.
BOOST_LOG_USE_STD_REGEX
,
BOOST_LOG_USE_BOOST_REGEX
or BOOST_LOG_USE_BOOST_XPRESSIVE
at Boost.Log build time the user can select which regex implementation
will be used by the library internally for the string matching filters
parsed from strings and settings. Note that this selection does not affect
string
matching filters in expressions.
Bug fixes:
dump
manipulator output on AVX2-enabled
CPUs (e.g. Intel Haswell).
get_attribute
method of loggers.
locked_backend()
function implementation of synchronous
and asynchronous sink frontends.
block_on_overflow
strategy was used.
add_value
manipulator produce
garbage attribute values when using with immediate integer constants. (#9320)
General changes:
BOOST_LOG_WITHOUT_DEFAULT_FACTORIES
.
By defining this macro the user can disable compilation of the default
filter and formatter factories used by settings parsers. This can substantially
reduce binary sizes while still retaining support for settings parsers.
Note that when this macro is defined the user will have to register all attributes in the library.
boost/log/utility/intrusive_ref_counter.hpp
is deprecated and will be removed
in future releases. Its contents have been reworked and moved to Boost.SmartPtr,
as boost/smart_ptr/intrusive_ref_counter.hpp
.
boost/log/utility/explicit_operator_bool.hpp
is deprecated and will be removed
in future releases. Its contents have been moved to Boost.Utility,
as boost/utility/explicit_operator_bool.hpp
.
boost/log/utility/empty_deleter.hpp
is deprecated and will be removed
in future releases. Its contents have been moved to Boost.Utility,
as boost/utility/empty_deleter.hpp
.
Bug fixes:
timer
attribute generating incorrect time readings on Windows on heavy thread
contention when QueryPerformanceCounter
API was used.
Breaking changes:
basic_formatting_ostream
no longer derives from std::basic_ostream
,
but rather reimplements its and its base classes interface closely. This
solves problems with overloading operator<<
for basic_formatting_ostream
and user-defined types. This will break user's code if it relied on the
inheritance from the standard stream types (such as passing basic_formatting_ostream
object as an argument to a function receiving std::basic_ostream
).
Please, use the stream()
member function to access the standard
stream. This change will not break the
code that outputs user-defined types to a basic_formatting_ostream
stream while there are only operator<<
overloads for the standard stream
types - the code will compile and use the standard operator overloads,
as before.
General changes:
BOOST_LOG_USE_COMPILER_TLS
configuration macro is defined.
add_value
manipulator with MSVC.
dump
output manipulator for printing
binary data.
General changes:
BOOST_LOG_NO_COMPILER_TLS
configuration macro has been replaced with BOOST_LOG_USE_COMPILER_TLS
with the opposite meaning. The support for compiler intrinsics for TLS
is now disabled by default.
BOOST_LOG_WITHOUT_DEBUG_OUTPUT
,
BOOST_LOG_WITHOUT_EVENT_LOG
and BOOST_LOG_WITHOUT_SYSLOG
.
BOOST_LOG_NO_SETTINGS_PARSERS_SUPPORT
macro renamed to BOOST_LOG_WITHOUT_SETTINGS_PARSERS
.
The new macros allow to selectively disable support for the corresponding
sink backends.
BOOST_LOG_USE_WINNT6_API
macro. The code compiled without the macro defined will still be able run
on NT5, but when run on NT6 it will be more efficient. With the macro defined
the resulting code will not run on NT5, but will be a little more efficient
on NT6 than without the macro.
record_view
s. Records are now
moved from when pushed to the core for further processing. This is done
in order to eliminate the possibility of unsafe record modification after
pushing to the core. As a consequence, log records can no longer be copied,
only moving is allowed. Record views can be copied and moved; copying is
a shallow operation.
to_log
manipulator allows to customize
formatting for particular types and attributes without changing the regular
streaming operator. Also, the add_value
manipulator can be used
in logging expressions to attach attribute values to the record.
Attributes:
attribute_value
class in various components of the library is no longer pointed to with
shared_ptr
s but instead
is handled by value. This allowed to simplify attribute value handling
in simple cases.
attribute
base class, which holds the reference to the implementation. All attributes
now have to be created by value rather than wrapped into shared_ptr
by user, which makes the code
more concise.
attribute
to the actual attribute type. This can be useful when the concrete attribute
factory provides additional interfaces.
get
method. Use the extract
function as a replacement.
attribute_name
.
It is constructible from strings, so in most cases users won't need to
change the code. See here
for more information.
scoped_attribute.hpp
moved from utility
to the
attributes
directory. The
header attribute_value_extractor.hpp
in utility
has been replaced
with headers boost/log/attributes/value_extraction.hpp
and boost/log/attributes/value_visitation.hpp
in the attributes
directory.
The two new headers define the revised API of attribute value extraction
and visitation, respectively. See here
for more details.
current_thread_id
attribute no longer uses boost::thread::id
type for thread identification. An internal type is used instead, the type
is accessible as current_thread_id::value_type
.
The new thread ids are taken from the underlying OS API and thus more closely
correlate to what may be displayed by debuggers and system diagnostic tools.
current_process_name
attribute.
The attribute generates a string with the executable name of the current
process.
functor
attribute has
been renamed to function
.
The generator function has been renamed from make_functor_attr
to make_function
. The header
has been renamed from functor.hpp
to function.hpp
.
Logging sources:
BOOST_LOG_DECLARE_GLOBAL_LOGGER_INIT
to BOOST_LOG_INLINE_GLOBAL_LOGGER_INIT
,
BOOST_LOG_DECLARE_GLOBAL_LOGGER
to BOOST_LOG_INLINE_GLOBAL_LOGGER_DEFAULT
,
BOOST_LOG_DECLARE_GLOBAL_LOGGER_CTOR_ARGS
to BOOST_LOG_INLINE_GLOBAL_LOGGER_CTOR_ARGS
).
Also, the macros no longer define the get_logger
free function for logger acquisition. Use logger::get
instead. See here
for more information.
BOOST_LOG_STREAM_CHANNEL
and BOOST_LOG_STREAM_CHANNEL_SEV
(as well as their shorthands BOOST_LOG_CHANNEL
and BOOST_LOG_CHANNEL_SEV
)
macros that allow to specify channel name for the log record.
Logging sinks:
_t
suffix.
basic_formatting_sink_backend
class template, which indicates to the frontend that record formatting
is required. This breaks user-side API of the library: the formatter and
locale has to be set to the frontend rather than backend.
void flush()
.
asynchronous_sink
class template now allows to specify record queueing strategy. Several
strategies provided, including unbounded_fifo_queue
(the default) and unbounded_ordering_queue
which cover the functionality of asynchronous sink frontends in 1.x releases.
See the asynchronous
sink frontend docs for more details.
Append
configuration
file parameter for text file sinks. If this parameter is set to true
, the sink will append log records to
the existing log file instead of overwriting it.
Filters and formatters:
filter
and basic_formatter
.
Both new types implement type erasure and provide function calling operators
to invoke the stored filter or formatter.
expressions
namespace. Attribute placeholders are now interoperable with other template
expressions based on Boost.Phoenix.
All template expression headers now reside in the expressions
subdirectory.
BOOST_LOG_ATTRIBUTE_KEYWORD
macro). Keywords
can be used in template expressions instead of attribute placeholders and
also as a key in container lookups.
false
in such cases, the formatter
will result in empty string instead of the value. The behavior can be changed
by calling or_default
or
or_throw
member functions
on the attribute value placeholder in the filtering/formatting expression.
format_date_time
.
format_named_scope
.
c_decor
,
c_ascii_decor
, xml_decor
and csv_decor
.
The generic character decorator is named char_decor
now.
Documentation changes:
Miscellaneous:
push_record
if a sink throws and the
exception is suppressed by the exception handler set in the core.
type_visitor
instance by
value, and the visitor is no longer a base for the actual receiver of the
dispatched value. Instead, the visitor now refers to the receiver, if one
is capable to consume the value. The visit
method has been renamed to operator
()
. The static type dispatcher now
requires a reference to the receiver on construction, it doesn't imply
that the receiver derives from the dispatcher anymore.
slim_string
utility
has been removed. There is no replacement.
This release mostly fixes bugs in the code and documentation.
This release mostly fixes bugs in the code and documentation. The next major release (2.0) will contain breaking changes and feature additions. The 1.0 branch will not receive any feature updates.
BOOST_LOG_NO_COMPILER_TLS
during the library build process. The macro also affects other platforms,
which may be useful if your compiler does not support TLS.
rotation_interval
keyword is no longer
available. The same functionality is achieved with the new time_based_rotation
keyword and the
rotation_at_time_interval
predicate. See here
for more details.
support
directory. Top level library headers now mostly include nested headers.
keywords
namespace. There are no longer nested keywords
namespaces in sinks
, attributes
, etc. All keywords have been
extracted into separate headers in the keywords
directory.
add_common_attributes
.
init_log_to_file
now accept more customization options as named arguments.
No one really remembers these dark ages...