March 2010 - Boost - lists.boost.org

Fwd: Re: [log] review part 1
by Andrey Semashev 15 Mar '10

15 Mar '10

Due to technical reasons this reply went off-list. For sake of keeping the conversation public, I'm reposting it. -------- Original Message -------- Subject: Re: [boost] [log] review part 1 Date: Sat, 13 Mar 2010 16:08:14 +0300 From: Andrey Semashev <andrey.semashev(a)gmail.com> To: Steven Watanabe <watanabesj(a)gmail.com> On 03/12/2010 07:22 AM, Steven Watanabe wrote: > I mostly have documentation notes at this point. Andrey, since I have so > many, and they're mostly fairly minor, would it be better if I made > a patch for the documentation source? Yes, that would be great. I quickly reviewed your suggestions, and they all look reasonable (I always have a hard time with articles). Thanks! > I think newbies should probably be replace globally with new users, > since I kind of feel that the term newbie is somewhat derogatory. Ok. I didn't mean to offend anyone, of course. :) > http://boost-log.sourceforge.net/libs/log/doc/html/log/defs.html > ================================================================================ > > For Log record: > I don't like the expression "A single pack of information," although > I can't think of anything better off hand. A collection of data,...? > ================================================================================ > > Issues: > > Instead of compiling a narrow or wide library, why don't you use > libboost_log > and libboost_wlog? There are parts that would be the same in both these libraries. Most notably, singletons of file_collector repository and some constants. This might lead to linking problems if someone tries to use both versions of the library. > I agree with other comments that I saw about Attribute being > a poor choice for what it does. I would prefer that the term "Attribute" > should be used for what you call an "Attribute Value," and that > there should be a different term, like "Attribute Extractor" for > what you call an "Attribute." My understanding of the term "attribute" is that it's some kind of meta-information that defines the concrete values that will be attached to log records. I'm ready to agree that the word "attribute" doesn't bring my intention precisely, but the alternatives don't quite get closer. "Extractors" are reserved for another tool in the library.

5 6

static in_class constants
by Christian Henning 15 Mar '10

15 Mar '10

Hi there, I'm finishing up some linker problems I have with gcc. One area of problems seems to be static in_class constants that I have declared in my header file. MSVC doesn't have problem with it but gcc is complaining. I'm wondering how other libs in boost are dealing with these problems. For instance in my new gil::io lib I define some tags in pnm_tags.hpp as follows: /// Defines type for image type property. struct pnm_image_type : property_base< uint32_t > { BOOST_STATIC_CONSTANT( type, _mono_asc = 1 ); // Monochrome ASCII encoding BOOST_STATIC_CONSTANT( type, _gray_asc = 2 ); // Gray level ASCII encoding BOOST_STATIC_CONSTANT( type, _color_asc = 3 ); // sRGB color ASCII encoding BOOST_STATIC_CONSTANT( type, _mono_bin = 4 ); // Monochrome binary encoding BOOST_STATIC_CONSTANT( type, _gray_bin = 5 ); // Gray level binary encoding BOOST_STATIC_CONSTANT( type, _color_bin = 6 ); // sRGB color binary encoding }; Thanks, Christian

7 27

Review - boost::log
by Tom Brinkman 15 Mar '10

15 Mar '10

Should boost log be accepted into the boost library? My vote is no. This library will just reinforce boost's reputation as being a repository of needlessly complicated highly templatized libraries for relatively easy programming tasks. I don't mind this added complexity when it comes to genuinely difficult problem spaces. In my view, however, logging is not one of those problem spaces. Logging is one of those things that if it takes longer than 10 minutes to read the documentation and get up to speed, it will not get used. What is your evaluation of the design? Very much in the spirit of a typical boost library. However, it has very little attention to "C" interfaces and makes heavy use of templates. I suppose because this is boost, that that is acceptable. However, boost and the c++ community at large should start moving towards a more friendly attitude towards a "C" style api for utility libraries. Most non-boost c++ developers will dismiss this library out of hand, not because its a bad library, its not, it's just more of the same. Heavy handed use of templates. I guess I've spent too much time over the last 5 years ripping out poorly conceived heavily templated code. The thought of adding to this madness, with another utility library that is burdened by templates is hard to swallow. What is your evaluation of the documentation? Good What is your evaluation of the potential usefulness of the library? Logging is useful. Yes. Did you try to use the library? With what compiler? Did you have any problems? Yes. GCC++. No problems How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? 2 hours Are you knowledgeable about the problem domain? Yes. I was the review wizard for three years and have followed the progression of boost from the beginning, Tom Brinkman

10 23

Re: [boost] suggestion on assertion macros
by Andrzej Krzemienski 15 Mar '10

15 Mar '10

