Boost Loogging v2 Hi all, It's been a while - I admit, and I apologize for it. Well, finally, I'm working on version 2 of Boost Logging, taking into account your suggestions when the first version was rejected. The extra short version: It's in alpha stage. Get it from here: http://torjo.com/log2/ Without further ado, I'll present you Boost Logging Library v2, with - a much nicer separation of concepts and - a much more flexible interface. - you don't pay for what you don't use. - fits a lot of scenarios: from very simple (dumping all to one log) to very complex (multiple logs, some enabled/some not, levels, etc). - you can now define your own LOG_ macros Here are 2 small examples to show you a bit of v2's power: ----------------- Example 1: struct write_to_cout_and_file { ... }; // defining the logs logger<write_to_cout_and_file, manage_enabled_no_ts> g_single_log("out.txt"); #define L_(x) if ( g_single_log) g_single_log.process_msg()(x) // code L_("reading word " + word); ----------------- Example 2: struct write_to_file { ... }; struct write_to_cout { ... }; struct write_to_dbg { ... }; // defining the logs typedef process_msg< ostream_like_return_str<>, write_to_cout> processor_cout; typedef process_msg< ostream_like_return_str<>, write_to_file> processor_file; typedef process_msg< ostream_like_return_str<>, write_to_dbg> processor_dbg; logger<processor_cout, manage_enabled_no_ts> g_log_app; logger<processor_file, manage_enabled_no_ts> g_log_err("err.txt"); logger<processor_dbg, manage_enabled_no_ts> g_log_dbg; #define LAPP_ if ( !g_log_app) ; else g_log_app->read_msg().gather().out() #define LERR_ if ( !g_log_err) ; else g_log_err->read_msg().gather().out() #define LDBG_ if ( !g_log_dbg) ; else g_log_dbg->read_msg().gather().out() // code LAPP_ << idx << " : reading word " << word; LERR_ << "error at " << idx << ", while reading " << word; LDBG_ << "debug info: " << idx << ", reading " << word; ----------------- The above was the short version. You can also look at the test_*.cpp files, to see some more examples of how you can use the library. Download it here : http://torjo.com/log2/ Long version follows: First, a bit about the workflow: Step 1: Filtering the message Step 2: Gathering the message Step 3: Writing the message Step 1: Filtering the message In order to be efficient, before anything happens to the message, we see if the log it's written to, is enabled. If so, we process the message. If not, we ignore all of the message. This is rather easy, with constructs like this: #define L_(x) if ( g_single_log) g_single_log.process_msg()(x) #define L_ if ( !g_log_app) ; else g_log_app->read_msg().gather().out() Step 2: Gathering the message Now, that we know the log is enabled, all the message is gathered. This depends on how you write the message. For instance, you can gather it in one step, if you want to offer a syntax like this: L_("this is my message"); Or, you can offer syntactic sugar: i = 100; L_ << "this is " << i << " times better that the average bear... "; In this case, you'll gather all info in a stream of some kind. Or, you can have more data besides the message string, like: module name, severity of message, category, etc: L_(fatal,"chart","Can't find the ChartX control"); Step 3: Writing the message Now all info about the message is gathered. You can write it to its destination(s). What you wanna do with a message, is completely up to you. The library will offer you possibilities. You can go for the extremely easy way, and just have a functor which dumps the message somewhere, like this: struct write_to_cout { void operator()(const std::string & msg) const { std::cout << msg << std::endl ; } }; Or: struct write_to_file { typedef boost::shared_ptr<std::ofstream> ptr; write_to_file(const std::string & filename) : m_out(new std::ofstream(filename.c_str())) {} void operator()(const std::string & msg) const { (*m_out) << msg << std::endl ; } mutable ptr m_out; }; Or, you can choose to Format and/or write your message to Destinations (these will be explained later) Download it here : http://torjo.com/log2/ ------------------------------------------------------ Logger objects For each log you want, you'll have a logger object. Note that "log" is a concept - several logs can write to the same file and/or one log can write to multiple destinations. I use the term "log" to identify a type of log message you want to write -- for example, you can have a "debug log" for writing debug messages; an "info" log, for writing informations, and so on. The fact that they might end up writing to the same destinations, is completely transparent to the user, as it should. A logger object contains 2 things: - a filter: an is_enabled() function - to find out if it's enabled. - a process_msg() object - this contains the logic of what to do with the message, if the log is enabled. The 2 concepts are orthogonal - Andrei would call them "policies" ;) The process_msg() is the object that will process the message if the log is enabled - it executes steps 2 and 3. How this happens, is completely up to you - when you define your macros (more on this later). ------------------------------------------------------ Filtering and Log Levels I have implented several filters: see filter.hpp file: - manage_enabled_no_ts - filter (not thread-safe) - always_enabled - enable logs at compile time - always_disabled - disable logs at compile time - debug_enabled, release_enabled - manage_enabled_ts - thread-safe filter - etc. Using v2, you don't really have to use Log Levels, if you don't wish (see examples above) A logged message can have an associated Log Level. By default we have these levels: info (smallest level), warning , debug , error , fatal (highest level) Depending on which level is enabled for your application, some messages will reach the log: those messages having at least that level. For instance, if info level is enabled, all logged messages will reach the log. If warning level is enabled, all messages are logged, but the warnings. If debug level is enabled, messages that have levels debug, error, fatal will be logged. Note that there's an example of using Log Levels provided with the code. ------------------------------------------------------ Usage syntax / Macros Once you've set up what each of your logs does (writes to), it's a must to have an easy and straightforward way to write to your logs - logging can be fun. While you can write directly to your logs, like this: if ( !g_log_app) ; else g_log_app->read_msg().gather().out() << "coolio!" << std::endl; Usually you'll prefer to have some macros to help you write less and especially avoid being error-prone. In the previous version, you've asked to be able to write your own macros - well, you are. And it's waaaay easier than before: If you have a logger object, to test if it's enabled, call its operator bool(). To see if it's not enabled, call its operator! I will provide some helpers in the future - they're not there yet. ------------------------------------------------------ Logger objects and macros So, to define a log macro, you'll say something like this: logger<some_processor, some_filter_class> g_log; #define L_ if ( !g_log) ; else g_log->... Note that "g_log->" is equivalent to "g_log.process_msg()->" (syntactic sugar) What follows after "..." is all up to you. For example, you can just get the message, and call a functor: struct write_to_cout { void operator()(const std::string & msg) const { std::cout << msg << std::endl ; } }; logger<write_to_cout, manage_enabled_no_ts> g_single_log; #define L_(x) if ( g_single_log) g_single_log.process_msg()(x) And in code you'll say things like L_("some great message"); Or, you can use something a bit more complex, which will gather a message written using "<<", and then call a functor. I've already implemented this class: typedef process_msg< ostream_like_return_str<>, write_to_cout> processor_cout; logger<processor_cout, manage_enabled_no_ts> g_log; #define L_ if ( !g_log) ; else g_log->read_msg().gather().out() And in code you'll say things like: L_ << "this" << " is " << "cool"; Or you can implement your own process message class. ------------------------------------------------------ Using process_msg() Your process_msg class can hold context. And you can also manipulate logs in code: logger<...> g_log; g_log->my_great_log_manipulator(); Thus, you can create your own process message handler classes. ------------------------------------------------------ Formatters and/or destinations In my previous version, they were called modifiers and appenders. So, after the message has been gathered (step 2), we do the writing (step 3). In step 3, if you use the "format_write" class, you can choose to add formatters and/or destinations. A formatter is a functor that formats the message - for instance, it can prepend the current time, it can prepend the index, or thread ID, or append an Enter. A destination is a location where a message can be written, like: console, a file, a socket, etc. Dealing with formatters/destinations is easy: once you have a format_write object, just use: void add_formatter(formatter fmt) void del_formatter(formatter fmt) void add_destination(destination dest) void del_destination(destination dest) In the previous version, the formatters were called first, and destinations last. Now you have more control. However, this is not thoroughly tested - need to work more on this. ------------------------------------------------------ Examples. I've provided a few examples - you'll find them in the "tests" directory. The code compiles and was tested on VC8. Am still working on formatters and destinations. I'm planning to host it on sf.net. Feedback and comments are welcome. Again, you'll find the library here: http://torjo.com/log2/ -- http://John.Torjo.com -- C++ expert ... call me only if you want things done right