Tag Archives: boost

A Better Boost Book

Boost is a excellent resource for C++ programming, but suffers from inconsistent documentation and a daunting array of sub-projects. Trying to make sense of it all is a fairly serious undertaking. I tried to get my head around it by writing my occasional series of boost blog posts, but now I see that somebody has done a much better job.

The Boost C++ Libraries is a free book that clearly explains some of the more generally useful boost libraries, with lots of useful examples. It even covers advanced libraries like ASIO in an approachable way. I highly recommended bookmarking it if you do any C++ programming.

Using Exceptions in C++

C++ is big – it has been said that any given programmer only ever uses about 40% of the language’s features. The trouble is that it is a different 40% for each person. Exceptions are a great example of this, some people swear by them while many coding standards specifically ban/discourage them (cf: google, mozilla). It is ironic that a feature designed to make code safer is sometimes regarded as being too dangerous to use.

Personally I like exceptions, but even I realise that they have there limitations. This post is an attempt to formalise some guidelines about when exceptions should be used and when they should be avoided beyond the usual language rules. I should mention at this stage that most of my experience is in desktop client/server software. C++ is used in all sorts of places these days, and what works on desktops and beefy servers may not suit the embedded world (for example).

When to Catch

My rule of thumb is “Do not let exceptions escape from a function you didn’t explicitly call yourself“. This includes destructors, callbacks, thread functions, WNDPROCs, and any other miscellaneous way your functions can be entered (it does not include constructors or virtual functions – exceptions are very useful in those). In general, all these things should catch and handle all exceptions.

Your program will die if an exception escapes a thread. If you are lucky your runtime will do something clever and your program will die painlessly but possibly the OS will have to dispatch the process messily. Either way, your users will not be impressed, so you should always wrap thread functions in try{}catch blocks. In the best case you might be able to signal that an operation failed to the main thread, which can restart it if required. In the worst case you can at least log what happened before exiting.

Lots of third part libraries communicate with your code using callbacks that you supply. You should always ensure that any exceptions are caught before returning back into third party code, since you can never be sure if the library does the right thing. C style libraries like LibCURL are right out, they will probably leak handles and memory as the stack is unwound. C++ libraries may (or may not) be better but could do things you do not expect, like swallow the exceptions themselves instead of letting them fall through (boost::iostreams). Also, some libraries actually call you back on a different thread (boost::asio) so the advice in the previous paragraph also applies here.

You should always be prepared to catch any exceptions that are documented by any C++ libraries you use, especially things like boost::filesystem which can throw at any time.

What to Throw

My advice is to create a small hierarchy that is derived from std::runtime_exception unless you are already using a custom exception class. Don’t try to get clever and throw std::string or char*. Design your hierarchy around how the exceptions are to be handled, rather than what can go wrong. For instance, if there are 5 different ways your program throw exceptions, but only 3 different things that can happen in response then you only need 3 types of exceptions.

In my experience, exceptions fall into two categories: recoverable and fatal. Recoverable exceptions will be caught within a layer, or perhaps the next layer up which can then reattempt the operation (or perhaps just log and ignore the problem if the operation was not crucial.) Fatal errors are usually not caught until the outer loop of the program, where they are logged before the program can be shutdown cleanly. In general, the exceptions you expect to recover from should derive from exceptions you expect to be fatal.

I tend to name my exception types based on how they are handled and what circumstance they represent, like so:

1
2
3
4
5
6
7
8
9
10
11
12
13
class UnrecoverableFileReadException : public std::runtime_error
{
	// thrown when a file cannot be read correctly, ie: the file exists but is misformatted
public:
	UnrecoverableFileException( const std::string& msg ):std::runtime_error(msg) {};
};
 
class FileReadException : public UnrecoverableFileReadException
{
public:
	// thrown when a file cannot be read but the user can be prompted to select another file
	TemporaryFileException( const std::string& msg ):UnrecoverableFileReadException(msg) {};
};

When throwing, always construct the exception with a sensible message if only for logging and debugging purposes. Normally this message would not be shown to the user since it will be hard to localise. Add additional members to your exception class if you want to include other information with the exception. Just remember that exceptions must be copyable.

1
2
3
ostringstream oss;
oss << "Could not open file " << filename << " the error was: " << errno;
throw TemporaryFileException( oss.str() );

If you really want to go the whole hog consider using boost::exception which builds upon similar ideas.

When to Throw

Exceptions should never be thrown if everything is running perfectly. Only when something goes wrong should throwing an exception be considered an option. I have seen code that threw exceptions to signal the end of an enumeration or to signal that the results of a query were empty – I consider these examples to be a terrible use of the feature. Remember that an exception is not just an error, but something really outside of normal program flow.

I also tend not to use exceptions for logic errors. If an algorithm can fail then the calling code should be prepared to handle a return code signalling an error. Likewise I would not throw if a database query returned no results – an empty result set is inside the bounds of normal program flow. However, I would consider throwing an exception if the query failed due to the database being unavailable.

