November 2008 - Boost - lists.boost.org

Re: [boost] [Review] UUID library (mini-)review starts today, November 23rd
by Vladimir Batov 02 Dec '08

02 Dec '08

Andy, Thank you for taking the criticism the right way and my apologies if some of my comments sound(ed) somewhat harsh. It is never my intention. I won't be addressing the points below directly as some issues I raised are petty (and I somewhat wish I did not raise them). I admit I felt uneasy with the proposal but could not pin-point what it was. I'll try again. Background: We are in our project currently using uuid facility heavily and very dependent on it. The version we use (from memory) is something like (it's not necessarily exactly what we use and I'll omit some scaffolding and stick with the basics): struct uuid : public std::string { typedef std::string base; uuid() : base(generate()) {} explicit uuid(string const& s) : base(s) {} static uuid null() { return uuid(std::string()); } private: std::string generate(); }; On Linux the generate() function calls uuid_generate(). No one (in our project anyway) can be bothered choosing between uuid_generate_random() or uuid_generate_time() -- uuid_generate() takes care of the guess work and picks the best available. The same on Windows -- it'll probably be UuidCreate()&UuidToString(). Given that uuid above is merely a wrapper over OS facilities, we get known behavior, we are guaranteed "support" and an automatic "upgrade" if/when the standard changes or a new better algorithm becomes available. For me (a collective nebulous "me") to switch to your boost::uuid it has to provide something to win me over. Let's see what that might be. Does boost::uuid provide superior implementation? Maybe. If it is, that was not spelt out sufficiently visibly for me to pick up in the documentation. Therefore, as it is now the answer regretfully has to be 'no'. Does boost::uuid provide superior interface? That issue might get very subjective and personal. Therefore, I'll re-focus on if boost::uuid is user-friendlier. Maybe but I doubt it as an ordinary user does not want to be bothered choosing between algorithms. If uuid_generate() and UuidCreate() can make that choice for me, it is good enough for the overwhelming majority of uuid applications. Therefore, the answer seems again 'no'. Does boost::uuid provide superior support and a upgrade path? With all due respect I have to say 'no' again as your support (no matter how enthusiastic it is) cannot compete (on industrial/commercial scale) with vendor-backed support. uuid_generate(), UuidCreate() as printf() come with the system. One has to have really serious reasons to use something else instead. Does boost::uuid provide superior documentation? Well, my impression is that it is 'no' again. What boost::uuid does immediately entice an ordinary user with then it is Boost reputation. However, in all honesty it's not boost::uuid property per se but the reputation for quality of the Boost libraries built over those many years. In this thread I hear some people say "it's OK to ship". I disagree. Every new library has Boost reputation to uphold. It takes time to build such a reputation. It does not take long to lose it -- a couple of just "OK to ship" libraries will probably do. I'd probably be more comfortable if boost::uuid took the approach of boost::thread of providing consistent interface across many platforms via re-use of the functionality provided by the OS (when available) rather than duplicating it. Then though I'd expect the interface to be given considerably more thought. As for the interface I'll express my view to one of your comments below. > I would not want the default constructor to generate a uuid. I don't > want users to pay for that if they don't want it. Some use cases will > not require generating uuids, only using them. I have to disagree. I believe that the overwhelming majority of cases falls into the following category -- "I introduce something when/because I need that something". That is, by Foo foo; std::string str1; std::string str2(params); uuid id1; uuid id2(param); I create valid instances. Say, 'str1' is empty but it is still a valid string. I create 'id1' because I need an uuid. You on the other hand use uuid id2(param); // valid instance uuid id1; // invalid instance where #1 creates a valid instance but #2 creates an invalid instance (it lacks its identifying property -- it's NOT unique). Therefore, you use the same (visually and behaviorally) creation mechanism to achieve *different* results. From the user perspective it is inconsistent and likely unexpected. The case you are catering for with uuid() is not mainstream but quite the opposite -- the user introduces something that he does *not* want. Such case should be handled explicitly with the user actually spelling out what he means like Foo::Foo() : uuid_(boost::uuid::null()) // initially invalid {} Best, Vladimir.

4 3