> there were a discussion recentrly about verifying arguments of > assertion macros while checks are turned off > i've got an idea of how to check the argument(s) and guarantee zero > code size and runtime overhead Hi, This is a good addition to assertions, but once we decide that we are improving assertions, there is much more that needs an improvement. Most of them are listed in the thread on Contract++ library (proposed for Boost) that you are already referring to. But let me list the potential improvements here. 1. If the expression in assertion throws an exxception, this should also be considered an assertion failure. Otherwise evaluating or not evaluating an assertion may render different program behavior. You can implement that by wrapping the expression with a try-catch block; but then assertion is a statement rather than an expression. Personally I think it is even better that an assert in a statement and it cannot be a subexpression of a bigger expression, but it no longer complies to assertion interface. Lambdas have the capability of changing statements into expressions, but we do not have them yet. 2. Be able to disable some assertions, but not all, e.g. I want the following assert in my code never to execute: assert<low_level>( is_sorted( v.begin(), v.end() ) ); find_logarithmic( v.begin(), v.end(), val ); Simply because it may be too slow even in debug. 3. I may want to disable even syntax checking in order for my compilation to run faster. I guess we should also consider user that prefer slower applications that compile faster 4. Make sure that the expression does not access any global variables. Well, we shouldn't really forbid that but give it as an option for the programmers that like "functional style" programming. I don't know how to do that now, but with lambdas, I believe it is posible with empty capture lists. 5. At least try to limit the possibility of the expression having any side effect. Contract++ ttries to do it by enforcing the const correctness of some inputs. Perhaps, even the old assert is left alone and some super-assert like the one from Concept++ should be incorporated into Boost and be the preferred way of veryfing user assumptions. Regards, &rzej

6 11

[iostreams] Add char_traits to the Device concept
by thomas weidner 14 Mar '10

14 Mar '10

Hi, i came across this issue when trying to use iostreams with a custom character class and custom character traits. The main problem is, that iostreams assumes std::streampos as the position type for all devices. Some parts of iostreams, like detail::indirect_streambuf honor the char traits' custom pos_type, but this will cause build failures as the underlying device (even code_converter) uses std::streampos as position type. My proposal is to add an associated character traits type to a Device. A Device type whould therefore not only provide information about the underlying character type, but also about the used pos_type, off_type and code conversion (not) done. I would even use traits different from std::char_traits<Ch>/iostreams::char_traits<Ch> as default character traits for most devices. Most devices like for example file_descriptor_sink don't do any code conversion, so a pos_type which contains a mbstate_t is useless and leaves the user with the impression, that code conversion *is* done. A simple integral type like C's off_t should do fine. Let's call those traits binary_char_traits for now. As an implication of this a iostreams::stream_buffer<file_descriptor_sink> should use the Device's char traits type, so should be a std::basic_streambuf<char, binary_char_traits<char> >. Especially it whould not be useable with std::iostream. This is IMO a nice and very clean result, as an iostream expects characters on which code conversion has been performed. You whould need to plug a code_converter in between. Some thoughts about iostreams::code_converter. Perhaps we should change the Codecvt template parameter to a second traits type. This traits type will become the code_converter's associated char traits type. the codecvt type could be an extra template parameter or is simply std::codecvt<code_converter_char_type, underlying_device_char_type, codecvt, code_converter_traits_state_type>. this whould be the same mechanism as code conversion in the stdlib works (using std::codecvt specialization). Comments to my thoughts are very welcome. --- Thomas

1 0

Re: [boost] [log] Boost.Log Review...
by Sean Chittenden 14 Mar '10

14 Mar '10