The best places to use exceptions are in situations where your program is using resources that are not under your control, including anything to do with IO. Both files and network connections exist outside of your program and can become unavailable at any point due to any number of reasons. In many cases the problems are transient and all your program needs to do is try again in a few minutes – a program that quits each time the DNS, directory server, or external database cannot be reached will not survive for very long in any production environment. Exceptions allow you to back out of an operation without too much trouble and handle the problem in a sensible location.

One problem you might encounter is that is often hard to retrofit exceptions into code that wasn’t designed for them. In this case, my advice about not letting exceptions fall through 3rd party code also applies to legacy code that you own. This is not to say that you cannot use exceptions at all, just that you may have to take steps to keep exception handling within the layers of your application.

The C++ Boost Libraries Part 6 – boost::any

In C++ if you have a variable that you say is of type “Person” (for instance), you can be fairly certain (more or less) that it always actually contains a Person (or perhaps a subclass of Person. If you have a container of Persons, then you know (more or less) that every member is also a Person (or a subclass).

This is all very good, prevents a lot of runtime errors, and generally makes C++ a great language if you care about correctness. But sometimes, very rarely, you actually want to store a whole bunch of messy, unrelated types in a container without trying to ram them into some sort of class hierarchy. Parsers are a good example of this. It is often convenient just to chuck tokens of various types into a data structure for later processing without worrying too much about the specific type (string, int, float, etc).

boost::any is a small class that can hold values from almost any type, designed for just such messy applications. Using boost::any is very simple:

1
2
boost::any a1 = std::string("Moose");
boost::any a2 = 6;

Of course, getting the values back again is a little harder.

1
2
3
4
5
6
7
8
9
try
{
	std::string v1 = boost::any_cast< std::string >(a1); // this works, a1 is a string
	std::string v2 = boost::any_cast< std::string >(a2); // nope, will throw an exception at runtime
}
catch ( const boost::bad_any_cast& e )
{
	// tried to any_cast into something that wouldn't go
}

Of course, you can query a boost::any for the typeid of the stored object. Just don’t do it when Scott Meyers is in the vicinity.

1
2
3
4
5
std::string v;
if ( a1.type() == typeid(std::string) )
{
	v = boost::any_cast< std::string >( a1 ); // this should never throw, since we checked first
}

A single boost::any is perhaps not that useful, but a container of them can store almost anything we want:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
typedef std::vector< boost::any > AnyVector;
AnyVector values;
 
values.push_back( 5 );
values.push_back( std::string("Hello") );
values.push_back( 5.3 );
 
try 
{
	for ( AnyVector::const_iterator p = values.begin();
			p != values.end();
			++p )
	{
		if ( p->type() == typeid(int) )
			cout << "Int = " << any_cast<int>(*p) << endl;
		else if ( p->type() == typeid(std::string) )
			cout << "String = " << any_cast<string>(*p) << endl;
		else 
		{
			cout << "Unhandled type: " << p->type().name() << endl;
		}
	}
} 
catch ( const boost::bad_any_cast &e )
{
	cout << "Bad any_cast<>" << e.what() << endl;
}

Any type that you put into a boost::any must be copy constructable (the any makes a copy, not a reference). You also have to make sure that its destructor doesn’t throw (but of course you do that anyway!)

Although I wouldn’t recommend boost::any for everyday use, it does come into its own when the only alternative is a huge class structure or (even worse) void *s.

The C++ Boost Libraries Part 5 – boost::filesystem

The standard C++ iostreams library is very good (well, some would say sort-of good) at reading and writing a file’s contents, but it does so in such a way as to completely ignore file names. I am sure there was a good reason for this omission, but whatever it was is long out of date. There isn’t even a standard way to iterate through a directory, for God’s sake! You end up either falling back to the C standard library (ick) or using operating specific APIs just to find out how big a file is.
Continue reading

The Boost C++ Libraries Intermission – Getting Boost Used

A former colleage of mine (Hi Nigel!) frequently wore the greatest geek tee-shirt I have ever seen to work. Ineptly reproduced here, it summarizes the realities of software development – when deciding what to implement technical considerations are often overruled by more prosaic influences.
9-layer-osi

Take this comment by another old colleage. It is a example of how a lot of companies fail to exploit the huge amount of well-tested code available for reuse. There are lots of reasons why a company might ban boost, in my opinion none of them are that compelling.

The main reason cited is the fear of legal retribution (before continuing, I should point out that I am not a lawyer and the following is not legal advice.)

More than one company has been stung by employees including code they do not own into a commercial product, even accidental violations can attract huge penalties with big companies being particularly at risk. This has resulted in a climate where a company will pass every decision on third-party libraries through their lawyers. Lawyers by nature are cautious, they live in a world of contracts, indemnities and assigned liabilities. The default answer is almost always going to be “no” unless there is a contract to sign and someone to blame if it goes pear-shaped.
Continue reading