Boost namespace abreviations
by edam 01 Dec '08

01 Dec '08

Hi there, I just wanted to hear the boost community's thoughts on abbreviating boost's namespaces. According to Boost's library naming conventions (http://www.boost.org/development/requirements.html#Naming_consistency) this is strongly discouraged, and with good reason -- having clearly (and consistently) named namespaces is a good thing! Having used boost for a (mere) couple of years now, though, I've started to find its namespaces a bit unwieldy. I try to avoid going "using namespace" (for a few reasons, nicely summarised here: http://dev.lsstcorp.org/trac/wiki/DiscussCodeStandards) and I can't bring myself to go down the route of announcing to the compiler that I will be "using ..." specific symbols from whichever namespace either. So I am left with having to explicitly specify the namespace of each symbol, like this: std::cout << std::setw( 2 ) << std::setfill( '0' ) << hours; While this requires more typing, I prefer it to the alternatives. As a boost user though, I find this becomes a bit more of a pain. Boost's namespaces, whilst well named, are a lot to keep typing out! Here's a quick example: boost::posix_time::time_duration foo = boost::posix_time::hours(2); Multiply this by a thousand lines of boost-using code and you've got a lot of typing! I wondered if there would be any interest in a boost abbreviations header that, if included, would provide abbreviated names for boost's namespaces. Something along the lines of a boost/abrv.hpp: // this is an incomplete example namespace bst = boost; namespace boost { namespace gd = gregorian; namespace pt = posix_time; namespace dt = date_time; } This would allow the developer to shorten the above example code to bst::pt::time_duration foo = bst::pt::hours(2); in this case saving a full 18 characters! Multiply this by 1000 lines of code and you may save some finger-ache. What I'm proposing sounds terrible, I know, but if you consider that users would "opt-in" to this by including the abbreviations header (meaning it wouldn't affect existing users), I wondered if there would be any merit in it? I'm expecting a lot disapproval to this idea, but I thought I'd ask what people think anyway. Please don't shoot me down too much -- this is my first post to the boost mailing list! :o) Regards, Tim. -- edam - www.waxworlds.org/edam

5 4

[date_time] Internal header testfrmwk.hpp
by Andrey Semashev 01 Dec '08

01 Dec '08

Hi, There is a testfrmwk.hpp header in the boost/date_time directory. This header contains some utility to aid testing of the library and I believe is not a part of the library interface (that is, it's not in boost namespace and I don't see it documented). I don't know why the header resided in the boost/date_time directory in the first place, so I intend to move it into the test directory. Does anyone have objections? (Jeff, I hope, you're reading this)

2 2

[Boost.Thread] ids obtained from the same thread not equal
by Karp Dantax 01 Dec '08

01 Dec '08

Using boost::thread::get_id() in an executable and one of its DLLs generate different ids although the calls are made from the same thread. Until Boost 1.34.1, which used GetCurrentThreadId() to compare two boost::thread objects, it worked perfectly. I have not delved into the code, but now that the library is using thread local storage to store the current thread id, it is not working in the context mentioned above. Well, thats it. Maybe i am missing something here? []s

2 1

Re: [boost] Breaking existing libraries
by Tomas Puverle 01 Dec '08

01 Dec '08

> Too bad, and just when I thought we were getting down to brass tacks. > Well, maybe Tom would care to weigh in on these issues; I'm still making > an effort to figure out how best to resolve them. I have been absolutely swamped in the last two days and will not have the time to write up any responses until much later today. Having said that, do you think it's worth my time? It doesn't seem really like we're getting anywhere.

3 6

RFC: Automatic indexing of quickbook/boostbook/docbook docs.
by John Maddock 30 Nov '08

30 Nov '08