>> The above wasn't explicitly distilled in the documentation in a >> single place, but I think future developers would find it very useful >> to see that spelled out explicitly. Given the extremely modular >> design of the library, I understand why the docs are the way they are >> and know that some of this is touched on in the Design Overview, but >> until I became very competent with the library, the documentation >> seemed too abstract. Despite the importance of logging, becoming a >> logging expert was tangential to the problem I was trying to solve >> and I would have personally found the above summary very useful. > > Well, that summary may describe your use case very well, but it is by no > means complete with regard to Boost.Log as a whole. I would even say > it's misleading in some parts - in particular: "Loggers are collections > of Sinks" and "Think of channels as a Sink-level observer". Fair response. I think a more general way for me to classify my response/concern (instead of providing a loosely worded example) would be: "Which class does what and how do the classes relate to each other?" Right now answering that question results in a decent exploration of Boost.Log's code and documentation. It would have been useful to me, and likely future developers, to have the classes that comprise Boost.Log summarized so that conceptual map could have been more easily formed without having to dig in to the actual headers. Something similar to the contents of the Definitions page, but with architectural clues. http://boost-log.sourceforge.net/libs/log/doc/html/log/defs.html As an example, expanding on the Sinks definition from above: > Log Sink: A target, to which all log records are fed after being collected from user's application. It is sink's nature that defines where and how the log records are going to be stored. Maybe include something as brief as: > With a Log Sink, developers can modify the filtering and add additional backends. I consider myself a modestly competent user of boost, but still am getting parts of this wrong after over three months of using/digging in to Boost.Log. >> A hindsight 20/20 architecture and terminology for Boost.Log could be >> simplified in terms of: > > What is "20/20"? I'll continue my answers assuming that the following > was your understanding of the current Boost.Log architecture. Correct. The contents of this email has evolved from sometime around mid-January or whenever I learned that Boost.Log was going to be reviewed and accepted. It also crudely mirrors my understanding of the library as I went through the development process of utilizing the library. >> *) Log Record pre-conditions. Sinks control whether or not a Log >> Record is to be generated > > Looks like you're confusing sinks with filters. Also, don't forget about > the global filter. I became sloppy with my terminology. Filters are stored in Sinks and the Global core. Speaking of filters, yesterday I stumbled across a feature request: > Program received signal SIGABRT, Aborted. > 0x00007fff81de2fe6 in __kill () > (gdb) bt > #0 0x00007fff81de2fe6 in __kill () > #1 0x00007fff81e83e32 in abort () > #2 0x00007fff81e03de2 in _Unwind_Resume () > #3 0x00000001000a3b1c in main (argc=1, argv=0x7fff5fbff338) at /tmp/foo.cc:267 If I wrap everything in a boost exception, I get: > exception: /usr/local/include/boost/log/filters/attr.hpp(134): Throw in function (unknown) > Dynamic exception type: N5boost16exception_detail10clone_implINS0_19error_info_injectorINS_12log_mt_posix13missing_valueEEEEE > std::exception::what: Requested attribute value not found It'd be nice if the error message were able to somehow include the string representation of the value (attribute) it wasn't able to find. Turns out it was a type-o so I had an unregistered attribute, but the type-o would've been very easy to identify if it were included in the error message someplace (instead it took a fair amount of manual investigation and backtracking to figure out it was a filter searching for an attribute that didn't exist). [snip useful responses/corrections ] >> Observers could then be placed on Sinks that would stamp Log Records >> with Severities, or Channels, or in whatever hodge-podge >> configuration the developer wanted and such examples would be very >> cookbook. > > Now that you presented a code snippet, your suggestion makes more sense > to me. Let me express my thoughts on it in two parts: > > 1. Custom log records. Yes, the model of "mandatory" attributes look > promising. It could, at least, partially solve the problem of possible > library misconfiguration that was highlighted in another review. I > imagine that some kind of log record prototype (or factory) should be > defined by the user in order to be able to construct log records with > the specific set of attribute values. Filters and formatters could then > request these mandatory attribute values without having to worry about > their absence. Lookup performance may also be higher, but I doubt it > will be compile-time. The idea is quite vague now but after some > thinking over it might become a good addition to the library. > > 2. Designing sinks (and the core, I presume) after the log records. No, > that looks unacceptable to me, at least for what Boost.Log tries to > achieve. This would introduce too much coupling between the logging side > of the library (which tends to be exposed to many parts of the > application) and the consuming side (which tends to be configured in a > single place of the application). To my mind, these sides of the library > should be maximally decoupled. Also, it's not clear how to support > multiple log record types in such a design. >> *) Global loggers vs. per-object references to singletons > > Not sure I understand. Is it better to have global objects that reference singletons: > typedef boost::log::sources::severity_channel_logger_mt<levels::severity_level> logger_t; > > BOOST_LOG_DECLARE_GLOBAL_LOGGER(default_log, logger_t); > BOOST_LOG_DECLARE_GLOBAL_LOGGER_CTOR_ARGS(stats_log, logger_t, (boost::log::keywords::channel = "stats")); or per object references to logging singletons: > typedef boost::shared_ptr< boost::log::sinks::synchronous_sink< boost::log::sinks::text_ostream_backend > > console_sink_t; > typedef boost::shared_ptr< boost::log::core > logger_core_t; > > struct my_obj { > my_obj(logger_core_t& logger) : lg(logger) {} > void foo() { BOOST_LOG(lg) << "log msg"; } > logger_core_t& lg; > } > > int main() { > console_sink_t cerr_sink; > cerr_sink = boost::log::init_log_to_console( > std::cerr, > boost::log::keywords::filter = boost::log::filters::attr< int >("Severity") >= warning, > boost::log::keywords::format = "%TimeStamp%: %_%", > boost::log::keywords::auto_flush = true); > my_obj o(boost::log::core::get()); > o.foo(); > } ... I think that example's right. >> *) Channel severity loggers example > > That example wouldn't be much different from the ones in sections about > severity_logger or channel_logger. But I'll add a code sample. Where I spent time with this was figuring out how multiple chan severity loggers interacted with the core and how my app was supposed to interact with the distinct loggers, which were linked in to the core, behind the scenes. > typedef boost::log::sources::severity_channel_logger_mt<levels::severity_level> logger_t; > BOOST_LOG_DECLARE_GLOBAL_LOGGER(default_log, logger_t); > BOOST_LOG_DECLARE_GLOBAL_LOGGER_CTOR_ARGS(lg1, logger_t, (boost::log::keywords::channel = "chan1")); > BOOST_LOG_DECLARE_GLOBAL_LOGGER_CTOR_ARGS(lg2, logger_t, (boost::log::keywords::channel = "chan2")); > #define LG1_WARN BOOST_LOG_SEV(lg1::get(), log_severities::warn) > #define LG1_INFO BOOST_LOG_SEV(lg1::get(), log_severities::info) > ... > LG1_INFO << "info msg"; >> *) Setting up an initial console logger as >> line one in main() > > Hmm. Ok, I'll add something about that to the tutorial. Easy to do (see above), but I didn't see anything that said, "it would be wise to do this first and then remove your console sink after you setup your logging environment." Initially I disregarded the init_to_console() convenience functions while reading the docs, and it wasn't until I started dealing with error messages that weren't being logged to a file because my logging setup routines hadn't been completed (or had failed for some reason due to FS perms), that I suddenly took note of needing to get console logging working first. >> *) Changing a backend filter at a later date > > Just call set_filter on the backend, that's all. This was one of the areas where there were lots of ways that I could do it, but I couldn't tell which was the right way. libs/log didn't suggest a preferred mechanism or right way to do it. >> *) Using async logging for INFO level logs, but switching to sync for >> CRIT errors. > > You can register two sinks - one synchronous and one asynchronous, and > set their filters accordingly. Ah, clever way of handling that. >> *) Obtaining the severity of a particular logger > > You mean, the default severity? There's no public API for this, but > there's a protected function default_severity in the logger feature. Why > would you need it? Internally you're using spirit for log record filtering, so it's impossible from what I can tell to do that inside of Boost.Log. Having a way of poking at a sink to obtain information about its runtime status. Using the above console sink as an example: > typedef boost::shared_ptr< boost::log::sinks::synchronous_sink< boost::log::sinks::text_ostream_backend > > console_sink_t; > console_sink_t cerr_sink; > cerr_sink = boost::log::init_log_to_console( > std::cerr, > boost::log::keywords::filter = boost::log::filters::attr< int >("Severity") >= warning, > boost::log::keywords::format = "%TimeStamp%: %_%", > boost::log::keywords::auto_flush = true); > > std::cout << "Current Severity Level: " << /* or something like this */ cerr_sink->filter_severity() << std::endl; I ended up adding this to my application's surrounding code. >> *) How do you remove log events given a severity level at compile >> time. Currently this isn't explicit defined in the documentation >> like it is in Google's glog library: >> >> http://google-glog.googlecode.com/svn/trunk/doc/glog.html#strip > > The library has no direct means for that. Users can conditionally define > their logging macros, based on BOOST_LOG_SEV or pure C++ interface and > then enable or disable the particular logging statements from the source. *nods* I just didn't see anything in the docs to do this, which is why I ended up with the practice: > #ifdef RELEASE > # define LG1_WARN BOOST_LOG(null_log::get()) > #else > # define LG1_WARN BOOST_LOG_SEV(lg1::get(), log_severities::warn) > #endif null_log always filters everything sent to it. Probably less than ideal, but I couldn't think of a better way to handle this. >> *) Is there a way to set a bit in a Log Record that overrides a >> Sink's filter? For instance, there are certain events that I want to >> make sure go to the console 100% of the time without changing the >> severity of the log message. Do I just log twice? It'd be keen if >> Log Records could have a bit that could be set and would override a >> filter. >> >> bool log_to_console = true; BOOST_LOG_SEV_CONS(lg, warning, >> log_to_console)<< "my message"; > > You can set an attribute (say, "Emergency") for that record, and setup > filters so that whenever this attribute is present, the record is passed > on to the console backend. You mean a scope attribute? > boost::shared_ptr< attrs::mutable_constant< bool > > console_attr(new attrs::mutable_constant< bool >(false)); > lg.add_attribute("Console", console_attr); > BOOST_LOG(lg) << "Console is false by default"; > > { > BOOST_LOG_SCOPED_THREAD_ATTR(lg, "Console", true); > BOOST_LOG(lg) << "Console is true"; > } > > BOOST_LOG(lg) << "Console is false again"; Like that? >> *) It should be noted that the internal async log message queuing >> mechanism uses a vector and during very bursty logging activity that >> the vector can grow large in size and doesn't ever reduce in size. >> This is a known limitation and the use of a vector was chosen to >> facilitate atomic append operations for log records. Using a >> std::deque would be preferred for bursty applications that way space >> could be reclaimed easier, but as Andrey pointed out, it would >> require a full mutex which would reduce the performance of the >> library. > > There is no vector in the async frontends. The problem with the current > queuing mechanism is not the storage strategy but the lack of queue > boundaries. But I agree, I should have drawn attention to this aspect in > the docs. Will do. *nods* I brought this up in a private email w/ you and was satisfied with your answer, but thought it worth noting for others. As for the frontends having their own queue, with the way that async frontends work and their feed_records() call, I'd assumed the backend used a time-based mechanism to come by and pick up the log records stored in per-frontend TSS queues. Something where frontends atomically pushed records on, and the backend would atomically swap() the list of records off for sorting and processing by the backend. Just a point of confusion after reading: http://boost-log.sourceforge.net/libs/log/doc/html/log/detailed/sink_fronte… and I never dove in to the source to investigate further. >> *) I find the argument against Lazy Streaming of attributes to be >> weak. >> >> Current BOOST_LOG() expands to a for() loop where the contents of >> the for() loop aren't executed unless a Sink in a Logger accepts the >> record. >> >> So why can't Log Records have compile-time attributes that can be >> populated with typed attributes in a stream? >> >> And then be able to extract the compile-time attribute in a backend: > > Just as it is said in the rationale - the streaming expression is _not_ > executed until _after_ the filtering is done. And filtering already > involves attribute values, so there's no way to use these attribute > values you specified in the streaming expression. Besides, after the > view of attribute values is constructed, it is immutable, so nothing can > be added after the filtering is done. That's why I make the distinction between "log record preconditions," attributes that can be used in a filter, and "attributes," which is a catch-al term for data stored in a Log Record. I agree that it is impossible for streamed attributes to be used as preconditions, but streamed attributes act as an extremely convenient (from a syntax perspective) way of passing data to a backend for processing. >> *) Dovetailing on the above two points, a flush bit for a given Log >> Record would be very nice as well. 99.999% of the time async logging >> is desired, but in the 0.001% of the time when a Log Record must get >> out to disk, chances are that one Log Record every blue moon is >> disproportionally valuable compared to the normal Log Record. Having >> a flush() that doesn't return until the backend has fsync(2)'ed data >> would be really spiffy. >> >> BOOST_LOG_SEV(lg, warning)<< "My message"<< lg::flush; > > As I already noted, your mileage is too biased, at least. I, personally, > tend to use synchronous logging. But I do recognize that some kind of > flushing ability would be nice in case of async logging. I like the idea of using both async and sync sinks. It leaves me with a few questions, however: How does that work if they're both using the same text file backend? Will log entries still be ordered? > typedef boost::log::sinks::text_file_backend backend_t; > typedef boost::log::sinks::ordering_asynchronous_sink< backend_t > sink_t; > boost::shared_ptr<sink_t> sink(new sink_t( > boost::make_shared< backend_t >(), > keywords::order = logging::make_attr_ordering("LineId", std::less< unsigned int >()), > keywords::ordering_window = boost::posix_time::seconds(1))); Thanks again in advance. -sc -- Sean Chittenden sean(a)chittenden.org

