Re: [boost] [Log] Review Results

Subject: Re: [boost] [Log] Review Results
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2010-03-11 12:35:16

On 03/11/2010 01:04 PM, Roland Bock wrote:
> Andrey Semashev wrote:
>>> Is there a way to have several sinks with different filter but
>>> sharing the log records?
>>
>> That's an interesting idea, not very simple to implement though. The
>> problem is that some records can pass filtering for some of the sinks
>> and not the others, while the sinks may share the formatter. Further
>> on, formatting of the same log record for different sinks may occur in
>> different threads. I'll add this feature to the TODO list, I need some
>> time to think about it.
>
> I understand that it is difficult in all generality. Since it is an
> optimization, maybe it could be implemented for certain cases only? For
> instance restrict it to sinks which live in the same thread?

I'd like to avoid such non-obvious restrictions. I'm thinking of some 
kind of thread-local storage for each shared formatter. It would have to 
cache the record and the result of its formatting in this storage, so 
that it could format the record only once, no matter how many times it 
is invoked for it. The problem is that it's not clear when to clean the 
cache.

> The warnings for the code attached to the original posting are attached
> to this mail. Compile options are:
>
> -Wall -Wreorder -Wnon-virtual-dtor -Wno-non-template-friend
> -Woverloaded-virtual -Wsign-promo -Wextra -fvisibility=hidden
>
> There is a ticket for the date_time stuff, already. Currently I have to
> fix that by hand with each release...

Ok, I'll look into it.

>> If you don't want exceptions to be thrown, you can use things like
>> flt::has_attr, std::nothrow in filters/formatters and exception handlers.
>
> I don't mind exceptions. The main issue from my point of view is: No
> critical message must be lost. If I log a message I want to be pretty
> sure that it is logged somehow. If the sinks fail and exceptions are
> thrown, currently, the message is lost. It would be unreasonable for me
> to add a try/catch statement to each log statement.
>
> Maybe the message could be added to the exception? Or maybe the user
> could provide a callback that would be called in case of an exception?

Exception handlers allow to inject such callbacks in sinks, core and 
loggers. On a corner case, the callback can suppress all or some exceptions.

> Not sure now, but messages must not be lost by the log system.

I think, it might be a good idea to attach the record to the exception 
by means of Boost.Exception.

>> Can you point me to the particular sections that were difficult to read?
>
> Examples with a short explanation, why I think I had difficulties.
>
> - core: cite: [This section contains a more detailed description of
> library components and features. Some of them are presented in the
> Tutorial section...]
> This may be one of the main reasons for me to have some trouble. When I
> wrote that mini test program, I found myself continuously jumping from
> tutorial to details and back again.

Ok, I'll remove that as it looks like it doesn't bring any useful 
information anyway.

> - sink_frontends:
> A mini summary with mini sample code would be helpful as introduction:
> What do I do with sink frontends?
>
> Construct
> Add filters
> Add backends
> Add attributes? <-- can I ?
> Hand over to core

Hmm, there are code samples for every sink frontend, and every sample 
contains the steps needed to setup a sink, including filters, formatters 
and adding to the core. Do you think that's not enough?

> - utility: The init_log_to_file convenience function is mentioned in
> examples several times but never with a pointer to the utility section.
> The missing links to other sections might be a reason for me not to have
> really read the utility section. In fact I did not think I'd need it.

Ok, I'll add references.

>> I don't think adding namespaces and includes to examples in the
>> readable documentation is a good idea. As you noted, these examples
>> should be brief and free of such noise. However, I will reorganize the
>> docs, so that the code samples will be taken from compilable external
>> files.
>
> Oh, I did not mean to include the "noise". No the examples are fine per
> se. But it would be very helpful to have a link to a complete/compiling
> sample program at the end of each tutorial section.

Will do. I wanted to play around with quickbook some more anyway. :)

>>> - I understand that I can use my own set of severity levels. It is
>>> well documented how to filter messages using these severity levels.
>>> But I have no idea how to format messages with these severity
>>> levels? I do not want the number, I'd like a string, of course.
>>> I looked it up in the trivial.hpp, but it should be part of
>>> the documentation.
>>
>> It is described in the formatters section:
>>
>> http://tinyurl.com/yh3r7ue
>>
>> All you have to do is to define operator<<. The approach is also
>> demonstrated in examples.
>
> OK, would be cool to have a pointer to that section from here, for
> instance:
> http://boost-log.sourceforge.net/libs/log/doc/html/log/tutorial/attributes.html#log.tutorial.attributes.commonly_used_attributes

Ok, will do.

>>> - Maybe I missed it, but I did not find an overview of the log
>>> rotation options, including a description of the placeholders in
>>> strings.
>>
>> http://tinyurl.com/ygpxtgc
>
> That link seems to be damaged. It did not forward me to the real
> destination.

Here's the full link:

http://boost-log.sourceforge.net/libs/log/doc/html/log/detailed/sink_backends.html#log.detailed.sink_backends.text_file

>> The functions and their arguments (including named ones) are described
>> in the Reference section. That is the formal interface description.
>> The more expanded description with code samples in the Detailed
>> features description. If you found inconsistencies or something
>> missing in particular, I'll be glad to fix it.
>
> OK, maybe it would be sufficient to add links into the reference section?
>
> My problem is that I often found myself in the situation described above
> (difficulties): I am not sure if I have all the information I need. And
> I am not sure how to find out. Brief introductions with usage patterns
> in the detail-section would help a lot, I guess.

Ok, I'll try to do so. Adding links to the auto-generated reference is 
not a very obvious thing to do.