I've just committed a new tool to the sandbox under tools/auto_index which helps automate the indexing of quickbook/boostbook/docbook documentation. Obviously the tool is biased toward C/C++ code documentation, as among other things it can scan C/C++ headers looks for definitions of classes/typedefs/macros/functions which should be indexed. The actual index can be produced either by the final XSL transform, or by auto_index itself (ie using regular docbook markup for the index), the former is better for PDF/print docs as it allows page numbers to be inserted, the latter works better for html docs, and is also faster (thankfully - the XSLT index generation code is glacially slow). There are some examples taken from type_traits and Boost.Math here: http://svn.boost.org/svn/boost/sandbox/tools/auto_index/example/readme.html Some rather basic documentation for the tool itself is here: http://svn.boost.org/svn/boost/sandbox/tools/auto_index/doc/html/index.html note that currently there is no Boost.Build integration - I really need some help with that - so the tool is much harder to use than it should be. Any comments, especially on the usability of the indexes generated would be much appreciated! Cheers, John.

5 12

[test] minimal.hpp causing unresolved external with Intel on Windows
by Beman Dawes 30 Nov '08

30 Nov '08

The little program below compiles and runs fine on most compilers, but with the Intel compiler there is an unresolved external: test.obj : error LNK2019: unresolved external symbol "void __cdecl boost::throw_exception(class std::exception const &)" (?throw_exception@boost@@YAXABVexception@std@@@Z) referenced in function _main test.exe : fatal error LNK1120: 1 unresolved externals --Beman #include <boost/test/minimal.hpp> int test_main(int, char*[]) { return 0; }

2 4

filesystem: wrong close 0 descriptor in copy_file_api on unix
by Anton Ivanov 30 Nov '08

30 Nov '08