2 1

[SoC] Summer of Code Project Ideas
by Andrew Sutton 13 Mar '10

13 Mar '10

I'm officially soliciting ideas for student projects for this year's 2010 Summer of Code. If you're maintaining or contributing to a library and have some non-trivial items on a TODO list, then suggesting that as a possible student project may be a viable idea. Unlike the previous years, I think that proposing work on sandbox libraries would also be a good idea. There is a substantial amount of work in the sandbox that might be well-suited for student projects and eventual (I hope) acceptance to Boost. In general student projects should be tightly focused with a clear set of goals to getting their work integrated into a mainline development branch (be that trunk or sandbox). In general, we've noticed that ground-up libraries almost always fail to be integrated or released independently since they require a commitment longer than the summer. There are, of course, notable exceptions to this rule. If you are going to propose a student project, please keep in mind the following things: 1. Students tend to go away in the fall. 2. If their work isn't tended after August, then it's largely forgotten 3. If the student is gone and their work is forgotten, then the project didn't really succeed. If you write down or submit a project, please include your expectations for that work. And try to keep it small. That said, if you're too precise in the specifications, we'll going to get a couple dozen proposals that simply reiterate your expectations. But that's the nature of the beast. Good ideas for projects might be: == Data Structures and Algorithms== Admittedly these have little impact on overall quality of Boost, but make a nice sandbox for students to work in and can result in surprisingly good code. Over the course of the summer 1 or 2 related data structures or a family of related generic algorithms seems to make a nicely packaged project. ==Extensions for Existing Libraries== There are a number of Boost libraries that are very amenable to extension (e.g., BGL, GIL, Math, etc.). Basically any library that doesn't have a finite feature space. Non-intrusive changes (i.e., those that don't require hacking on the existing bits) typically make good summer of code projects. == Infrastructure Projects== Projects that aren't part of Boost, but help us improve the quality of Boost might make decent projects, but we've never had one proposed or accepted that I'm aware of. Remember, we can't accept documentation projects so "Write my documents" will not be a good student project (unfortunately ;) ==Applications of Boost== This is a little different... It might be a good idea to have students build real (example?) applications that use the Boost C++ Libraries. There are a number of real benefits to having students work in this space. First, these applications are very obvious clients of Boost. They can provide immediate feedback on issues with the interface, usability, correctness, performance, documentation, etc. Second, they might make really good examples of best practice for using Boost. Third, they probably make nice student projects. If you have any ideas, let's hear them. And remember, funded projects need mentors. Andrew Sutton andrew.n.sutton(a)gmail.com