Hi! Seems bug in boost::filesystem::copy_file on unix. This code is wrong if ::stat call fails - it is just close descriptor with number 0 (by if ( infile >= 0 ) ::close( infile );). BOOST_FILESYSTEM_DECL error_code copy_file_api( const std::string & from_file_ph, const std::string & to_file_ph ) { const std::size_t buf_sz = 32768; boost::scoped_array<char> buf( new char [buf_sz] ); int infile=0, outfile=0; // init quiets compiler warning struct stat from_stat; if ( ::stat( from_file_ph.c_str(), &from_stat ) != 0 (infile = ::open( from_file_ph.c_str(), O_RDONLY )) < 0 (outfile = ::open( to_file_ph.c_str(), O_WRONLY | O_CREAT | O_EXCL, from_stat.st_mode )) < 0 ) { if ( infile >= 0 ) ::close( infile ); return error_code( errno, system_category ); } Fix is just changing int infile=0, outfile=0; // init quiets compiler warning to int infile=-1, outfile=-1; Patch attached. Bug https://svn.boost.org/trac/boost/ticket/2542 created. -- Yours sincerely, Anton Ivanov (ai(a)drweb.com)

2 1

[result_of] decltype and function objects
by Eric Niebler 30 Nov '08

30 Nov '08

I've noticed test failures when compiling some of boost in C++0x mode due to the change to boost::result_of to use decltype. The problem comes from function objects like this: template<class T> struct identity { typedef T result_type; T const & // <== problem here operator()(T const &t) const { return t; } }; In this (overly simplistic) example, we just want to return what is passed in. The computed type (result_type) is different than the return type of operator() ... and for a good (IMO) reason: to avoid an unnecessary copy in some cases. The idea is to accommodate usage like this: result_of<identity(BigObj)>::type i = identity()(BigObj()); It is really very important that decltype(i) be BigObj, and not BogObj const &, which would cause a dangling reference. But with the change to use decltype in boost::result_of, the dangling reference is exactly what I would get. Am I now forced to change identity::operator() return by value here? That seems sub-optimal to me. In many other potential uses of identity (e.g., when forwarding the result to some other function), the copy is totally unnecessary. -- Eric Niebler BoostPro Computing http://www.boostpro.com

3 3

Maintenance Guidelines wiki page (Revison 8)
by vicente.botet 29 Nov '08

29 Nov '08

Hi, I have updated the Maintenance Guidelines wiki page. I have take in account the minor proof-reading modifications from Steve Watanave which I have overridden by error (thanks Steve!),and added a lot of thinks, maybe too much :) Please read this mail completely before jumping to the page. This page need to be completed and reworked. Please be free to add new sections to the page or improve the current ones directly or post your comments or suggestions to this list. Here it is the table of contents. [C] 1. Motivation [C] 2. Introduction [C] 1. User code breaking cases [I] 2. Versioning individual Boost libraries [O] 3. Deprecating features [I] 4. Cross version testing [C] 3. Documentation [O] 1. Tag Boost library with specific library version [developer] [O] 2. Make feature request for each feature [developer, user] [I] 3. Include the tracked tickets on the Release notes [developer] [I] 4. List the test cases associated to the trac system tickets [developer] [I] 5. List the dependency upon other Boost library [developer] [O] 6. Document behavior differences between release and debug variants [O] 7. Document behavior differences between toolsets [developer] [C] 4. Coding [O] 1. Don't use using directives [user] [C] 2. Avoid the use of include all features files at the /boost level [user] [C] 3. Be careful with the use of using namespace header files [developer] [C] 4. Don't overload functions that are used by the TR1 (using using)[developer] [O] 5. Avoid include-all-features files at the /boost level [C] 6. Don't refine functions overloading without ensuring the same behavior [C] 7. Avoid the inclusion of symbols at the boost or boost::detail namespace [C] 8. Avoid different external behavior depending on the variant release or debug [O] 9. Avoid to change interfaces [developer] [O] 1. Don't delete files prematurely [developer] [O] 2. Don't delete namespaces prematurely [developer] [O] 3. Don't delete classes/functions/variables prematurely [developer] [O] 4. Don't modify functions prototypes prematurely [developer] [O] 5. Remove the deprecated features on a given release [developer] [C] 5. Test [C] 1. Test headers [developer] [C] 1. Include each header files twice [developer] [I] 2. include each couple of header files in both orders [C] 3. Include all header files [C] 4. link all the header files twice [C] 2. Don't forget to test [C] 1. The implicitly generated member functions [C] 2. The removed default member functions when you declare a constructor [C] 3. The deleted (private) default member functions [C] 4. The explicit constructors [C] 5. The implicit constructors or conversions [C] 6. The const-ness of variables, function parameters and function return types [I] 3. Separate the functional test from the unit test (implementation test) [I] 4. Track regression test on the trac system tickets [I] 5. Preserve the functional test from the preceding versions [developer] [C] 6. Inspections [O] 1. Announce new library features [developer] [C] 2. Inspect the code [developer, user, RM] [C] 3. Check that every modification has been documented [developer, user, RM] [C] 4. Check that every modification has been tested [developer, user, RM] [U] 7. Developer guidelines [U] 8. User guidelines [U] 9. Release manager guidelines Tasks I plan to do: 1* Add the motivation 2* Add other examples of user code break in 2.1 3* Update the Developer, User and Release manager guidelines cross reference (7,8,9) 4* Separate on 4 pages. Main, Documentation, Coding, Test and Inspections 5* Complete incomplete guidelines [C] and improve some of them [I] Note that some guidelines applied to the developer library could be done by other people that would need SVN writtig permission. In particular the Functional Test and some documentation reports. (See below points C and E) Other points I see: A* See if the Jamfile to test the headers from Steve can be adapted to tests (Steve?) 5.1.2 Include each couple of header files in both orders B* See if the difference between source and binary compatibility is desirable (ALL) C* See if the functional test can be written by a team of interested users to don't overload the developers. These tests could in addition include multi-library tests and be stored in a directory independent from the developers one (Interested users?) D* See which configurations (deprecated or not) could be tested by the current test team. (Release Manager Team?) E* See how the following points can be automated and where this information can be included in the documentation. A separated page make possible that this task could be done by other people than the developer. (Some one knowing the Track system?) 3.3. Include the tracked tickets on the Release notes 3.4. List the test cases associated to the trac system tickets F* See how the dependencies between libraries can be automated (Release Manager Team?, CMAKE project?) 3.5. List the dependency upon other Boost library In order to know if I'm going on the right direction, I would like the interested people reply to this post stating for each section, if it is OK[O], must be completed[C]/improved [I], must be updated [U], must be removed [R] and of course any idea is welcome. You can access it directly at "https://svn.boost.org/trac/boost/wiki/Guidelines/MaintenanceGuidelines" or at "https://svn.boost.org/trac/boost/wiki" >Guidelines >Maintenance Guidelines Best regards, Vicente

7 15