10 42

[log] Boost.Log Review...
by Sean Chittenden 13 Mar '10

13 Mar '10

YES, the Boost.Log library SHOULD BE ACCEPTED in to the Boost release distribution. Summary: *) Boost.Log isn't perfect and after having reviewed most of its alternatives, and having recently converted from using glog, I like the utility and architecture provided by Boost.Log the most. It comes close to solving all logging problems for everyone. Closing the gap of solving the last 5% between what Boost.Log does and what I ideally wanted was tedious and required me to develop a much higher level of understanding that I would have liked, but it was possible. *) In solving all logging problems for all people, Boost.Log's documentation is quite abstract. *) I would like to see the design of templates/classes flipped so that the starting point for interacting and beginning to use Boost.Log begins with customizing Log Records and ends with defining backends and backend filtering. This is a fundamental design choice, however and one that I'm willing to accept given the value that Boost.Log provides. *) I've been saving most of this feedback for the better part of two months now so excuse the length and rambling. Certain points of the library I struggled with and ultimately ended up begrudgingly resigned myself to accepting as "the way it is" vs. "the way it should be." *) My perspective on the Boost.Log is framed by the recent use of Google's glog library and in a previous life having written performance-oriented, binary logging libraries for high TPS systems (only in C, however, not C++). > - What is your evaluation of the potential usefulness of the library? Boost.Log quite useful and has the highest promise of any logging library that I am aware of because of its ability to accommodate the following common use case: Support asynchronous logging from multiple frontend threads with a backend able to order the output and send different messages to different files. If it weren't for the ability of this library to meet that specific design requirement, I would still be using Google's glog library. > - What is your evaluation of the design? The design is very modular. Too modular. So much so that the flexibility and required understanding is actually a barrier to entry to make use of the library (i.e. now that I'm using the library, I know more about the innards of Boost.Log than I would like or think is reasonable). After using this library for several months now, I have distilled a quick summary for those coming up to speed on how to use Boost.Log and its components. This is specific to how I'm using Boost.Log, but I think this is the desired use-case for most users of Boost.Log (esp since this is the common path for users of ASIO). - Your application is littered with Log Statements that are tagged with different Severity Levels - Log Statements consist of a Logger (a collection of Sinks), a Precondition (e.g. a severity) and Log Record instance data (most commonly a message) - Loggers are collections of Sinks (e.g. a file and the console) - Loggers conditionally accept Log Records if one of a Logger's Sinks returns true for a Precondition (e.g. only create a Log Record if the log statement's Severity Level greater than or equal to the Severity Level configured in the Sink) - Instructions required to create a Log Record won't be executed if a Sink doesn't accept a Log Record - Sinks can be configured to queue accepted Log Records (e.g. async frontends) before passing them to one or more Backends for printing (e.g. console text file, SNMP trap) The Boost.Log system can be configured to mutate individual Log Records through the manipulation of the following three types of information: - Channels represent a way of tying together a collection of related systems (e.g. security, network, application). Think of channels as a Sink-level observer that stamps the channel on a Log Record. - Severities represent the importance of a message (a Log Statement precondition that a Sink-level Observer could stamp a Log Record) - Attributes represent per-Log Record information (a string key/value in a Log Record instance) Backends can then format the output based on the Attributes of a particular Log Record. The above wasn't explicitly distilled in the documentation in a single place, but I think future developers would find it very useful to see that spelled out explicitly. Given the extremely modular design of the library, I understand why the docs are the way they are and know that some of this is touched on in the Design Overview, but until I became very competent with the library, the documentation seemed too abstract. Despite the importance of logging, becoming a logging expert was tangential to the problem I was trying to solve and I would have personally found the above summary very useful. While glog is a supper thin logging API, Boost.Log feels like a complete and modular logging system. In glog, seeing: VLOG(3) << "asdf"; Where 3 can/was a #define, the system ended up feeling very arbitrary and unstructured. A hindsight 20/20 architecture and terminology for Boost.Log could be simplified in terms of: *) Log Record pre-conditions. Sinks control whether or not a Log Record is to be generated *) Loggers. A container for zero or more Sinks *) Sinks. A frontend that queues Log Records *) Sink Compile-Time Attributes/Observers. Observers that are configured at compile time, augment Log Records, and stamp Log Records as they pass through the Sink (e.g. severity, channels, etc) *) Backends. A formatter that orders and writes Log Records from Sinks *) Log Records. A container of information that is populated by the user's application, Sinks and Backends (possibly Loggers as well) *) Log Record Compile-Time Attributes. Compile-time members of a Log Record struct *) Log Record Runtime Attributes. Key/Value members of a Log Record stored in a std::map (currently how Attributes are implemented) I'd imagine most developer would want async messaging between Sinks and Backends. Those that don't, could make use of a Sink Compile-Time Attribute that always sets the flush bit on a Log Record. > - What is your evaluation of the implementation? Generally speaking the internals of the implementation is pretty clean, especially given the size and various ways that Boost.Log can be cobbled together. Also in hindsight: the developer interface for interacting with the library could be improved by making Log Records the fundamental unit that everything hangs off of. Making log records easy to extend containers that carry domain specific information without std::map seems like a better design choice given how frequently developers will interact with Log Records. The use case of having log records that maintain stats that get pumped through a logging system struck me as particularly useful, but unnecessarily expensive with std::map. As was noted in other reviews, the cost of evaluating whether or not a Sink is going to accept a Log Record is of some concern. Figuring out a way to have the Log Record preconditions evaluated as quickly as possible should be important given the frequency at which logging code is/should be deployed in most applications. I remember reading someone else's benchmark saying that it was ~2500 instructions to evaluate whether or not a Sink should accept a given Log Record. For something that should macro expand to: for (logger::iter = logger.begin(); iter->accept(severity); ++iter) iter->stream() I haven't profiled, but when most accept() functions are doing: inline bool accept(SevT s) const { return s >= sev_filter ? true : false; } 2500 ops seems expensive to me. The notion of a "global logging core" bothers me. Having singletons of loggers and sinks in TSS is very good from a utility perspective. Admittedly I don't know how the global logging core is used beyond being a nob that can be turned to enable/disable logging, nor have I profiled it yet, but any centralized core bugs me in a highly threaded environment. Questions: Why does Boost.Log roll its own TLS/TSS support? boost/log/detail/thread_specific.hpp vs. boost/thread/tss.hpp There may be a very good reason, I just didn't see it when I was looking through the library. Can Log Records be pool managed somehow? *) Log Records I understand why std::map is used to store attributes (ease of use/flexibility), but at the same time, I do wish that frequently stored attributes could be baked in at compile time. This is my biggest gripe with the library, actually. I would like my application to err on the side of making use of compile-time information at the expense of the time required for compiling the source. Storing things in a std::map seems lazy and brutish, for the lack of a better description. Flipping things on its head so that Log Records define Loggers, Sinks and Backends would be ideal, IMHO, and would solve most of my gripes. This is a design decision, but the contents of Log Records is of more importance than the backends. Boost.Log appears to be designed from Backends to Log Records vs. Log Records to Backends, which is the way data flows through an application (this would be my preference). For example: // quick pseudo-code using MI to create my_log_record and downstream types typedef enum { info = 0, warn = 1, crit = 2 } severity_t; struct my_log_record : boost::log::record::attribute::map< std::string, std::string >, boost::log::record::attribute::severity< severity_t >, boost::log::record::attribute::message, boost::log::recordmy_app::log_record::attribute::src_port {}; typedef struct my_log_record log_record_t; typedef SinkT< log_record_t > sink_t; typedef LoggerT< sink_t > logger_t; typedef BackendT< sinkT > backend_t; Observers could then be placed on Sinks that would stamp Log Records with Severities, or Channels, or in whatever hodge-podge configuration the developer wanted and such examples would be very cookbook. *) Log Records are highly reused and seem like ideal candidates for a TLS freelist. > - What is your evaluation of the documentation? Pretty complete, albeit abstract. Lacks examples for customized records and a best practice guidelines. A few other suggestions for things that I had to hunt down or figure out: *) Global loggers vs. per-object references to singletons *) Channel severity loggers example *) Setting up an initial console logger as line one in main() *) Changing a backend filter at a later date *) Using async logging for INFO level logs, but switching to sync for CRIT errors. *) Obtaining the severity of a particular logger Outstanding doc questions: *) How do you remove log events given a severity level at compile time. Currently this isn't explicit defined in the documentation like it is in Google's glog library: http://google-glog.googlecode.com/svn/trunk/doc/glog.html#strip *) Is there a way to set a bit in a Log Record that overrides a Sink's filter? For instance, there are certain events that I want to make sure go to the console 100% of the time without changing the severity of the log message. Do I just log twice? It'd be keen if Log Records could have a bit that could be set and would override a filter. bool log_to_console = true; BOOST_LOG_SEV_CONS(lg, warning, log_to_console) << "my message"; Other comments: *) It should be noted that the internal async log message queuing mechanism uses a vector and during very bursty logging activity that the vector can grow large in size and doesn't ever reduce in size. This is a known limitation and the use of a vector was chosen to facilitate atomic append operations for log records. Using a std::deque would be preferred for bursty applications that way space could be reclaimed easier, but as Andrey pointed out, it would require a full mutex which would reduce the performance of the library. *) I find the argument against Lazy Streaming of attributes to be weak. http://boost-log.sourceforge.net/libs/log/doc/html/log/rationale/why_not_la… Current BOOST_LOG() expands to a for() loop where the contents of the for() loop aren't executed unless a Sink in a Logger accepts the record. From: boost/log/sources/record_ostream.hpp #define BOOST_LOG_STREAM_WITH_PARAMS_INTERNAL(logger, rec_var, params_seq)\ for (BOOST_LOG_AUTO(rec_var, (logger).open_record((BOOST_PP_SEQ_ENUM(params_seq)))); !!rec_var; rec_var.reset())\ ::boost::log::aux::make_pump_stream((logger), rec_var) So why can't Log Records have compile-time attributes that can be populated with typed attributes in a stream? BOOST_LOG_SEV(lg, warning) << "My log has an attribute src_port" << log_record_t::set_src_port(conn.src_port) << " this continues to append to the Log Record's message"; And then be able to extract the compile-time attribute in a backend: // Dashed out pseudo-code to make a point (I know the syntax is garbage in the src_port's formatter). typedef struct backend : boost::log::record::base_record { typedef int src_port_type; int src_port; } record_t; typedef boost::log::sinks::text_file_backend< record_t > backend_t; b->set_formatter( fmt::stream << fmt::attr<unsigned int>("LineId", keywords::format = "%08x") << " Src Port: " << fmt::attr< record_t::src_port_type >(record_t::src_port) ); *) Dovetailing on the above two points, a flush bit for a given Log Record would be very nice as well. 99.999% of the time async logging is desired, but in the 0.001% of the time when a Log Record must get out to disk, chances are that one Log Record every blue moon is disproportionally valuable compared to the normal Log Record. Having a flush() that doesn't return until the backend has fsync(2)'ed data would be really spiffy. BOOST_LOG_SEV(lg, warning) << "My message" << lg::flush; As is, you have to call: sink->feed_records(::boost::posix_time::seconds(0)); which isn't as elegant and I don't believe actually signals to the backend that data needs to be flushed to disk (it simply drains the frontend). Developers that want synchronous logging could define an observer that always sets the sync bit and would almost certainly be optimized away at compile-time. > - Did you try to use the library? With what compiler? Did you have any problems? FreeBSD 7+ and Darwin. GCC 4.2.1, gcc 4.3 gcc 4.4. TIP in subversion has been working well for me. RC4 was problematic due to bjam configuration problems. > - How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? Developed a reasonably in-depth understanding of the internals and its use. > - Are you knowledgeable about the problem domain? Sufficiently adept in the problem domain. Parting thoughts: Like I said in the first paragraph, this library should be accepted in to Boost because it's the best that I've evaluated and see available on the landscape. My compliments to Andrey, and likely Trojo as well. All of my critical feedback is hindsight 20/20 after having successfully integrated Boost.Log in to my application. I am happy with Boost.Log though do see room for improvement in the future. Forward thinking: The more times I have to tweak and revisit logging, for whatever reason, the more convinced that a better and more elegant design would result if Backends, Sinks, et al were defined in terms of Log Records. If there is a Boost.Log2, I would love to see the architecture flipped on its head as suggested. I believe such an architecture would: *) improve the evaluation of a Sink's preconditions for accepting/creating a new Log Record *) allow Log Records to contain bits that are set by observers and are propagated through a Log Record's life-cycle back to the Backends *) result in easier application specific logic (e.g. flush or console redirection) *) improve performance when preconditions are evaluated *) improve performance because fixed sized Log Records could be memory managed on thread specific pools *) allow observers to be chained together components that would be easier to setup and manipulate; and *) could be used to allow data to stream to a backend (namely application stats) Further, by constraining the scope of what Boost.Log is capable to a more rigid/fixed architecture that gets optimized at compile time, the library would be easier to understand and use (e.g. change the design so that not all Sinks or Backends accept all Log Records). Hopefully someone finds this retrospective useful in the future. -sc PS I started to put my money where my mouth is and cobbled together something that crudely demonstrates Log Records -> Backends, but came up short when getting streaming attributes to work due to a lack of time available to focus for getting an overloaded operator<<() to work. The sample can be found here if anyone is interested. Discussions of this should be taken offline since it's tangential to the current Boost.Log review process. http://codepad.org/8ACp0obH -- Sean Chittenden sean(a)chittenden.org

2 1

Status of (boost) lockfree?
by Emil Dotchevski 13 Mar '10

13 Mar '10

I decided to give the lockfree library that's currently in the review queue a try. On MSVC 9.0, I'm getting this error: boost\lockfree\detail\cas.hpp(129) : error C2440: 'reinterpret_cast' : cannot convert from 'const boost::uint64_t' to 'LONGLONG' The compiler then continues to say: Conversion is a valid standard conversion, which can be performed implicitly or by use of static_cast, C-style cast or function-style cast Am I missing a configuration macro, or is this a valid compile error? Emil Dotchevski Reverge Studios, Inc. http://www.revergestudios.com/reblog/index.php?n=ReCode

4 5

[serialization] portable non-floating-point binary library.
by Mostafa 13 Mar '10

13 Mar '10

Hi all, If adding floating point support to portable binary serialization is so hard/time-consuming, why not just have a portable non-floating-point binary library in boost as an intermediate step? Surely it would be more convenient for the community, instead of having to build in or make a library out of the files in https://svn.boost.org/trac/boost/browser/trunk/libs/serialization/example. (I did search the archives and couldn't find any answers, if I missed some threads please point them out.) Thanks, Mostafa

1 0