Many people are in love with the Singleton pattern. Others — a small minority, I suspect — consider it a mistake, an anti-pattern, or something that was only ever included in the Design Patterns book as a lifeline to procedural programmers who couldn’t really figure out this OOP thing.

I won’t pretend to be half as clever as all the people who have already written about the problems with singletons years ago, and I don’t think I have anything new to bring to the table. But it is a pattern I learned to loathe very soon after I first saw it in use. (Singletons do sound attractive when you first hear of them. But they pale a bit when you end up having to tear up and rewrite half your code just because all your singleton classes start revealing their shortcomings) And for a long time now, I’ve tried to convince other programmers that Singletons have some serious problems. Recently, it seems like I’ve even gotten noticed for it on StackOverflow.

First, GMan posts an answer to one question, and I comment with a mild disagreement, and the discussion goes on for a few more comments. As singleton rants go, this one is pretty mild, and I don’t really think about it any further. Then, a few weeks later, I discover his blog and this post. Wow! A convert. A person I know to be extremely bright and a knowledgeable programmer has changed his mind in response to something I said… I’m flattered.

And today, I noticed another question being posted, which had both Boost and Singletons in the title — how could I resist? Two subjects I enjoy talking about, even if the things I say about them are very different. Surprisingly, the comments there already mentioned me, and some of my earlier answers regarding singletons. Should I be flattered that people have started bringing my name up when discussing Singletons?

Anyway, one of the comments also suggested I write a blog post describing my argument in detail. So I will.

Two wrongs don’t make a right

There are a lot of problems with singletons. In fact, it’s surprising that so many people still consider the pattern useful, when it is afflicted with so many weaknesses and flaws. However, for now I will single out the two that I feel are the most fundamental: not just problems with how a singleton works, but with what they’re trying to achieve:

A singleton, as defined by the Gang of Four, combines two properties:

• it guarantees that exactly one instance of an object exists. While that one instance is typically created lazily, so it doesn’t technically exist throughout the entire application’s lifetime, it always seems to the programmer as if precisely one instance exists, and
• it guarantees global access to this one instance.

Let’s pick those apart a bit. The last one is easiest: it is, by now, fairly common knowledge that global state is bad. We don’t like global variables, we don’t like static class members, we don’t like anything that makes it harder to isolate bits of our code. Dependence on global state causes a lot of problems: it hurts parallelism, as access to global mutable state generally has to be serialized through the use of locks. It makes dependencies harder to detect and control (any function might silently decide to access our singleton. The function signature says nothing about this, so we have to read the source code of the function to determine if this is the case. And because it is so convenient to always just add a reference to a singleton, we tend to do it a lot. When you have a singleton, you quickly end up in a situation where three out of four classes depend on it. How did that happen? Why, logically speaking, do so many classes need direct access to the database? Or the renderer? Is that good design? Not only is this messy, it’s also painfully hard to fix after the fact. Once we have these dependencies on global objects everywhere, that’s a lot of code we need to change to eliminate the global. Almost every class will be impacted by the change, and a huge number of functions have to have their signatures modified to take that extra parameter replacing the global. Or even worse, the function has to be completely rewritten to eliminate the need for whatever service the singleton provided. The more globals you have in your project, the more your dependency graph starts resembling spaghetti. And the harder it gets to clean it up.

It hurts reusability, as code taken from one project and inserted into another may break because it depended on globals not present in the new project. It hurts testability partly for the same reason, a unit test testing a class must suddenly provide a number of globals as well just for the code under test to compile, but also because global state makes tests less deterministic. One test might change the state of this global, affecting the outcome of the next test to run.

Globals are bad for a lot of reasons. They have their uses, no doubt about that, but we should be suspicious whenever the solution to a problem involves global data. It might be the best solution, but often, it is more trouble than it’s worth.

The other point is more subtle. Why do I object to a class enforcing that “only one instance may exist”? It’s really just common sense. As the Agile movement tells us, we don’t really know what our code is going to look like tomorrow. Over the course of development, we have to adapt to changes, modify our code, revise decisions already made. Why put roadblocks in front of us? Why make it harder to adapt to unforeseen changes or requirements?

Today, I might think that I need only one logger instance. But what if I realize tomorrow that I need two? That’s not so far fetched. We may have one log we write ad-hoc messages intended for debugging purposes, solely to be read by developers, and another formalized log, where structured messages are written when predetermined events occur, so that the application can be monitored in production. Sure, we could define the two as completely separate classes, and then we’d only need one instance of each (but then we’d start duplicating code). Or we could use the same log instance to write to both logs (but then the logging code would become more complex, having to interleave two separate and non-overlapping logs.

Once we’ve accepted that an application may need more than one logger, shouldn’t we do ourselves the favor of ensuring that our loggers can be instantiated more than once, just in case it turns out to be the right thing to do? We’re not even adding any complexity, there’s no cost associated with this. On the contrary, we’re removing significant complexity. Thread-safe singletons are surprisingly hard to get right. Dependencies between singletons are tricky and circular ones can cause them to blow up in all sorts of fun ways. And let’s not even get into how to handle anything our singletons might do while the application is shutting down. What if the database singleton tries to write a simple “goodbye” log message to the log singleton? What if the log singleton got destroyed before the database one? Ouch.

Singletons are hard to write and hard to use. Removing them only simplifies our code, so if it also enables us to better adapt to unforeseen requirements, why shouldn’t we remove them?

Not convinced? Let’s think of some other examples then:

• the application configuration should be a singleton, right? We obviously can’t have more than one of those! Wrong. We can. We often do. Think about what happens when the user opens the “Options” screen and modifies the settings. During that time, two sets of settings exist: the “applied” settings that are currently in effect, and the “speculative” ones, currently being picked out by the user. Once he clicks OK, the speculative changes should be applied, replacing the ones that were previously in effect. But until then, we have two sets of settings to maintain.
• a database connection pool then! If we have more than one pool of connections, we can’t efficiently share them! Correct, but perhaps we don’t want to share them. Perhaps I want to ensure that library A has one pool of 10 connections available to it, component B has a smaller pool of 3 connections, an components C, D and E use the global pool with however many connections it supplies. That would ensure that no matter the number of threads running in component B, it’ll never starve out other components trying to access the database. It can never hold more than three connections, leaving room for other components. Of course, in the common case, we do want all connections to be shared in one single pool. But perhaps not always. So yes, there should probably be a globally accessible default pool available. But why shouldn’t it also be possible to define new local pools if the user deems it necessary? Why limit ourselves to one instance?

And even if you do come up with some case where we absolutely must never have more than one instance, where it would make the sky come crashing down on us, consider testing. Consider that each of your unit tests should set up the environment it needs, and run within that environment, in isolation from other tests. That means that every test should create its own logger instance, or database pool instance, or whatever else our singletons are doing, just so it can avoid being polluted by stateful changes made by earlier tests. Each unit test for the Direct3D renderer should set up its own renderer object. Each physics simulation test should initialize the physics engine first, and shut it down again after use. Singletons don’t easily allow that. Sure, we can extend them with explicit Create() and Destroy() methods, but then our abstraction is starting to get leaky. We can no longer assume that precisely one instance exists, because we might have just destroyed the one that existed.

The “exactly one instance” guarantee removes flexibility from our code that we may need, in order to enforce a constraint that we definitely don’t need. Where’s the harm in allowing the user to create more than one instance if he decides to?

C++ programmers are familiar with std::cout, the standard output stream. Funny thing about this, it is a simple global object. We can obviously never have more than one standard output stream. But we can have more than one stream. The standard library just initializes one of them to point to the standard output, and saves it as a global variable. We don’t need it to be a singleton, we don’t even need it to be a static class specially defined for the purpose. We just need a stream, defined somewhere where it’s globally accessible.

True, a sufficiently stupid programmer could create a new stream when he intended to write to std::cout, and true, a singleton implementation would have prevented that. But is it worth it? When was the last time you saw someone accidentally invoke std::ostream() << "Hello world";, when they intended to write std::cout << "Hello world";? It’s not the most common typo I’ve seen.

We don’t need to prevent multiple instantiations. If we want only one instance, we just instantiate the class once, and refer to that instance whenever we need it, end of story. We don’t need the compiler to slap us over the wrists if we do create multiple instances, because we never do so by mistake. If we do it, it’s because we have a reason. It’s because our initial assumption that only one instance was needed, turned out to be wrong!

So there you have it. A singleton combines two negative qualities. It takes the “you can never create a second instance of this class” constraint, which hardly ever makes sense, and even when it does, does not typically need to be enforced by the compiler, and combines it with a global object, giving us all the downsides of both!

Two wrongs don’t make a right. Not even if they were described as a good idea by some guys 15 years ago. They’re still no greater than the sum of their parts: two wrongs. One bad thing combined with another bad thing, creating a very bad thing.

Too many programmers rely heavily on singletons to solve a problem they never had. They never needed a compile-time guarantee that multiple instances of a class can never be created. They just needed one instance to be created.

Sometimes, we do need globals, yes. In those cases, make old-fashioned globals. Use static class members, or if the language allows it, global (non-member) objects. Or use the Monostate pattern, or whatever you feel is the cleanest solution. But remember that the problem you’re trying to solve is “enabling global access to this data”. No more, no less. You do not want a solution which sneaks completely unrelated constraints and limitations in through the back door.

And while I can’t personally think of many cases where this is true, you might also run into situations where it is truly necessary to prevent more than one instance of a class from ever existing. Again, I can’t think of what situation this might be, but I won’t rule out that it can occur. If it does, then enforce that constraint alone. But don’t go around providing global access to the object as well. Whatever specialized purpose your “one instance only” class serves, it’s highly unlikely that everyone should be allowed access to it. So don’t make it a global.

Most of the time, your classes should have neither of these attributes. Sometimes, rarely, they may need one of them. But the singleton pattern imbues the class with both properties, and that is just a plain bad idea.

If I had to pinpoint one thing that marked the difference between a skilled and an unskilled C++ programmer, it would be “do they understand RAII”. Many people don’t, hence this post.

RAII is, apart from being badly named, one of those deceptively simple concepts that you think you understand when you first hear of it, think “well duh, that’s obvious”, and then proceed to write code as usual, because you just don’t see how widely applicable it is.

But let’s get the name out of the way first. RAII stands for “Resource Acquisition Is Initialization”. And if you’re not already familiar with the idiom, then this has told you nothing at all. If you did know about RAII in advance, then you can, when you stop and think about it, kind of see how the name relates to it… vaguely… sort of.

What it actually means is simple: Resources should be managed by classes. When the class is initialized, the resource is acquired (hence the name). When the class is destroyed, the resource is released. And the lifetime of the object should exactly match the desired lifetime of the resource. That sounds obvious, and many programmers will (assuming they’re working in a language that has classes), say that this is what they always do.

Often, C++ developers think this just means “smart pointers. Wrap your memory allocation in a boost::shared_ptr and you’re done”. I see that as one not-very-often used border case though, rather than a typical example of RAII. So let’s take a step back instead.

The key idea isthat any kind of resource, not just memory, but file handles, sockets, database connections, or even more abstract resources like loggers or profiling timers or textures, really any concept or process which has a lifetime, should be mapped to an object.

Unlike the typical object-oriented line of thought which goes that “everything must be an object, because then.… well, everything will be an object, and your code will be better”, here we actually have a concrete reason: We want to use the object to manage the lifetime of the resource.

When I allocate memory with new, I have to deallocate it again sooner or later, with delete. (Or in C, with malloc() and free() respectively). And I have to make sure that this is done. And I have to make sure that it is not done twice. And that the object is not accessed after this is done. There are a lot of constraints we have to obey, all related to the lifetime of the resource. And this is why unmanaged programs have a reputation of leaking memory left and right. If we allocate memory, and it is to be used by a dynamic number of objects or functions all referencing the same allocations, which of the users is responsible for deleting it? And how do we know when it is safe to delete, when no users remain?

Ironically, most managed languages have not solved the problem. They have added a garbage collector (which yes, is very useful for a wide number of reasons), but that only solves one specific instance of the problem. It takes care of avoiding memory leaks, but it doesn’t avoid resource leaks in general.

The garbage collector ensures that this code won’t leak memory:

void foo() {
  SomeObject* obj = new SomeObject();
  bar(obj);
}

where without a garbage collector, we’d (at least without RAII) have to write code such as

void foo() {
  SomeObject* obj = new SomeObject();
  try {
    bar(obj);
    delete obj;
  }
  catch(...){ delete obj; }
}

In the garbage collected case, we don’t know what bar does, and we don’t need to know. It doesn’t have to delete the object. And neither does the foo function. So we have successfully dodged the problem of managing the lifetime of memory allocations. We haven’t really solved the problem though. We still don’t have any good tools to manage the lifetime. We’re just guaranteed by the system that it’ll last long enough.

In C++, this effect can be approximated using some kind of smart pointer¹.

Smart pointers allow us to write code like this:

void foo() {
  boost::shared_ptr<SomeObject> ptr = new SomeObject();
  bar(ptr);
}

and be sure we won’t leak memory. Of course, this solution isn’t perfect — reference counting is much more expensive than a good garbage collector, and if we create cyclic references, the objects will never be deleted, as the reference counts never reach zero. It is a decent approximation, but nowhere near as good and reliable as the garbage collector in managed languages.

But the problem shows up again if we use another type of resource. What if we’d opened a database connection instead? We’d have to write code such as this: (The following Java-like pseudocode is copied almost verbatim from this StackOverflow.com answer, courtesy of Martin York.)

void writeToDb()
{
  Db db = new Db("DBDesciptionString");
  try
  {
    // Use the db object.
  }
  finally
  {
    db.close();
  }
}

(And of course it gets even worse if db.close() can throw exceptions. Then we have to catch that exception, just to avoid it propagating out from the finally clause if we reached finally because of an exception being thrown in the try clause.)

The resource management problem still exists. We still have to wrap the code in exception handling just to make sure that the connection is closed as soon as we’re done with it. And we have to do this at every use. And it gets complicated fast.

Of course, .NET makes this a bit simpler:

using (Db db = new Db("DbDescriptionString"))
{
  // use the database object.
}

But the onus is still on the user of the class to ensure it is closed correctly. There is no obvious way to encode into the Db class that “once we’re done with an object of this type, the connection must be closed immediately”.

And in C++, smart pointers are no longer suitable solutions, since the resource to be managed is no longer a pointer allocated with new.

Instead, a more basic flavor of RAII comes to the fore:

void someFunc()
{
    Db db("DBDesciptionString");
    // Use the db object.
} 

Yes, that’s all. When the db object goes out of scope, at the end of the function, its destructor is called. The destructor internally calls this->Close() for us, so we don’t need to do it! We just have to trust the scoping rules of C++, which guarantee that destructors are called on local variables when they go out of scope, and on class members when the class is destroyed.

So in a sense, the key idea in RAII is simply that “resources should behave sensibly”. They should get copied safely if an assignment is made (or otherwise, assignments should be prevented), they should be available if their owning object is successfully created (if it can’t create the resource, it should throw an exception, aborting the creation of the object), and when they are no longer used, they should be cleaned up.

The C++ standard library class template std::vector is a wonderful example of RAII in action. The resources being managed by a vector are memory (the array allocated internally to hold the objects being contained in the vector, as well as the objects themselves. When the vector is destroyed, every object it holds must be destroyed too, and the array in which they were placed must be deallocated.

In the following examples, assume that a function foo is passed a vector of MyClass objects by value. We don’t know how many, if any, objects are stored in it, but since we are passed a copy of the original vector, we take ownership of it. It exists only in the function foo, and must be destroyed afterwards.

void foo(std::vector<MyClass> vec) {
  ...
 //  when we get to the end of the function, all local variables, including vec, 
 // are automatically destroyed by having their destructors invoked.
 // So no matter how many MyClass objects were stored in the vector, it ensures that they too have their destructors called.
 // And the vector also deallocates its internal array, leaving neither of its resources alive at the end of the function
}

void foo(std::vector<MyClass> vec) {
  throw std::exception("Oops");
  // as above, vec is automatically destroyed when we leave the function,
  // regardless of *how* we leave it. Even if we leave it because an exception was thrown and not caught.
} 

void foo(std::vector<MyClass> vec) {
  // other is constructed as a copy of vec. std::vector ensures that both of vecs resources are copied as well
  std::vector<MyClass> other = vec;
  // we now have two vectors, each owning a dynamically allocated array and a number of MyClass objects
  // and again, at the end of the function, both are deallocated cleanly
} 

void foo(std::vector<MyClass> vec) {
  std::vector<MyClass> other; // a second, empty, vector

  // perform an assignment, setting vec to be an empty vector
  // std::vector makes sure that if you do this, the resources previously held by vec are cleanly released
  // before copies are made of the resources held by other
  vec = other;

  // and so when the function ends, the MyClass objects originally held by vec
  // have already been destroyed, so their destructors are *not* invoked now
} 

As the above shows, vec owns its resources, and manages them tightly. Whenever a change happens to vec, it reflects this by updating its owned resources. If it is destroyed, it destroys its owned resources. If it is copied, it copies the resources it owns. If it is assigned to hold something else, it first destroys its existing resources. And so on. Nothing you do can bring it “out of balance”. It just works. That is RAII. Smart pointers are just convenient adapters turning raw pointers into RAII objects. But RAII is much more than smart pointers.

It is the broad and general idea that resources should be mapped to objects, so that the object can not be created unless it succeeded in acquiring its resource, and it can not be destroyed without also releasing its resource. This effectively saves C++ programmers from having to worry about resource management.

Take an example that’s guaranteed to cause pain without the use of RAII: Handling exceptions being through halfway through constructors. Say you have a class with multiple members which are initialized in its constructor. After the first member has been initialized, but before all of them have been initialized, an exception is thrown. Let’s use the following contrived example:

class Foobar {
  Foo f;
  Bar b;
  MyClass c;

public:
  Foobar() : f(42), b("hello world), c('a') {}
};

unfortunately, b’s constructor throws an exception. How to handle this? We know that in C++, partially constructed objects do not automatically have their destructors called. when the construction is aborted.

And since we want to avoid any resource leaks, we require that the following must happen: – a must have its destructor called (because a was successfully initialized before the error occurrd) – b must release any resources it acquired in its constructor before it threw the exception – c must do nothing. Its construction was not yet begun when the error ocurred, so it would be an error to attempt any kind of cleanup of c. – The Foobar object (the object pointed to by the this pointer) must ensure that the above, and nothing else, happens, and it must do so without relying on its own destructor (which won’t be called, as construction did not successfully complete).

And of course, pretending that only b can throw an exception may be a simplification over the real world. Perhaps every member could throw one from its constructor. Care to write a Foobar constructor which takes all this into account, providing enough try/catch blocks to correctly catch every exception that might be thrown, and release exactly the resources that have been allocated until then, and nothing else? A tall order, and an open invitation for bugs. And of course, it’d lead to a huge, bloated and error-prone constructor. It’d also prevent us from using the initializer list. We’d have to perform some kind of “safe” non-throwing default construction of both a, b and c before entering the constructor body, where exception handling is possible, and from there, attempt to perform assignments to bring the three members into the desired state.

In pseudocode, the constructor might look something like this:

Foobar() {
  a = new Foo(42);
  try {
    b = new Bar("hello world");
  }
  catch {
    destroy a;
    throw;
  }
 try {
    c = new MyClass();
  }
  catch {
    destroy b;
    destroy a;
    throw;
  }
}

Note that all this complexity is only necessary because we want to handle several different resources. a, b and c all contain resources that must be attempted acquired, and properly released if this fails. If there’d been only one resource, the job would have been much simpler. There wouldn’t be any point at which some resources have been acquired, and others have not. If we succeeded in acquiring that one resource, there’d be no risk of errors occurring afterwards, so we wouldn’t need complex conditional cleanup code. And if we failed to acquire the one resource, there’d be nothing to clean up — after all, the resource was never acquired!

So to keep down the complexity, the only safe way to define a class is to make it own at most one resource. And this one-to-one mapping of resources to classes is exactly what RAII is all about. If a, b and c had all been RAII objects, then the above code would work. Regardless of which members could or couldn’t throw exceptions. According to the rules of C++, we know that in the above case,

• the Foobar destructor (this->Foobar::~Foobar() will not be called, as *this was not successfully constructed.
• the a destructor will be called, as this member was fully constructed at the time of the error.
• the b and c destructors will not be called, as these members were not fully constructed at the time of the error.

So assuming that b’s constructor takes care of releasing any resources successfully allocated when the error occurred (the number of which, as pointed out above, should ideally be zero), we’re actually home free! What happens is exactly what we listed earlier as our goal. a has its destructor called, c’s constructor was never run in the first place, so it doesn’t have to do anything, and *this doesn’t have to do anything special in its constructor. All of its members take care of their own resources, so the number of resources managed by *this is zero!

We don’t even need to write a destructor for Foobar now, if all its members are RAII objects. Whether the Foobar object is partially or fully constructed, its members take care of themselves. That is the power of RAII. Once a resource has been mapped to a class, we can use it as much as we like, and even in very complex situations, and never have to worry about the resource being leaked. It is managed by its wrapping RAII object, and the C++ lifetime and scope rules ensure that this wrapper object gets destroyed when it goes out of scope

First in line is Microsoft’s C++ compiler and IDE.

From you, what I’d like to see in 2010 is actually fairly simple (at least conceptually): rethink your IDE. The Visual Studio team as a whole is already doing this in a big way with VS10. I’m hoping you can find the time to reinvent the C++ IDE specifically as well.

For the past decade (except for the 5 years you wasted trying to eliminate native C++), you’ve been trying very hard to write the ultimate IDE for the wrong language. You’ve got something that works pretty well for C++ code anno 1993 or so. And which completely falls apart when used for more modern C++. Why do you persist in putting so many resources into making Intellisense better, when it still has no way to deal with a simple template function? Isn’t that a hint that you should rethink your approach? Modern C++ has quite a bit in common with dynamic languages. The type of a function parameter may not be known just by looking at the function definition. Often a full-fledged “interactive mode” as is common in dynamic languages, is desired, for example if we want to see what the actual type of some template parameter is. Or when instantiating template metaprograms, we may wish to step through them line by line at compile-time, rather than being limited to looking at the compiler errors — the metaprogramming equivalent of printf–debugging. What I’d like to see from the MSVC IDE in the coming years is an acceptance and support of modern C++ paradigms — generic programming, template metaprogramming and all the difficulties that implies. Don’t give me an IDE that tries to provide Intellisense for a program with a completely static structure. If you’re going to do Intellisense, make it able to handle the very flexible type system enabled by templates. take a leaf from the JavaScript support in your IDE, which supports intellisense even though the language is dynamic and types generally aren’t known until runtime. So to display type information in the IDE while the code is being written, they have to be clever. But they can do it.

In C++, the types aren’t known until compile-time, so from the IDE’s point of view, the problem is similar. To display type information while the code is being written (and before it is compiled), the IDE has to be clever. And at the moment, it isn’t. At the moment, Intellisense just gives up.

Let’s take a simple example. What should the IDE do about this function:

template <typename T>
typename T::return_type foo(T arg){
  bar(arg);
  return arg.baz();
}

If we play it by the book, and demand a “perfect” solution, there is nothing the IDE can do. It doesn’t know what T is, so it can’t help us with autocompletion, suggesting members after the dot, or anything else. But if we’re willing to think outside the box, and accept a success rate lower than 100%, there are several strategies the IDE could use to provide meaningful Intellisense information:

• we could look at the call sites. They must logically provide types that are valid in this context. We could find one call site, and provide Intellisense on the assumption that the type T is whatever was passed at that call site. That wouldn’t be 100% accurate in all cases, of course, but it would give us a type that works with the function, so it would be useful. It could even look at several call sites, and compute the union of the types used. If they all provide a frobnicate() method, then the IDE could assume that T inside the function foo always contains such a member.
• We could look at how the type is used in the function. It must have a copy constructor (because it is passed by value), it must have some nested type return_type, and it must have a no-arg baz member function, which returns something convertible to that type. And it must be convertible to whatever arguments bar expects. This probably isn’t a complete description of the type, but it would be enough to give us some limited Intellisense information at least. The compiler might be able to deduce some information about the type. We could even generate some kind of ad-hoc “concepts” implementation — perhaps not as extensive as that which was proposed in C++0x (and subsequently dropped), but a kind of helper datastructure that the IDE can attempt to map onto unknown template types.
• Or we could allow the user to specify an example of a valid parameter type, and then use that to generate Intellisense information from.

But an alternative approach (and these aren’t mutually exclusive) might be to reduce the reliance on Intellisense, which is essentially a static analysis tool. Perhaps a better approach would be to bring the “Immediate” pane up to date, and make it useful, not just during debugging, but while programming as well. Why can’t I through the intermediate window ask for the class std::vector<bool> to be instantiated, for example, so that I can inspect its structure? Perhaps I’m curious what its iterator type will resolve to, or perhaps I want to know the size of the class or other static information. Why can’t I just ask the IDE for this information? Again, modern C++ has a lot in common with dynamic languages. Very little information can be reliably extracted without compiling the code. So give me the tools for optionally and temporarily compiling bits and pieces.

When I write silly template metaprograms to compute the N’th prime number, and the result is wrong, why doesn’t MSVC provide a compile-time debugger? One which lets me step through the instantiation of this maze of templates, inspect the members of each, and find out where it went wrong, where it instantiated the wrong template, or where I forgot to write the specialization I intended.

In far too many ways, the C++ IDE really feels like a C IDE. Most of it doesn’t seem to know that there’s this new-fangled thing called “templates”, or that they change how people write code. The Immediate window or the debugger, do not recognize template parameter names. If I am debugging a function template <int I> void foo(), why can’t I get the debugger to tell me the value of I? It should be absolutely trivial to do. But the debugger can’t seem to do it. Intellisense can’t seem to do it. The Immediate pane can’t seem to do it. There’s a clear mismatch between the compiler, which is clearly a C++ compiler, and pretty much hasn’t bothered about the C side for close to a decade, and the IDE which still seems to be trying to be the perfect C IDE, completely disregarding every feature unique to C++.

I know you’re used to being told that you have one of the best IDE’s in existence. I beg to differ. You may have got one of the best C IDE’s, and your C# and VB IDE’s kick some serious butt. But your C++ IDE is essentially nonexistent. Your IDE does not support C++. It supports a marginally and conservatively extended C.

So far, I’ve dealt exclusively with the IDE issues, and that’s not a coincidence. On the whole, I’m quite happy with the MSVC compiler. The performance of generated code is good; you’re making great progress on C++0x support, and overall, you’ve got a compiler I’m happy with. Of course there are still a couple of areas where the lack of standards-conformance is embarassing (never mind the export keyword, I’m more bothered about two-phase name lookup and other relevant features), and there are some features I wish you’d borrow from GCC, but on the whole, and I wish you’d tighten up your warning messages a bit (some of them are nothing more than noise, or are impossible to avoid in “good” healthy code), I have relatively few serious complaints about the compiler. I do, however, have a few suggestions.

It seems to me that the source/header compilation mechanism could use a makeover. We can’t change the actual semantics (yet — hopefully the proposal for a module system for C++ gains traction), but the compiler can change how it actually processes the code. And yet, major compilers still process the source files in the exact same manner they did 20 years ago. Even though this is, on today’s machines, and with today’s huge codebases, ridiculously inefficient.

Ages ago, precompiled headers were invented, but I’m not really a fan of them. It’s a hackish solution which sometimes helps, but may also hurt, due to the tendency towards including everything in one single “blob” header. Even if that header is precompiled, it still means everything that includes it has to deal with these bloated monolithic symbol tables and other data structures. More importantly, it is a fragile solution, as the VC Team’s own blog shows.

But why can’t this mechanism be generalized? Why can’t the compiler process every header in isolation, build a complete parse tree of each one, and store those on disk? And then, when the header is included, rather than reading and parsing the header again, simply load this parse tree and merge it into the rest of the compilation unit. Of course, it is easy to come up with cases where the file may have to be parsed differently depending on where it is included, but in 99.9% of all cases, the inclusion mechanism is straightforward and simple: The header is typically not included in the middle of a class definition or from inside a namespace. It usually only reacts to a few fixed macros that may be defined before the header’s inclusion. So most of the time, the header could be precompiled in isolation and reused. And for the few cases where the changed state actually matters, where the header is included in the middle of a function definition or with no include guards or where a macro (say CreateWindow, or a similarly common name, cough cough) mangles the contents of the header, in those cases, the compiler can simply fall back to the traditional source code inclusion and subsequent compilation of the translation unit. Even if these precompilation passes aren’t stored to disk in the manner of precompiled headers, they could still be kept in memory, and reused between translation units during a build. If N .cpp files all include a certain header, it would allow that header to be compiled once, rather than N times.

Once again, we have something that feels like a leftover from C. In C, headers were mostly forward declarations and little actual code, so naive processing of headers worked fairly efficiently. in C++, it is getting more and more common to put huge amounts of code in headers, which means that the naive compilation strategy traditionally used for C becomes ridiculously slow and inefficient. Creating a truly general replacement strategy is nearly impossible, true, but it seems like it’d be possible to create a heuristic that’d enable more efficient processing of header files 99% of the time, and which could then fall back to the traditional method of copy/pasting headers into the translation unit for the last percent of cases.

And why does every translation unit have to read every file every time? Can’t their contents be kept in memory, at least for a short time? Those hundreds or thousands of file accesses are painfully slow. Windows already exposes APIs for monitoring file changes, so it should be fairly simple to determine when a source file has been modified, and only then flush it from memory.

And of course, everyone’s favorite nitpick: Why is windows.h so absolutely horrible? Why does it have to be one monolithic header which gives us everything Windows has to offer? Why doesn’t it compile as standard C++? Why does it include so many other headers (as above, slowing down compilation)? Why does it pollute the global namespace with macros for ridiculously common names?

Well, it does, and it’d be silly to expect this to change, due to backwards compatibility concerns. But why then, is there not a windows.hpp or similar? Why isn’t there a separate cleaned-up, C++-compatible header? One which uses function overloading instead of macros, for example? Or which just defines simple forwarding functions instead of macros? One which compiles even with the non-standard language extensions disabled? Or why isn’t there a set of these headers, allowing us to access the bits of the Windows API we’re interested in, without having to include *everything?

In short, I think the MSVC IDE (and in some cases the compiler too) is in desperate need of a rethink. Out with those 12-year-old project wizards, which create complex predefined project structures accumulating every bad practice and unexpected project setting in one place. I’ve lost count of how many beginners I’ve seen choke because their tiny little projects automatically get a precompiled headers thrown in for absolutely no reason. Out with the idea that C++ can best be presented like C#, as a static language where every piece of code can be understood in isolation. Instead, give us an IDE that treats C++ as a more dynamic language, where many types of information are just not available until the program has been compiled, and which embraces the unique features of C++ — one which supports and encourages use of templates, one which accepts that in modern C++, most code ends up in header files, and these header files become expensive to compile, and so are an area ripe for optimization. An IDE which treats C++ compilation as an interactive process, where template instantiation can be stepped through and inspected at each stage, and where interactive queries can be made statically or during debugging to inspect not just data, but also types.

Another addition that would really boost the usefulness of MSVC would be to provide facilities for template metaprogramming in unit tests: For example, it is common to use metaprograms to force compilation failures if a template is instantiated with a specific type. But how do we test that this works as intended? Give us the hooks and language extensions necessary to specify that “this function is expected to fail to compile, and if it does, that’s not an error, just remove the function and compile the remainder of the file”. Again, consider compilation process a part of the language — it is something that must be inspected and debugged, and for which we may wish to write tests.

void my_testcase() __declspec(wontcompile){
  // perhaps we want to ensure that the template can not be instantiated with a reference,
  // so we expect this test to fail
  frobnicator<int&> f; 
}

// if the above test fails to compile (as it should), the compiler should simply ignore it, and proceed to compile the other tests, rather than aborting
void next_testcase() {... } 

Target your IDE at Modern C++, rather than C with classes. Impress the world by being the first IDE to even think about this. Embrace, and provide support for, the changes that have happened in the C++ language, in best practices and in the mindset of the C++ community. Accept that yes, headers are ridiculously heavy these days, and blindly recompiling them for every translation unit doesn’t scale. Accept that the C++ language needs IDE support to inspect what happens in our compile-time metaprograms as well as at runtime. And face up to the fact that traditional intellisense is a lost cause. There is no way to statically produce all the information we expect from intellisense. Some can be improvised by various heuristics, or as in the template function case, by assuming some suitable dummy value for the function’s template parameters, but others may be nearly impossible to provide until the program has been compiled. So perhaps you need to think beyond Intellisense to provide this information to the programmer. Perhaps an “interactive mode” would be more suitable. If the IDE can’t provide the information I need automatically, it could at least allow me to query for the information. Perhaps it can’t tell me anything about the template type T, but why can’t I tell it to assume that T is a std::wstring, and provide information based on this assumption. Or something else entirely. You already have a pretty good C++ compiler. It’s time to start working on a C++ IDE, and call it a day on the C IDE you’ve been polishing until now.

So dear MSVC team, in case you can’t think of anything useful to do with your time in the year 2010 (as if… I know you’ve got C++0x support to work on, and that’s infintely more important to me than IDE improvements), here’s a new year’s resolution for you: Amaze the world, by showing what a C++ IDE should work like. Reinvent the role of the C++ IDE, instead of trying to force the C# or C IDE to work for C++ as well.

Well, my test case for this feature now takes ages to run. As I mentioned previously, a simple transaction modifying two integer variables under heavy contention can pull off almost two million transactions per second on my laptop.

My new test, in which each thread takes four variables and alternates between modifying two of them and reading the other two, runs perhaps ten thousand (!) times slower.

Of course I have several leads on how to fix this. The problem is largely all the performance-related “extras” I’ve been leaving out. For example, if a transaction fails to acquire a variable it needs, it simply aborts and immediately retries. In many cases, a better approach would be to block the thread, waiting for that variable to actually become available.

There are several other cases where I have a similar problem: I have to choose between delaying the thread for a moment with sleep() before attempting to continue, blocking it until some condition is true, or aborting the transaction entirely and starting over from scratch. At the moment, I generally just pick the easiest solutions (typically abort, and occasionally call sleep() a few times before we resort to that. Again, implementing some actual meaningful policies here would make a big difference. And tweaking these policies should help still more.

Another problem is that currently, I do not enforce a consistent global order when acquiring objects during a commit. This means I risk livelocks, again causing excessive rollbacks when multiple threads are competing over access to the same variables.

So I’m still optimistic. It should be possible to get performance back on track. But man, it’s depressing watching performance plummet like this.

Edit
And an update. After poking around a bit, it turned out that most of the time was being spent sleeping. When a transaction attempts to commit, if it can not acquire all the all the variables it needs, it retries a few times with a short delay (a couple of milliseconds) in between. If it doesn’t succeed after a few tries, it rolls back the entire transaction and starts over.

It turned out that these few, short sleep() calls brought CPU utilization down to something like 0.01%, and totally destroyed performance. Simply turning the sleep() call into a no-op brought me back to something more or less reasonable. I still need to improve on the above shortcomings, but now at least I can run my tests in less than an hour.

In the following, I’ll show a slightly modified version of one of my test cases. It shows how to call and use my library, from the user’s point of view. The test spawns a number of threads, which each wait on a barrier (because if one thread was allowed to run while another was being constructed, I’d get fewer concurrent transactions, and my test would be less likely to uncover race conditions), and then perform a fixed number of transactions. In each transaction, two transactional variables are opened for writing, one is decremented and the other incremented. If the sum of these variables is nonzero in any iteration, the thread registers a failure.

And if, after all the threads have terminated, the value of each of these variables is not what was expected, a failure is registered as well.

So from a testing point of view, there should be plenty of opportunity for things to go wrong. Just a single small race condition somewhere, and one of the many millions of reads would be inconsistent and the test would fail.

#include <stm.hpp> // my STM library

#include <boost/test/unit_test.hpp> // Boost.Test is used to supply a unit-testing framework
#include <boost/thread.hpp> // Boost.Thread is used as a threading API

// define the number of threads to run, and the number of iterations for each
enum { thread_count = 8, iterations = 200000 }; 

// The following are transactional variables. The shared template ensures that the contained value
// can only be accessed as part of a transaction, and provides the necessary metadata
// for checking validity and consistency
// Two such integers are created, both initialized to zero
stm::shared<int> val1(0);
stm::shared<int> val2(0); 

BOOST_AUTO_TEST_SUITE( threads ) // define a test suite named "threads"

// this function defines the body of our transaction. 
// We're passed a transaction, which can be used to open any "shared" variables
bool tx_func(stm::transaction& tx){
    // open both variables for writing
    int& a = val1.open_rw(tx);
    int& b = val2.open_rw(tx);

    // modify the variables freely
    --a;
    ++b;

    return a + b == 0; // Our transaction returns a bool. Other return types (or void) are also supported
}

// this class defines a thread. operator() is called as the thread's entry point
struct thread_functor{
    // In the constructor, the thread object is given a barrier it can synchronize on,
    // and a reference where it can write the its result (success/failure)
    thread_functor(boost::barrier& bar, int& res) : bar(bar), res(res) {}

    void operator()(){
        // when the thread is first created, we wait for the barrier
        // This ensures that no transactions are running until all threads have been constructed
        bar.wait(); 
        for (int i = 0; i < iterations; ++i){
            // for each iteration, pass our transaction function to the "atomic" function, which executes it atomically.
            // To get a non-void return type, we have to specify the template parameter explicitly 
            // (this can be avoided in C++0x using the return_of template to deduce the return type implicitly)

            // depending on the return value of the transaction, write success or failure back
            res = (res != 0) && stm::atomic<bool>(tx_func) ? 1 : 0;
        }
    }

    boost::barrier& bar;
    int& res;
};

// another transaction, to be executed after our helper threads terminate, 
// to verify that the right number of modifications have occurred
// note that here variables are opened for reading only
void verify(stm::transaction& tx) {
    const int& a = val1.open_r(tx);
    const int& b = val2.open_r(tx);

    BOOST_CHECK_EQUAL(-a, thread_count * iterations);
    BOOST_CHECK_EQUAL(b, thread_count * iterations);
}

// finally, we get to our test case itself
BOOST_AUTO_TEST_CASE ( short_concurrent_transactions )
{
    boost::barrier bar(thread_count);
    boost::thread_group gr;
    int res[thread_count]; // array of results
    // set all the results to an initial true/1 value (since each iteration "and"'s it together with the current result
    std::fill(res, res+thread_count, 1); 

    for (int i = 0; i < thread_count; ++i){
        gr.create_thread(thread_functor(bar, res[i])); // create the threads, passing the necessary parameters to each
    }

    gr.join_all(); // wait for all threads to terminate

    // verify that each thread return success
    for (int i = 0; i < thread_count; ++i){
        BOOST_CHECK_EQUAL(res[i], 1);
    }

    // run a final transaction to access both variables and check their final values
    stm::atomic(verify);
}

BOOST_AUTO_TEST_SUITE_END()

In the above, I used a function object to represent threads, and a regular function to represent transactions. Of course in both cases, either would work — a function object would potentially be more efficient as it is easier for the compiler to inline, but I used a function for brevity.

In C++0x, of course, lambdas could also have been used in both cases.

One of my design goals has been to make basic usage as simple and intuitive as possible, and I think I’ve succeeded so far. Any C++ programmer who is familiar with the STL algorithms or the Boost libraries, should find my library’s interface very straightforward. Note especially that all the transaction “magic”, of verifying validity and retrying transactions as needed, is completely invisible to the user. You simply define a function expressing what your transaction should do, and pass it to the atomic function.

In its current version, this test is able to execute around 1,800,000 transactions per second on my Core Duo 2GHz laptop. (Of course, with transactions as small as these, opening only two variables each, performance is a lot better than it would be in real-world transactions.

So that’s it for now. Of course I’ve got a few more user-facing features in the pipeline¹, and a lot of backend changes, but the basic functionality is there, and I’m pretty happy with it so far.

It has really underlined to me just how deeply entrenched most Java, C and C++ programmers are in the imperative mindset. When we want to perform a transaction, we’ll need to execute something like the following pseudocode:

for (;;) {
  tx = new Transaction();
  try {
    // ... fill in body of the transaction ...
    tx.Validate();
    tx.Commit()
  }
  catch (InvalidTxException){
    tx.Rollback();
  }
}

And several STM systems actually require the user to write the above whenever a transaction is to be executed.

Some implementers have realized that this is both verbose, messy and error-prone. So they try to hide it behind a macro.

#define BEGIN_ATOMIC \
  for (;;) { \
    tx = new Transaction();\
    try { \

#define END_ATOMIC \
      tx.Validate();
      tx.Commit()
    }
    catch (InvalidTxException){
      tx.Rollback();
    }
  }

and now a transaction looks like this instead, from the user’s point of view:

BEGIN_ATOMIC
// ... fill in body of the transaction ...
END_ATOMIC

Which is obviously shorter and requires less duplicate code. On the other hand, it relies on macros. Eeeew, yuck!

In Java, most implementers have tried to extend the language, to add a language-level atomic statement, allowing code like this:

atomic {
  // ... fill in body of the transaction ...
}

And yes, this obviously works too, and has the potential to integrate much more closely with the compiler and type-checker. But it’s also a very imperative kind of thinking. “add another type of scope inside whichever function wants to perform the transaction”.

What astonishes me is that no one (apart from Peyton Jones, who implemented Haskell STM) have realized that what we really want is nothing more than a higher-order function. A function which implements the transaction infrastructure, and then calls a user-defined function.

What we’d like to do, ideally, is to define a function atomic, as in the following pseudocode:

T atomic(f : Tx -> T){
  for (;;) {
    tx = new Transaction();
    try {
      T ret = f(tx);
      tx.Validate();
      tx.Commit();
      return ret;
    }
    catch (InvalidTxException){
      tx.Rollback();
    }
  }
}

Of course, if we wanted to be really functional, we could use recursion instead of the loop, but let’s not get carried away. Ultimately, what we want is just to hide all the messy infrastructure of a transaction from the user.

The above declares a function atomic which takes as its parameter a function which, given a transaction (type Tx), returns type T.

atomic implements the messy transaction loop, and simply calls the user-supplied function inside it.

And presto, the user can now create a transaction like this:

int myTx(Tx tx) {
  // do whatever
}
int result = atomic(myTx);

Or, in a language which supports lambda expressions,

int result = atomic((tx) => {/* do whatever */ });

Bit nicer than messing around with user-implemented loops or macros, isn’t it? Of course, I’ve so far sought refuge within the peaceful realms of pseudocode, where anything is possible. We obviously can’t do this in Java or C++, can we?

No, and yes, in that order. In Java, I agree, we’re just screwed. Of course, we could just pass in an object instead of a function, and if it implements some ICallableTransactionBody interface, atomic could call its RunTx() method. That would work, but it’s not quite as elegant.

In C++, though, the situation is different. A large part of the standard library (all the STL algorithms) relies on higher-order functions. .

In C++, we can define atomic as follows:

template <typename Func>
void atomic(Func f){
  for (;;) {
    tx = new Transaction();
    try {
      f(tx);
      tx.Validate();
      tx.Commit();
    }
    catch (InvalidTxException){
      tx.Rollback();
    }
  }
}

First, I should mention that I cheated. I removed the return value. atomic now returns void. The reason is that it’s not quite trivial to infer the return type of a function in C++. TR1 does introduce a function std::result_of but it doesn’t work in every case. C++0x will fix this once and for all, by providing the necessary language features to implement it. But until then, we could hack around it, either by requiring the user to explicitly specify the return type (atomic<int>(myTx)), or by using result_of and simply telling the user to avoid the cases where it doesn’t work. But to keep the above code example simple, I simply removed the return type instead. But it can be solved, and my prototype does it.

Now, on with the show. We have now defined our atomic function. How do we call it?

In one of three ways, in decreasing order of familiarity:

First, with a function pointer. Hopefully every C++ programmer knows about these:

void myTx(Tx tx) {... }
atomic(myTx);

Fairly clean and simple. One downside is that because the atomic function is just passed a function pointer, the compiler may not be able to inline the call to myTx. It is doubtful that it’d make much difference here, but it is nevertheless a valid concern.

The second approach fixes this, as well as enabling some more flexibility: Functors, or function objects, which every C++ programmer should know about, but unfortunately, not everyone does:

struct myTx {
  void operator()(Tx tx) {...}
};
atomic(myTx());

Now we’re passing in an object of type myTx, which means that the compiler knows exactly which function to call: myTx::operator()(Tx). So it can inline this trivially, eliminating the above performance concern.

Perhaps more importantly, our function can now hold state. It is an object, so it can be given a constructor and destructor. It can be given other member functions to allow the user to interact with it. It has become a lot more versatile.

Finally, we can wait for C++0x, which introduces lambda expressions:

atomic([](Tx tx) { ...});

And what’s noteworthy is that the same atomic definition works in all three cases! So the user is actually given the choice of which method to use. Our STM library supports them all.

Isn’t this cleaner than the original approach, of requiring the user to implement the whole loop himself? So why have no one used it before?

Ultimately, I can think of two possible reasons:

• the writers, usually very clever researchers and academics, were not familiar with higher-order functions, or with functional programming in general, or
• the writers did not know that this was possible in C++

I suppose the second option is the most forgiveable. C++ is a big messy language, and not everyone are familiar with every corner of it. That’s fair enough, but even then, most of this could have been done in C too, by using function pointers. It’s not that esoteric, is it? But I sincerely hope it is not the first case. I could understand if Joe Coder at Insignificant Software Inc. had never heard of functional programming, but most of these are computer science professors!

Incidentally, this should also provide a nice example for when an imperative programmer asks “how would it benefit me to learn a functional language?”

Here we have a clear example of how using a very simple functional technique can significantly clean up the code and make it much more robust¹, even in an imperative language like C++.

Part I focused on the very fundamentals of C and C++, making sure that you understand the build system and the very basics of the syntax.

Part II expanded on this to teach you all the C++ you’ll need to do basic work in the language, including a few useful parts of the standard library, such as vectors and strings.

You now know all the basics we need, and the actual Win32 API should now be very simple to deal with. Not elegant or consistent, but comprehensible as long as you keep a close eye on the documentation and take nothing for granted.

First of all, the documentation can be found here. As you probably already know, Microsoft’s own search capabilities are nonexistent, and to find the function you need, you’ll typically want to use Google. But sometimes, the complete reference is useful, so here it is.

To teach you how to use the Win32 API, I wil, run you through a pair of functions with some very basic functionality: retrieving the last error message.

Should be simple, right? You’d think so, if you’re new to Win32.

The operation consists of two steps. First we have to retrieve the last error code, and then we have to ask Windows for the associated message as a string.

And the first step is indeed easy. We just have to call the GetLastError function. Let’s start with the complete code:

#include <windows.h>

int main() {
  DWORD error = GetLastError();
}

Feel free to run this in the debugger and see which code the function returns. (Most likely you’re going to get a 0, since no error has actually occurred at this point).

Now let’s look at the actual documentation. They describe the function as having this signature:

DWORD WINAPI GetLastError(void);

which looks like nothing we’ve seen so far. Let’s take the easy parts first. The function’s name is GetLastError. It takes a parameter of type void, or so it seems. This is actually a throwback to C, and means that the function takes no parameters. Both GetLastError() and GetLastError(void) is legal in C++. In C, the two used to have subtly different meanings. (void) properly declared a function which took no parameters, while () declared a function which took any number of parameters, but simply didn’t access them. But that was C. In C++, the two are identical, and we usually use () to indicate a function that takes no parameters.

Next, we have the return type at the far left. DWORD is short for Double Word (a word is the “natural” data size on the CPU, which, back in the old days, was a 16-bit integer. Hence, a double word is a 32 bits wide. Microsoft has defined DWORD as a macro alias for portability. Under the hood it is simply an unsigned int, but that may change some day. If it does, they will redefine the DWORD macro to stand for some other type. So if you use DWORD when they tell you to, your code will still compile when it happens. It is easiest to just nod and accept this. It doesn’t make a big difference for us, but if and when we need to, we know that we can cast a DWORD to an unsigned int

That leaves the last name, WINAPI, which exists for pretty much the same purpose. It is another macro, and stands for the calling convention. The calling convention for a function specifies how parameters should be passed to it, and where it should place its return value. If we don’t know the calling convention of a function, we can not call it. Normally, we’re happy to use the default calling convention, but the Windows API has to be specific, so they add the WINAPI macro. And again, they use a macro so that if they one day decide to change the underlying calling convention, they can simply redefine this macro, and everyone’s code should still compile with no problems.

Following this, they describe the parameters and return value in detail. This is always worth reading in detail, because often, some parameters may or must be NULL. Likewise, the return value may have several meanings, and there is no single consistent convention. Some functions return zero on success, others return non-zero, or a positive value on succes. Some don’t return a success code at all. And some functions returns NULL on error, and actual data on success. Always, always read this section carefully.

In this case, we’re lucky. It simply returns the currently active error code, although it does ramble on about all the inconsistencies caused by other functions.

The remarks section tells us other information that doesn’t fit under one specific parameter or under the return value. Again, this should never be skipped. This is where all the inconsistencies and special cases are often listed.

Some functions then have a link to an example usage.

Finally, the documentation shows us where and when the function is defined. In this case, we need at least Windows 2000, and the function is defined in WinBase.h (but we should just include windows.h).

And it is defined in the Kernel32.Lib library. This library is included by default, so we don’t have to worry about this.

So far, it hasn’t been too bad, has it? It should be clear already that it’s not a pretty API, but as long as we stick to the documentation it’s pretty straightforward.

So let’s move on to the FormatMessage function. Follow that link, and take a look… I’ll be here waiting.…

Done? Good. Now this looks scary. And no, this time I can’t give you a simple explanation. This function truly is scary. Of course, this is one of the reasons why I picked it for this example. This is about as bad as the Win32 API gets.

The page lists the following function prototype:

DWORD WINAPI FormatMessage(
  __in      DWORD dwFlags,
  __in_opt  LPCVOID lpSource,
  __in      DWORD dwMessageId,
  __in      DWORD dwLanguageId,
  __out     LPTSTR lpBuffer,
  __in      DWORD nSize,
  __in_opt  va_list *Arguments
);

__in, __in_opt and __out are Microsoft-specific extensions, and are mainly used for documentation and for static code verification. It tells us which parameters are used for input, and which ones are for output, as well as which ones are optional.

LPCVOID is another Microsoft macro. Microsoft spent a decade or two promoting Hungarian Notation before they had to admit what an astonishingly bad idea it actually was. But of course Win32 is stuck with it. The LP prefix stands for “Long Pointer”, and you can pretty much ignore the “Long” part. That dates back to 16-bit computers, where you actually had different types of pointers (far and near pointers). All we need to know is that it is a pointer. The C is for constant. In other words, this is a constant pointer to void, or const void*. (Of course, void isn’t a very meaningful thing to point to. A void pointer is essentially used as a pointer to an unknown type.)

LPTSTR is another adventure in Hungarian Notation. You already know LP. STR is probably obvious too. It’s a string. (Of course, since this is a C API, we’re talking about a C string, or a char pointer, which also explains the presence of the LP part. That leaves the T. What can that mean? I’m not sure. It might be “Template” or similar. It was introduced when Microsoft realized that they’d have to support Unicode. As I mentioned previously, Windows uses wchar_t for unicode text, and so their API had to accept wchar_t pointers when working with Unicode strings. But they still had to be backwards compatible as well, and be able to handle plain char pointers as well.

So they invented a new set of macros The T essentially stands for “whichever character type is currently active”. If you enter your project’s properties, you’ll see the option to enable or disable Unicode on the General tab. It should be enabled by default.

As long as Unicode is enabled, any macro including this T will be mapped to the equivalent macro using a W (for Wide). If Unicode is disabled, the macro will instead point to a similarly named macro without this character.

In other words:

• LPTSTR -> LPWSTR or LPSTR
• LPTCSTR -> LPWCSTR or LPCSTR
• TCHAR -> WCHAR or CHAR

And all of these again point to the types you would probably now expect. LPWSTR is a pointer to a wide string (wchar_t*). And LPCSTR is a const pointer to a string, or const char*. And WCHAR is a wchar_t.

As if this wasn’t complicated enough, the function itself is also a macro. Two versions of the function actually exist:

• FormatMessageA is the old ASCII version, using plain char strings.
• FormatMessageW is the “new” Unicode version, using wchar_t strings.

FormatMessage is not itself a function, but simply a macro, which is resolved by the preprocessor to one of these two. (C doesn’t allow overloaded functions, so they had to settle for this ugly hack to allow multiple definitions of the same function).

This also means that we can actually call these two names directly. If we call FormatMessageW, we’ll get the Unicode version regardless of whether Unicode is enabled in project settings. This makes it safe for us to use wchar_t strings directly, rather than mess around with TCHAR strings which might be one or the other.

Going back to the function declaration, the last parameter, va_list, looks a bit out of place. It’s not capitalized, and it doesn’t have these ugly prefixes. It is used in C to indicate a variable number of arguments, commonly known as varargs. As I mentioned in part I, printf uses varargs as well, and this throws away all hope of type safety, or even knowing how many parameters are pased to the function. Hopefully we won’t need to mess with this. (it’s marked as __in_opt, so it should be optional. Let’s hope we won’t have to use it then).

Anyway, there’s nothing for it. Let’s dive in. First parameter:

Ok, so this is a DWORD flag, and seems to store a combination of two values. The second table is shorter, so let’s take that first. There are three options here. A zero just means to preserve whatever line breaks exist in the message by default. the constant FORMAT_MESSAGE_MAX_WIDTH_MASK seems to preserve hardcoded linebreaks, but removes “regular” ones. I have no clue what the difference is.

The last option (mentioned just under the table) is to store any other number into the value. This then specifies the maximum line width. We’re happy to just use the default line breaks though, so we’ll settle for the zero value. That leaves the first table.

Looking through the options there, it seems that we need FORMAT_MESSAGE_FROM_SYSTEM. FORMAT_MESSAGE_ALLOCATE_BUFFER seems potentially interesting as well, but this table doesn’t really explain what happens if this flag is not enabled. If the system doesn’t allocate a buffer for us, who does? Looking down further, at the input parameter nSize we see that:

If the FORMAT_MESSAGE_ALLOCATE_BUFFER flag is not set, this parameter specifies the size of the output buffer, in TCHARs.

In other words, if we don’t use this flag, we have to provide a buffer. But we don’t know the length of the message we’re trying to retrieve, so this seems a bad idea. (Of course we could just provide a buffer of 64KB, which the documentation mentions is the maximum size, but this seems silly).

Finally, if we skip down to the “Security Remarks”, it says to add FORMAT_MESSAGE_IGNORE_INSERTS if we’re going to pass “arbitrary system error codes”, which we are. Most API’s try to ensure that the simplest action is the correct one. Win32 seems to be designed for the opposite case, ensuring that that correct usage should only be possible if you have already read the entire documentation page, very carefully, and at least three times. But that won’t stop us.

So the dwFlags parameter should then be the combination of these flags: FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_IGNORE_INSERTS | 0‘, although of course the 0 can be omitted.

Next, we have lpSource. Luckily, this is marked optional, and it is stated that this is ignored unless one of the two listed dwFlags values are set, which they’re not in our case. So we ignore it and simply pass NULL.

Then we have the message ID. This must be the value we got from GetLastError. Then we have the language ID. Rather than going searching for possible values to pass here, we can see that if we just pass a zero, it’ll try to pick a sensible default. So let’s do that.

Now comes the pointer to the output buffer. Read what it says here carefully:

If dwFlags includes FORMAT_MESSAGE_ALLOCATE_BUFFER, the function allocates a buffer using the LocalAlloc function, and places the pointer to the buffer at the address specified in lpBuffer.

So the parameter lpBuffer is a pointer to the pointer to the buffer. That is, we must pass it a pointer to the pointer it should set to point to the allocated buffer.

It also mentions that the buffer is allocated with LocalAlloc, and must be freed by us with LocalFree. Better remember this, or we’ll leak memory. Note that Windows defines several different memory allocation functions. This time they chose to use LocalAlloc. C++‘s new and delete are implemented in terms of some of these, but who knows which?.

Now comes nSize. It allows us to specify the minimum number of characters to allocate? Why would we care about that? Let’s just pass zero and hope for the best. It’s just a minimum after all.

Finally, we have Arguments. We already specified that the system should ignore inserts, so it seems like it shouldn’t actually care about these arguments. They’re also specified as optional, so let’s pass a big fat NULL here.

And that should be it! Now we just have to handle the return value:

• zero on failure, or
• the number of TCHARs stored in the output buffer, not counting the terminating NULL

And… we’re through. Now let’s try putting the pieces together and see what happens:

#include <windows.h>
#include <iostream>

int main() {
  DWORD error = GetLastError();

  wchar_t* buffer;

  DWORD length = FormatMessageW(
  FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_IGNORE_INSERTS,
  NULL,
  error,
  0,
  (wchar_t*)&buffer,
  0,
  NULL);

  std::wcout << buffer << std::endl;

  LocalFree(buffer);
}

Note the ugly cast we need to on the buffer. This is necessary because the argument may be either a pointer to a pre-allocated buffer, or (as in our case), a pointer to a pointer we’d like to be set to point to the system-allocated buffer. But the function expects a pointer to a string buffer, not a pointer to a pointer to a string buffer, so if we want to pass it the latter, we have to cast it to the former type.

Note that I’m calling the W version of the function specifically, and using wchar_t instead of TCHAR. The reason is simple. I want the Unicode version, regardless of Unicode setting in the project. Part of the reason is that it’s a lot easier to print out the string when we know what type it is. In particular, the standard library requires us to use cout for regular character strings, and wcout for wide strings. If we’re given a string of TCHAR’s, do we call cout or wcout to print it? Easier to just be specific and make sure we have wide characters.

Well, that’s it. Try running it. It should print out that “the operation completed successfully”. Gee, thanks. That really makes it all feel worthwhile, doesn’t it? Make sure you understand what our code means (in particular, why the cast is necessary, and how wcout is able to print out the string and know where it ends, when all it has is a pointer to a character.

Anyway, you’ve now seen some of the worst the Win32 API has to offer. And you’re still alive. Many of the functions you might want to call are far simpler than this.

In part I, I went through a minimal “Hello World” program in some detail, and attempted to explain the arcane workings of the C/C++ compilation model. Some may argue that this had no relevance to my target audience, but I think it is a necessary evil. Almost all C++ programmers get tripped up at some point by the the difference between compiler and linker errors, and what exactly the #include directive actually does. Hopefully, by reading part I, you’ll be able to avoid this.

With that out of the way, we can get started on the interesting part, though. Part II will focus on actual C++ code. We won’t consider managed interop or even the Win32 API yet, though. This part will still take place in native C++-land only. In short, the purpose of this part is to enable you to write simple C++ programs, and more importantly, to understand the C++ sample code you probably run into from time to time.

I will not cover all the idioms and techniques that “real” C++ programmers use. We’ll settle for the bare minimum required to get by in a .NET-to-Win32 interop scenario where you really just want to write enough C++ code to call some native API function. This means that we won’t get the most robust, reusable, elegant or concise C++ code. But we will be able to get the job done.

I’d love to write a more detailed series of posts about “modern C++“¹ some other time, but it is beyond the scope of this series of posts.

Using C++

Before we get into the Win32 API, let’s run through some slightly bigger C++ examples than the Hello World from part I. At the very least you’re going to need to know how to define and use classes, and a few useful components in the standard library.

You already know that it is possible to define class member functions outside classes, but you haven’t yet seen a nontrivial class definition. Let us try creating one. For the purposes of demonstration, I’ll implement the simplest class I can think of; a counter. It’ll simply contain an integer, and callers will be able to increment the value, and get the current value.

class counter {
public:
  counter() : i(0) {}
  int current() {return i; }
  void update() { ++i; }
private:
  int i;
};

There, we now have a basic class. We can call it from this function: (I use assert to indicate expected values of variables, much like you would in a unit-test. Note that the asserts are pseudocode (among other things, I will access private class members with them, which obviously won’t work in reality)

// assume that we either placed the class definition here, or have a #include for the header in which the class is defined.
int main(){
  counter c;
  int i = c.current();
  assert(i == 0);
  c.update();
  assert(c.i == 1);
  assert(c.current() == 1);  
}

A ridiculous simple program, of course. But there are several things worth noting. In no particular order:

• Our counter object c is created without using new, and without explicitly calling a constructor. All C++ types are fundamentally similar to .NET’s value types — so c is not a reference to a counter, but instead a default-constructed instance of one, placed on the stack. If nothing else is specified, the default constructor is called when the variable is declared. (To call another constructor, we could have done something like counter c(1, "hello", 2.0f);.
• the class definition is terminated by a semicolon. This is important to remember, as forgetting it can lead to very misleading compiler errors. I won’t get into why this semicolon is necessary here though. It is a long story, and it is caused by the need for C compatibility.
• access specifiers are not applied per-member, but rather used to divide the class into sections. In a class, the default specifier is private. I tend to put my public members at the top of the class, to make it easier for readers to find the public interface. Further down, we have a private specifier, for hiding our int member. The valid access specifiers are public, private and protected, which each behave just like in C#. internal does not exist however, since there is no notion of assemblies, and the only way to share types between files is with #include’s as mentioned in part I.
• there is no clear, common naming convention in C++. The standard library users lower-case, and separate words by underscores, as in class_name. Many programmers however, use a convention similar to in .NET, naming types ClassName, and variables className. There are no fixed rules, so as long as you are consistent it’s fine with me.
• .NET has both classes and structs, and the two have very different meanings. In C++, both classes and structs exist as well, but their meaning is almost the same. The only difference between a class and a struct in C++ is that a struct defaults to public accessibility for members, where a class defaults to private. In other words, if I had defined the above as a struct, I could have omitted the public: line. (For this reason, I often find myself using structs. As I said, I tend to put the public interface at the top of the class, and add a private: section further down. However, it is not a big deal. A common rule of thumb is much the same as is used in C#: Structs are simple containers of data, where classes have behavior. My own style tends to be a compromise between the two. Classes with complex behavior are made classes for this reason, but in simpler borderline cases, I tend to prefer struct, even if it has some behavior. It makes no difference to the compiler, and it saves me a line of code, because it defaults to public, which is what I want at the top of my class anyway.)
• the observant reader will probably have noticed a difference here compared to the example shown in part I. Back then we declared the member method without defining its body inside the class. Now we define the body inside the class. Both approaches are legal, and each have their pros and cons. In particular, defining the body outside the class leaders to shorter class definitions, which may aid readability. On the other hand, defining functions inside the class leads to better locality — you only have to look in one place to learn all about the class. Further, the compiler is generally better able to optimize code if member methods are defined “inline”. For these reasons, people often put short functions of 2–3 lines or so inside the class, and define larger ones separately. There is one caveat, however. Functions defined inline (either by placing the full definition inside the class, or by marking the definition with the inline keyword) may have a definition in each translation unit. In other words, they may be placed in headers (where they’re seen by multiple translation units. Non-inline functions must only be defined once, and so generally have to be defined in a .cpp file, similar to what we did in part I.
• the constructor looks a bit different than you may be used to. The i member is initialized via the initializer list, specified after the colon. This is similar to how you would call a base class constructor in C#, although instead of base, the member name is used. Also note that we have to explicitly initialize i because as a primitive type, it would otherwise not be initialized at all. The initializer list syntax is only legal in constructors, and should be used as much as possible. I’ll explain why in a moment.

“Special” member functions

We could have defined the constructor in a more familiar way:

counter() {
  i = 0;
}

and in this simple case, it would have made no difference. In more complex classes, however, there is an important distinction: anything that happens in the constructor’s body happens after members are initialized. If the member is not specified in the initializer list, it is default initialized, which means that for primitive types, nothing happens, they just contain random garbage values, and for classes defining a default constructor, it gets called before the constructor’s body is evaluated, in which we assign the actual value we want the member to contain.

So yes, for our simple int case, we might as well have written the constructor without using the initializer list. But consider what would have happened if the member had been some complex user-defined class. Instead of simply constructing the object with the right value to begin with, we would have default-constructed it, and then executed an assignment. This would obviously have been less efficient than simply constructing the object correctly in the first place.

But just as importantly, some types can not be assigned to once they are initialized. Likewise, some types may not have a default constructor, in which case failure to use the initializer list to explicitly call another constructor will result in a compiler error! So in general, the initializer list should be preferred both from performance and correctness concerns. A side effect of the initializer list is that the actual body of constructors can often be left empty.

In .NET, there is a distinction between value and reference types, and the behavior of the assignment operator is completely different for each of the two cases. x = y for values of a reference type simply stores a reference to y into x. But if the two types are value types, a complete copy is created instead.

In C++, all variables obey value semantics. x = y will always copy the value y into x. This is why I said when discussing the constructor’s initializer list that an extra assignment may be expensive.

Since the plain value semantics as used by C# would be both inflexible and inefficient, C++ provides a number of tools for controlling the behavior of your class. In particular, you can define a copy constructor and an assignment operator to override exactly how assignment should be performed. The following demonstrates what they may look like.

class counter {
public:
  counter(const counter& other) : i(other.i) {} // copy constructor
  counter& operator= (const counter& other) { // assignment operator
    if (this == &other) {return *this; }
    i = other.i;
  }
  ....
};

Perhaps the first thing we should mention is the meaning of the & character. It is used to denote a reference, essentially an alias for a variable. It is related to pointers (see this post for a more detailed explanation of pointers), but is simpler and more limited. In particular, it can not be reseated. Once it is initialized, it is an alias for the variable it points to forever. Also, unlike pointers, there is no special syntax for using a reference:

int i; // create an integer.
int& r = i; // create a reference as an alias of i. Note that we simply assign i, unlike with pointers where we would have had to take the address of i first with the `&` operator.
r = 42; // assign 42 to whatever the reference points to. Again, no special syntax. There is nothing here to tell us that r is a reference.
int j = 13; // create another integer
r = j; // assign it to our reference. The effect of this is *not* to make r point to j (as would have happened had it been a pointer), but simply to assign the value of j to i. In other words, i will now equal 13, and r will still point to i.

Because a reference can not be reseated, it is also a nice example of a case where the constructor’s initializer list must be used. Imagine a class which has a reference member. References must point to something, so they have no default constructor. And once they are initialized to point to an object, they always point to that object. In other words, it must be constructed before the constructor’s body is executed, which means in the initializer list. Failure to do so simply won’t compile.

Now to explain the copy constructor, which is fairly simple. It is simply a constructor which takes one argument, a const reference to the type itself. Copy constructors are commonly used to initialize class members with copies of the arguments passed to the “outer” class’ constructor. In the copy constructor above, we also copy-construct i, for example. (The value of other.i is copied into our own i)

The assignment operator is a bit trickier. The first line inside it tests for assignment to itself. (As would happen in x = x). This may not have been a problem in this simple class, but in more complicated ones, self-assignment can cause problems, as you will be reading data from the same object you’re writing to. We also note that instead of simply comparing this to other in the test, we use &other. We wish to check that this and other refer to the same object instance, not just that they contain the same value. To achieve this, we need to compare pointers. this is already a pointer², but other is a reference, so we have to take the address of it first. Because a reference is essentially an alias for the referenced value, the address-of operator returns the address of the referenced value, not of the reference itself.

Next, note that the assignment operator does not have an initializer list, but instead performs the copying in the function body. The reason for this is obvious: It is not a constructor, so all its members are already initialized. An initializer list would not make sense, and is not allowed by the language. This also means that here, i’s assigment operator is invoked, rather than its copy constructor, as was used in the previous example. (Technically, built-in types have neither assignment operator or copy constructor. However, the same syntax is allowed, it simply uses the obvious built-in operations.)

A final note about assignment operators and copy constructors is that if = is used to declare a variable, the copy constructor, and not the assignment operator, is called. As I said before, these functions are special and known to the compiler, and so, can be invoked in special cases. That is, if you are given variables c and d of type counter, then c = d calls the assignment operator on c, because c is already initialized. But if it had instead been counter c = d, then c would have been initialized as a copy of d, and so its copy constructor would have been used. The compiler ensures this, even if you use assignment syntax in the initialization of a variable.

Finally we get to another dreaded C++ construct: the destructor. This is automatically called when the object is destroyed, and can be defined thusly:

class counter {
public:
  ~counter(){
    std::cout << i << std::endl;
  }
  ....
};

The syntax is similar to finalizers in C#, but the effect is somewhat different. The destructor is invoked instantly when an object is deleted, and it is guaranteed to be called. In our case, we simply use it to print out the counter value.

Let’s try using these new functions and operators:

int main(){
  counter c; // use the default constructor to create a counter
  c.update(); // increment its value
  assert(c.i == 1);
  counter d(c); // use the copy constructor to create a new copy of our existing counter.
  assert(d.i == 1);
  d.update();
  assert(c.i == 1); // our copy constructor made sure to create a *new* counter variable, so c is not affected by changes to d, and vice versa
  assert(d.i == 2); 
  c = d; // since c has already been initialized, the assignment operator is used to copy d into c.
  assert(c.i == 2);
} // at this point, both c and d go out of scope, and so their destructors are called. Destructors are always called in opposite order of destruction, so d's destructor will be invoked first.

All three functions are auto-generated by the compiler, if not declared explicitly. (The one exception is the assignment operator, which it may not be possible to auto-generate. If a class contains a member with no assignment operator, or a reference (which can not be reseated), the compiler will fail to generate an assignment operator, and all attempts to perform assignment will fail if one is not explicitly defined by the user.

The trio of copy constructor, assignment operator and destructor are sometimes called “the big three”, or we may speak of “the rule of three”. This is a rule of thumb that if you find yourself implementing one of these three special functions, you almost certainly should also implement the other two. The reasoning is pretty simple: The assignment operator and copy constructor are related — both are used to copy an object. If special care has to be taken when copying, then it should probably be defined for both these functions.

Further, if copying requires nontrivial handling, then it is a good bet that the class manages some kind of resource or contains data which requires special care in the destructor as well. Perhaps a pointer pointing to dynamically allocated memory, which must be deleted, or perhaps it should decrement a global counter used to count the number of live instances of the class. Or perhaps it is a file handle which must be closed. The fact that we had to implement special handling when copying is a strong hint that there will probably also be special handling required when cleaning up in the destructor.

And the converse is also true. If the destructor has to do something special, it must be because the class owns some kind of resource that must be released. And if it owns a resource, then we should ensure that the resource gets copied when the class itself does. So we should probably define copy constructor and assignment operator as well.

POD types

A final note about classes may be worth mentioning. C had no classes, only simple structs containing values, but no member functions, and without allowing inheritance or access specifiers. Since C++ was designed to be (mostly) backwards-compatible, such types have a special status in C++. In the above, I mentioned “primitive types” a few times. While an int is technically a primitive type (all built-in types are considered primitive types), the behavior I described is actually common to all POD (Plain Old Data) types. A POD type is essentially a type that would have been legal in C — in other words, it is either a built-in (primitive) type, or a class or struct where

• all members are public
• no member methods exist
• no constructor, copy constructor, assignment operator or destructor is defined
• no base classes exist
• All members are POD types as well

Such POD types are given special treatment in many ways. For example, they may be treated as “raw memory”. The standard-library C function memcpy, which simply copies a number of bytes from one location to another, may be used to copy POD types, but not non-POD classes. The reason for this is that non-POD types may have extra behavior that would break if this was done. As an obvious example, if we created a copy in this way, we would bypass the assignment operator/copy constructor, but we would end up with two objects, both of which would have their destructors called when deleted — so we would end up with a mismatch where the destructor is called more often than the constructors, a clear error if the class implements reference-counting, for example.

Another peculiarity of POD types is that they are not initialized unless a constructor is explicitly called. this is why we had to initialize i in our constructor above. As a POD type, i would otherwise contain whatever garbage value was found in memory. The same is true for POD structs. They too contain garbage if not explicitly initialized by calling a constructor:

int i; // no initialization occurs
int i(); // explicitly require default initialization -- for POD types, this is done by setting all members to zero.

In other words, had our counter class stored a non-POD member, the initializer list would not have been necessary. Its member would automatically be default-constructor if nothing else was specified. But POD types do not have that extra behavior, so if nothing else is specified, they simply don’t get initialized.

Enough about classes

There are a few other nitty-gritty details about the language we should discuss. You may have already wondered about one or two of them. So without further ado,

• variable declaration is usually done without using new. The new operator allocates memory on the heap, and returns a pointer to the newly declared variable. Since there is no garbage collector, we have to manually call delete on this pointer to free the memory. This is the source of C++‘s reputation as a playground for memory leaks. Of course the astute reader will have noticed that so far, I haven’t used new and delete even once. The truth is that these can often be avoided or hidden, thus removing all possibility of memory leaks. Any variable declared without using new is declared “locally” — if it is declared in a function, it becomes a local variable, and is destroyed when we leave the scope in which it is declared. If it is a class member, it is destroyed when the owning class is destroyed. If it is declared inside a loop, it is destroyed when we leave the loop, and if it is defined in a function, it is destroyed when we leave the function. In other words, variables declared without new have “automatic storage duration”, and in fact, int i = 42 could also be written as auto int i = 42. The auto keyword indicates exactly this, that the lifetime of the variable is automatic. Since this is the default, the keyword is never actually used, but it exists, and this is what it means. And just to clear up any doubts, variables with automatic storage duration are destroyed when we leave the scope it was declared in, no matter how we leave it. It doesn’t matter if we return from the function, or if an exception is thrown. In both cases, the local variable’s destructor is called.
• Just to avoid confusion, we’d better look at a quick example of using new: Consider this line of code: counter* p = new counter(). Here, we allocate an object of our counter class on the heap, with dynamic storage duration, but we also declare a local variable — the pointer p. The pointer is a local variable with automatic storage duration. In other words, the pointer itself will be freed just fine when we leave the function — but the dynamically allocated counter to which it points will not. This is how memory leaks occur. Once p gets destroyed, we no longer have a pointer to the dynamically allocated memory, so we can never free it.
• Avoiding cyclic dependencies can take a bit of work, since C++ code is read by the compiler from top to bottom. It won’t let a function or class refer to another which hasn’t been defined yet. Sometimes, this can be solved through refactoring, by splitting out the code we need to refer to, out into a separate class which can be declared first. But another trick is to use forward declarations. You have already seen it used for the class member method in part I. We can declare a function without specifying its body. This tells the compiler that the function exists, which means we can call it safely. So if we put such a declaration at the top of a file, we can provide the actual definition including the body at the end of the file, after whatever classes or functions we need to refer to. For classes, we can do a similar trick, and simply declare class counter;. As with the function case, this tells the compiler that counter is a class, and that it does exist. The definition just isn’t shown yet. This won’t let you access class members yet (since the compiler still doesn’t know which members it has), and you can’t declare variables of that type yet (because the compiler doesn’t know which, if any, constructor to call, and it doesn’t know the size of the class). But you can create references and pointers to the class.
• C# uses function overloading to allow for functions where some parameters may have sensible default values. If we have a function taking parameters a and b, we can create an overload which takes only a, and provides a default value for b. The same can be done in C++, but you also have the option of providing default values. The function void foo(int i = 0) {std::cout << i << std::endl; } can be called just with foo(), and will print out 0. If you are more comfortable with overloading, you may not need to use default parameters, but you may still encounter third-party code which uses them, so you should be familiar with the syntax.

The standard library

We’re nearing the end. The last thing you should know about C++ before I let you run loose is a few standard library classes. The C++ standard library is very small compared to .NET or Java’s class libraries, but it is also widely considered C++‘s main saving grace — most people consider the language an overcomplicated mess in many ways, but the standard library stands out, both as an example of C++ done right, and as a redeeming feature which transforms C++ into a powerful and elegant language³. Or more precisely, part of the standard library possesses these qualities.

In the following I’ll briefly sketch out the main parts of the standard library, and explain a few useful classes. For more general information, Microsoft has some excellent documentation for all parts of the standard library here.

The standard library has been assembled piecemeal over the years, and as such, represents several different styles and paradigms. The oldest parts of it are simple functions carried over from C’s standard library. I have already mentioned two of these, printf and memcpy, but of course many others exist.

After these came the first C++-specific additions, in the form of the iostreams library. You have also encountered a few members of this, in cout, cin and endl, as well as the operator<< used for streaming. This library is, honestly, not very nice. It does the job for simple Hello World-like applications, but it is inflexible, inefficient, overcomplicated and hard to extend. In fact, many C++ programmers stick to printf over cout despite all the disadvantages I listed in part I. Of course, iostreams also contains file streams as well as some other basic stream functionality. A related addition is the string class, and the locale facilities.

These all have one thing in common: they are very old-fashioned and are, today, considered far from ideal. The string class got some last-minute surgery when it was added to make it a bit more modern, and a few additions were made to the stream classes as well, but overall, these are relics from the era of “C with classes”.

Finally, the star of the show is the Standard Template Library, or the STL for short. This remarkable library completely changed the how the language was used, and is definitely worth exploring. I won’t ramble on about it here, but I will mention that one of its characteristics is that it almost completely abandons traditional Object-Oriented programming (which iostreams used heavily), in favor of the less known and almost C++-specific paradigm Generic Programming.

The STL consists of three distinct “pillars”:

• Container classes are the equivalents of .NET’s System.Collections.Generics classes. They store sequences of data, and little else.
• Iterator classes are superficially similar to .NET’s IEnumerator. They allow traversal over a container, but where .NET only allows traversal from the beginning to the end, C++ iterators also allow reversed iteration (from end to beginning), as well as traversal over subsets of the container (from the 6th to the 12th element, for example). Pairs of iterators are often used to mark sequences for further processing. Individual iterators are often used as “markers” into a sequence.
• Algorithm functions work on iterators, or a pair of iterators, and perform almost all sequence processing. Sorting, searching, copying, foreach, accumulating values or any other algorithm involving sequences of data is implemented as an algorithm working on iterators.

The clever part about this setup is that algorithms and containers know nothing of each others. An algorithm works on iterators, wherever they come from. It works whether the iterators are pointers into an array, into a linked list, or perhaps even into a stream or a database. As long as the iterator implements the appropriate functionality, it can be used by the algorithms. This allows for a degree of reusability that would have been impossible in .NET. The same find function for example, works on all of the standard container classes, in addition to working on any iterators your define yourself. As long as they fulfill a few basic requirements, you get find, sort and many other common operations for free.

And again unlike .NET, there is no interface you have to implement to create a new iterator type, or, for that matter, a new container class. The STL relies on a form of Duck Typing (if it looks like a duck, and walks like a duck, and quacks like a duck, it must be a duck) — this means that an iterator is not “a class which implements IIterator<T> or anything like that, but simply “A type T for which the following statements are defined, given an object x of type T: ++x, *x, T() and a few others. In other words, if a type defines a default constructor and a few operators, then it is an iterator, and it’ll work seamlessly with the rest of the STL. In fact, raw pointers are valid iterators as well.

In .NET, every collection class has to define its own search function, and there is no elegant way to decouple it completely. (We could define the function in a static helper class, but it would still be working on something specific like an IList, rather than just any sequence). In C++, the function std::find works on any pair of iterators.

While iterators and algorithms are key to “modern C++”, I will focus on the containers here, as they can be used with little explanation, and are almost indispensable (just like you wouldn’t want to program in C# without the List<T> class)

The equivalent of .NET’s List<T> class is the vector:

#include <vector>

int main() {
  std::vector<int> v;
  v.push_back(1);
  v.push_back(2);
  v.push_back(3);
  v.push_back(42);
  v.pop_back();
  // v now contains the values [1, 2, 3]
  v.resize(5); // resize to contain 5 elements
  // v now contains [1, 2, 3, 0, 0]
  assert(v[1] == 2);
  v[3] = 42;
  // v now contains [1, 2, 3, 42, 0]
  int& r = v[0]; // create a reference to the first element
  int* p = &v[0]; // create a pointer to the first element
}

Pretty straightforward. And again, note that we’ve managed to create an arbitrary number of objects in our application, without even once having to call new. Which also means that there is no possible way in which this application can leak memory. (short of bugs in the compiler or standard library).

There are a couple of caveats to be aware of though:

• There is typically no bounds-checking on the [ ] operator. This doesn’t mean it is legal to do v[999] above, it just means that there is no guarantee of what will happen if you do it. It is undefined behavior.
• Pointers and references to individual elements within a vector may be invalidated when we add elements to the vector. Like with C#‘s List<T>, it is a dynamic array, and resizes as necessary. Each such resizing operation consists of allocating a new array, copying the contents into that, and then freeing the old array. A pointer to data in the old array is therefore no longer valid. The same applies for iterators. Any iterator pointing into a vector is invalidated if the vector is resized.

Because a vector guarantees that its data is stored contiguously, essentially as an array, we can use this class instead of an array when interfacing with old C code (which only has pointers and arrays, but no vectors). In the above, the variable p could be passed to a C function as a pointer to the beginning of an array of int’s. we still have to be careful of course. The function must not be allowed to write past the end of the array.

Other container classes are the the map (equivalent to .NET’s Dictionary<Key, Value>. std::map<Key, Value> in the map header), and the set (no equivalent in .NET 2.0, although HashSet<T> in 3.5 is similar). Works much like a map without the Value parameter: std::set<T> in the set header). Their use is pretty much as you would expect.

In general, I would discourage you from using arrays. Prefer vectors instead, and if an API expects a pointer to an array, pass it a pointer to the first element of the vector instead, as shown in the previous example. Vectors are safer and simpler to work with.

Strings

A final pair of classes worth mentioning are std::string and std::wstring. C++ has no built-in string type, and so to work with strings, you have to include the string header, and use these classes. A string is simply a string of char’s, single-byte characters. A wstring is a string of wchar_t’s, or wide characters. On Windows, these are 16 bits wide, and use the UTF16 encoding, allowing them to be used for unicode strings.

These classes behave much as you would expect, so I won’t discuss them further. Instead I’ll skip to a related point of confusion: C has no string type at all. Instead, char pointers (or wchar_t pointers) are used as primitive strings.

A C-string is simply a sequence of characters, terminated by a null character ('\0'). If the null character is left out, all C string functions will just assume that the string continues until a null character happens to be found. This is obviously extremely fragile and a common source of bugs. but it’s an unavoidable fact of life when interfacing with C code.

This also rears its head when working with string literals. "hello world" does not have type std::string in C++. It has type const char[12], that is, an array of 12 const characters. (Note that the string is only 11 characters long. The compiler automatically generates the terminating null, and sets aside space for this as well).

Arrays in C and C++ are very primitive and fragile things, and implicitly decays into pointers when needed. Whenever you have an array, you can assign it to a pointer, and the pointer will automatically point to the beginning of the array. Because arrays are so limited (a function can not return an array or take an array as argument either), arrays are often passed around as pointers — and in fact, pointers can be treated much like arrays as well. Given a pointer p, p[2] is legal, and is equivalent to *(p+2). But because it is just a pointer, the size of the array isn’t known. It is up to the programmer to keep track of that.

Getting back to strings, the way arrays can decay into pointers means that this is legal: const char* str = "hello world". The pointer str now points to the statically allocated array of characters “hello world”, and for all practical purposes, str is now a C-string.

To create a wide string literal, the string is prefixed with a ‘L’, as in wchar_t* wstr = L"hello world".

Because C-style strings are used in most API’s, you often need to convert between this and the C++ string class. This can be done as in the following:

const char* str = "hello world";
std::string str2 = str; // an implicit conversion exists from char pointer to string. So in addition to this line, 'std::string str = "hello world" would also have worked.
const char* str3 = str2.c_str(); // the c_str() member method on the string class returns a C-style string.

Because string literals are C-style strings, there are a few pitfalls to be aware of when using them:

char* str = "hello worl";
char* str2 = str + str; // #1
str += 'd'; // #2

In line #1, we get a compile error. Because str is just a pointer, addition is not defined, and so the compiler chokes. A related example is in #2 where we try to add a character to the string. This compiles, perhaps surprisingly, but it won’t do what you expect. Instead, the char gets converted to an int, and added to the value of the pointer. So the result is a pointer to 'd' characters past the beginning of the string.

For these operations to work, we must have a proper C++ string:

std::string str = "hello ";
str += "worl";
std::string str2 = str + 'd';

will work as expected, and result in the string “hello world”.

You now know all you need to know about C++ to use it without shooting yourself in the foot too much. You also know enough to read a lot of the code snippets you’re likely to find online. And you’ve got a starting point for searching out more information should you wish to.

In the next installment, we will finally get to interfacing with the Win32 API. You may want to play around a bit with the compiler to make sure you understand pointers and C-style strings in particular, as we’re going to need those quite a bit. As I mentioned in part I, the Windows API is a C API, and an ugly, inconsistent one at that. It’s not a bad idea to make sure you’re somewhat comfortable with the basics of the language before trying to grapple with it.

So we took an afternoon out to run through some basic C++ code, and while we had fun doing it, and I’m pretty sure he found it interesting, it didn’t really achieve the goal of making him comfortable with writing small C++ programs to communicate with native APIs such as the Windows one.

Afterwards, I realized that the reason for our failure was that we hadn’t really made it clear what we were trying to achieve. He might have been interested in C++ in general, but what he actually needed was something a bit simpler: Being able to call native (primarily Win32) APIs.

Of course, the difference between these two is not obvious. In the .NET world, the two would basically have been the same thing. In learning C# (or another .NET language), you also learn to interface with .NET APIs, and if you need to interface with these APIs, you have to learn a .NET language.

In the case of C++ and native APIs, the situation is a bit different. Learning the language does not guarantee proficiency with using native APIs, and native APIs can be used without knowing C++.

So this series of posts is going to be my second attempt at teaching a .NET developer to at least be able to set up a basic native application, and more importantly, to call a function in the Win32 API.

The following is not a completely general introduction to C++. If you actually intend to learn and use the C++ language, there are many better texts to follow. I might even write my own attempt one day.

In this series of posts, I will

• assume familiarity with programming in .NET or another managed platform (such as Java). You’ll probably be able to get by as well if you’re coming from another high-level language such as Python or Ruby, as long as you can understand the basic syntax of the C family of languages.
• leave out a lot of things a “dedicated” C++ programmer should know. The goal is not to turn the reader into a professional C++ developer, but simply to break down the wall and enable you to make occasional forays into native-land to call an API function or two before heading back to your favorite language.

Before we begin

Before we get into the actual code, there are a few peculiarities of native languages to be aware of.

Almost all native APIs are actually written in C, not C++. Both languages have some responsibility for this. Part of the reason is that C is the lingua franca of programming languages. When your Python code has to talk to your Java code, they use a C interface. Virtually every language has C wrappers available to allow it to communicate with C code. So by writing your API in C, you ensure that every language can use it without too much trouble. And of course C is a very simple language, so almost any language can cope with a C API. There are no classes, no higher-order functions or exceptions or other pecularities of more modern programming paradigms. So part of the reason is that C is simply a good intermediate language.

The other part of the reason is found in C++: C++ has no fixed ABI¹. C++ functions compiled by one compiler can not be called from code compiled by another. And when C++ compilers can’t cooperate, entirely different languages don’t stand any chance of being able to talk to C++ code. COM objects provide a partial solution to this, but require a lot of plumbing to implement correctly. For widely used API’s, it is often simpler to restrict your interface to C code.

So the code we need to interface with is actually C, not C++. Our own code is going to be a limited subset of C++. If you intend to write actual applications in C++, you really owe it to yourself to learn the language properly, but for our purposes, sticking with a smaller subset is simpler.

So what does it mean in practice that the API is written in C? Primarily two things:

• No exceptions — errors have to be reported through error codes.
• No classes — C allows structs, containing data, but no member functions, and no access specifiers. All members are public.

Now, on to how we’re going to tackle our task:

The first three installments in this series of posts will deal exclusively with native code. This first one will demonstrate a simple Hello world program, and discuss some fundamentals of organizing and compiling C++ code. This isn’t exactly exciting stuff, but it is useful to understand, as it commonly trips up beginners (and even some reasonably experienced programmers).

The second part will teach all the missing piece of C++ (the ones that we’re going to need, anyway), so that you’re comfortable with reading and writing simple C++ programs.

In the third part we’ll get into the Win32 API, calling a few functions (of varying complexity) and not least, learning to read the arcane specification on MSDN.

Hello World

Load up Visual Studio, and create a new project. The project type should be Win32 Console Application. This brings you to the C++ Project Wizard. If it looks like something that belonged in Windows 95, that’s because that is when it was last updated. It is written in Javascript and HTML, of all things.

This wizard gives you access to a couple of application settings. For now, set Application Type to Console Application, and select Empty Project under Additional Options. In particular, we do not want a precompiled header. It is a hack that can speed up compilation time in large C++ projects, but it is nothing more than a source for confusion in simple, small projects. Neither ATL or MFC headers should be added under Add common header files for.

Click finish, and we’re given an empty project, just like we asked for. It contains three “folders”, named Header Files, Resource Files and Source Files. I put “folders” in quotes because they aren’t. Visual Studio calls them filters, and they basically just group files by file type, rather than actually enforcing any particular location on the file system. They’re also not particular important to us so you can delete them if you like. If you add a .cpp file to the project, it is automatically listed under the Source Files filter, while .h files get listed under Header Files.

Now, let’s see some actual code. To begin with, let’s try a Hello World:

Create a new .cpp file in the project.

Now type the following into it: (We’ll get into what it means in a moment)

#include <iostream>

int main() {
   std::cout << "Hello world" << std::endl;
}

Now compile and run it. No big surprises here, it does exactly what we’d expect a “hello world” program to do. As for what the code means, let’s start with the main function itself. It’s not a member of any class — in C++, nonmember functions are allowed (and commonly used), and main in particular must be a nonmember function. The observant reader may have noticed another curious thing about it: we declare int as its return type, but don’t actually have a return statement. This is allowed as a special case for main. Other functions still have to return normally, but if control reaches the end of the main function, it implicitly returns 0².

Inside the main function, you might wonder about the <<‘s. The operators exist in C# as well, and their built-in meaning is the same. Formally, they are used for bit-shifting in both languages, but C++ allows them to be overloaded, and in particular, streams define overloaded versions.

So the << operator “streams” data into std::cout. std::endl is a stream manipulator which, when it is fed into a stream, produces a line break, and flushes the stream. In this example, we could just have written std::cout << "hello world\n" to get the newline without flushing the stream, and in some ways, that would actually have been preferable. But I wanted to introduce endl.

A final note is the std:: prefix. Where C# uses a simple dot for all scope resolution operators, C++ defines a few different ones:

• For specifying members of a namespace, or specifying static members of a class, :: is used.
• For nonstatic class members, . is used. Given an object o, we can access a member m with the syntax o.m, exactly like in C#.
• For nonstatic class members accessed through a pointer to the class, -> is used. If we have a pointer p to an object, accessing its member m looks like this instead: p->m.

So in our Hello World program, we reference the object cout in the std namespace. We could simply add a using namespace std; at the top of the program, much like we would in C#, but in C++, it is not customary to do so. You’ll note that the namespace actually has a very short name, unlike .NET’s long names and nested namespace. Rather than System.Collections.Generic.List, for example, C++ defines std::vector. Almost the entire C++ standard library exists in the std namespace. One of the main reasons for this structure is to make it easy and convenient to access namespace members without having to do using namespace X.

cout stands for character output, and is the stream used for standard output, much like the output-related members of .NET’s Console class. There is also a cin stream object responsible for input.

cout and cin are actually nothing more than global variables of the type std::ostream and std::istream respectively. Another output mechanism you’re likely to see is the C function printf, which is syntactically closer to what you’re used to from .NET.

Given an integer i we want to print out along with a message, cout and printf would be used like this:

std::cout << "You have " << i << pancakes\n";
printf("You have %d pancakes.\n", i); 

Each of these have their advantages and disadvantages as you can probably see. The nice thing about cout is that it is type-safe, and allows us to compose our output string without having to worry about the type of i or the number of parameters. We just stream whatever we like into cout one parameter at a time, and it all just works. It also works with user-defined types. They just have to define an appropriate operator <<.

The nice thing about printf on the other hand, is that the actual format of the string is much more readable, and parameters are specified separately at the end. As you know from .NET’s string.Format function, it is very convenient to be able to write the entire format string in one go, and only specify parameters afterwards. It is a bit awkward that cout requires you to break up the string with <<‘s all over the place. But there are some serious limitations to printf as well:

• It can not be extended. It works for the basic built-in types, and nothing else.
• It requires the programmer to specify the type of the parameter as part of the format string. (%d specifies that the paramater at this partition is expected to be an integer (I assume the d stands for decimal). But there is no type-checking to verify that this is actually the case. I can pass a float to printf, and print it out with %d, and I get garbage.)
• The number of parameters to the function are unknown to the compiler. C (and C++) only have very rudimentary support for functions with variable arguments. Once you make use of this feature, you lose all type information and information about the number of parameters passed to the function.

I tend to prefer cout for these reasons; it is safer, and it can be extended. But you’re likely to encounter printf in code samples and should at the very least be familiar with it.

Finally, let’s deal with the very first line. There are four things to note about it. In order of appearance, they are:

• The # at the very start of the line indicates that this is a preprocessor directive. In other words, this is evaluated in a separate pass before the compiler starts working. Modern compilers don’t maintain a strict separation between preprocessing and compilation, but as the language is specified, the preprocessor basically runs over the source code performing a number of simple modifications before the compiler is invoked.
• include is the actual preprocessor directive. It specifies that we would like to include a file.
• The file name is surrounded by angle brackets (<>). When these are used, the preprocessor searches for the file to include in system directories. If we had used double quotes (""), the preprocessor would have searched for the file locally first. So slightly simplified, use ´<>to include system headers, and””‘ to include files from the same project or solution.
• Finally, inside the angle brackets, we have the name of the header file we’d like to include. In general, your own files should use a .h or .hpp suffix. Headers belonging to the C standard library also use .h, but C++ standard library headers have no extension. (So you have iostream instead of iostream.h).

Finally, what does it mean for a file to be #include’d? It’s not quite the same thing as the using statements you put at the top of a file in C#. Those using statements are functionally similar to the using namespace statement mentioned earlier — they allow us to reference types defined in other namespaces as if they were members of the current namespace. If we do not have the using statement, we have to specify the full namespace prefix when using the type (System.Collections.Generic.List<T> instead of simply List<T>), but the types are still available. I can reference System.Collections.Generic.List<T> in C# without any using statements. Likewise, I can reference std::cout as I did in the previous example without having a using namespace std.

But without the #include, the compiler would not have been aware of cout at all.

An #include is in a sense very simple. All that actually happens is a copy/paste operation. The preprocessor locates the file iostream, and copies its contents into our file at the location of the #include. The effect of this is to give us access to anything defined in the file. In .NET this is all taken care of by magic. Anything in the current assembly is automatically visible, and anything that isn’t declared internal in other assemblies is visible as soon as we add a reference to it.

In C++, no such mechanism exists. What the compiler sees is just the current file. Other files, even in the same project, are not visible when the current file is being compiled. The compilation model is notoriously quirky, and probably deserves some explanation.

The preprocessor and the C/C++ compilation model

C++ code is compiled in a couple of stages. I already mentioned the preprocessor. In the old days, this was a separate program, which was run on the source code first, perfoming simple text manipulation (search/replace, and conditionally removing chunks of code). The output of this was then fed to the compiler. Finally, the output of the compiler is fed to a linker, which we’ll get to later. Today, the preprocessor is built into the compiler, but it is still a separate pass made over the code before the actual compilation begins.

Let’s wrap up the preprocessor quickly though. It can do a few other things that we’ll probably run into soon enough. In particular, #define has a few uses. It creates a macro — whenever the name of this macro is encountered, it is replaced with the macro definition.

So in the following:

#define waffles pancakes
std::cout << "I like " << waffles();

we create a macro named waffles, and from that point onwards, any occurence of waffles is swapped for pancakes. Which means that the function that actually gets called in line two is pancakes(), rather than waffles() — highlighting another important aspect of the preprocessor. Because it is run before compilation, it has no notion of actual language syntax. It doesn’t care about the context of the text it is replacing. It doesn’t care that this is a function call, just like it wouldn’t care if the named had been found in a different namespace than the one the macro was defined in. It doesn’t respect scoping rules or anything else. It won’t swap out the middle of words, or the contents of string literals (so ilikewaffles() would go untouched, as would "waffles", but that’s about it. Anything else gets brutally replaced by the preprocessor.

Another common example of its simplicity is the following:

#define four 2+2
int i = four * four;

The result of this? It is 8. The preprocessor just performs simple text substitution, resulting in this code: int i = 2+2 * 2+2, which of course gets evaluated as int i = 2 + (2*2) + 2.

We can also use the preprocessor to perform conditional compilation removing sections of code at compile-time:

#define waffles
#ifdef waffles // #if defined(waffles) would also have been legal
// this will get compiled
#else
// this will get removed by the preprocessor
#endif

A variation on this is used in almost every header file, but we’ll get to that soon enough.

The compiler processes what is technically known as translation units. A translation unit is a single source file (typically .cpp or .cc for C++, or .c for C code), after preprocessing. So in our Hello World program, we have one translation unit, consisting of the contents of the header file iostream, followed by our main function. The result of compilation is not a program, but rather an object file (Visual Studio uses the extension .obj for these — GCC uses .o). An object file contains all the compiled code for this file, but with certain placeholder “gaps”. This is necessary as code files will typically depend on functions or variables defined in other translation units. We are able to tell the compiler that a function defined in another translation unit exists, but it won’t be able to see the actual defintion of the function, so it has to generate a kind of placeholder, saying “call the function with this name, as soon as we find out where that function is”. That is essentially the role of object files. Store the compiled code, along with the necessary information about which symbols this file defines, and which symbols it depends upon, and which must be found in other files for the program to be complete.

When all the object files are created, they are passed to the linker, which performs the final steps — reading all the object files, locating all these placeholders, and filling them in. If some code in object file A calls a function f defined in another file B, the linker must read both files A and B, determine the address of the function f, and insert it into the function call inside A.

If the linker finds multiple conflicting definitions of f (perhaps object file C also defined a function with the same signature), it is of course an error. Likewise, if it is unable to locate the full definition of a symbol referenced from a file, we get an error. Because the linker does not have access to the actual source code, but only the object files, linker errors are notoriously hard to understand, but it can be done. The following simple code causes a linker error: (we’re going to run with this example for a while, so feel free to add it to a new project, or overwrite the previous file. This code should be the only contents of the project)

class myclass {
public:
    int f(float fl);
};

int main(){
    myclass c;
    c.f(1.0f);
}

The code should be straightforward enough. We declare a class with a member function f. In the main function we create an instance of our class, and call the f function. There is just one problem: the function is declared, but it has not been defined. In other words, the compiler knows it exists (so we don’t get a compiler errror when we try to call it, as we would if we called a completely unknown function), but because it does not have the function body, it has to assume that the full definition is… elsewhere. So the compiler lets this pass, hoping that the linker can sort things out.

But the the linker is given only this one translation unit. So it is unable to find a definition for the function f, so it spits the following error at us:

error LNK2019: unresolved external symbol "public: int __thiscall myclass::f(float)" (?f@myclass@@QAEHM@Z) referenced in function _main

Ouch. Again, the linker doesn’t have access to the source code, so this is about the best it can do. It tells us that the problem is an “unresolved external symbol”, or in other words, it was unable to resolve a symbol that one of our translation units expected to be “external” (defined in another translation unit). As for the symbol itself? All it actually sees is the mangled string near the end: ?f@myclass@@QAEHM@Z. This is the name for the function generated by the compiler and stored in the object file, and I have no clue what the @‘s or the letters following it mean. They somehow encode information about parameters and return type, but that’s about all I can say. Luckily, the linker is able to decode this name, which it also does for us. It tells us that the function has public visiblity, and its return type is int. __thiscall is the calling convention used for member methods. (It is essentially a calling convention that allows for a this parameter, hence the name). The calling convention isn’t usually important here though. Next, we can see that the unresolved symbol is a member of the class myclass, the function is named f, and it takes a float as its parameter. Finally, it tells us that the symbol was referenced from the _main function (again, we can’t always trust the compiler to preserve the precise names, but it’s probably a safe bet to assume that when it says _main, it means main.

So the error is actually pretty straightforward once you filter out the noise. A lot of C++ programmers don’t realize this, and go into a panic whenever they encounter a linker error, which is why I wanted to demonstrate this one. They typically contain a lot of noise (especially in more complicated cases), but they can be deciphered if you eliminate all the @@ nonsense and read the remaining text slowly and carefully.

The other reason why I wanted to demonstrate this is that it is key to why header files are used. Based on the above example, we now know that the compiler can be tricked into accepting a call to a function it has no knowledge of, as long as it can see a valid declaration. (a function declaration is essentially just the signature (including return type), followed by a semicolon, much like an interface method in C#.

So perhaps we should get creative and see if we can make the linker happy too. First, we create second .cpp file with the following contents:

class myclass {
public:
    int f(float fl);
};

There’s still no definitions of f, but we’re taking it a step at a time. Now, though, we have two files containing the same definition of myclass. Of course, the compiler only sees one file at a time, so it won’t notice this, but what will the linker say? Won’t it complain about multiple definitions of the same symbol? Try compiling the project and find out.

As it turns out, we get exactly the same error as before. But we don’t get any complaints about the multiple definitions of the same class. This is actually allowed. We are allowed to create as many definitions of the same symbol as we like, as long as there is only one in each translation unit (the compiler will choke on it if you try to define a class you’ve already defined), and all the definitions are exactly identical. (The linker will typically not enforce the last requirement though. If the definitions are not identical, it typically manifests as weird crashes at runtime)

This is called the One Definition Rule (ODR). Only one definition may exist. That definition may occur in multiple places, but it must be identical, it must be the same definition, every time it is encountered.

So it seems like we have a problem, doesn’t it? We’re allowed to duplicate the class definition, but we’re not allowed to modify it! So how are we supposed to add the definition of f?

Try changing your second file (the one without the main function) to the following:

class myclass {
public:
    int f(float fl);
};

int myclass::f(float fl){
    return 42;
}

and compile it. Voila! It works. We didn’t modify the actual class definition, so we obeyed the ODR rule. Instead, we added the function definition afterwards, outside the actual class definition. And both the compiler and linker are happy. The linker now sees two identical definitions of the class myclass, but that’s allowed under the ODR rule. It also sees a call to the function myclass::f, and a single definition of the same function, so it is able to glue everything together into one single program.

Of course, having to copy/paste, and maintain duplicate code in every .cpp file is hardly ideal. Sooner or later, we’re going to modify myclass in one file, and forget to do the same modifications in all the other files. That will break the ODR rule, and everything will crash horribly.

That is where header files come in. We could put the shared code in a separate file, and use the #include directive mentioned earlier to automatically copy/paste the contents in! Let’s try that now. Create a new file (with the .h or .hpp extension), and place the class definition in that. Now remove the class definition from the two .cpp files we already had, and replace it with a #include referencing the header.

That is, your projcet should contain the following three files: (I’m going to name the .cpp files main.cpp and myclass.cpp for convenience:

// myclass.h
class myclass {
public:
  int f(float fl);
};

// myclass.cpp 
#include "myclass.h" // note we use quotes, not angle brackets here
int myclass::f(float fl){
  return 42;
}

// main.cpp
#include "myclass.h"
int main(){
  myclass c;
  c.f(1.0f);
}

And it seems to work. Clever. There is one little problem though. What happens if we include our header multiple times? We probably won’t intentionally do this, but perhaps we’re going to include it, and then include another header, which also includes it. We can easily get out into a situation where some headers get included many times. Think of standard headers like iostream. We’re going to end up including it fairly often. Sooner or later, we’ll end up including some of our headers twice, which breaks the ODR rule! We’re not allowed to have multiple definitions in the same translation unit. To test the problem, feel free to duplicate the #include statement and verify that the compiler chokes on it.

So to solve this problem include guards are used. Modify your header as follows:

#ifndef MYCLASS_H
#define MYCLASS_H

class myclass {
public:
  int f(float fl);
};

#endif

There should be nothing new in this, but the consequence might be surprising. First, we ask the preprocessor to check if the macro MYCLASS_H is defined, and only evaluate the following if it is not defined (the directive is named ifndef, or if not defined).

If we enter the if statement, the first thing we do is define the symbol MYCLASS_H, and then we evaluate the original contents of the header. Finally, we end the if-statement with an #endif. So what happens if the file gets included twice now?

For simplicity, assume the following .cpp file, containing nothing except two includes:

#include "myclass.h"
#include "myclass.h"

As the preprocessor parses this, it’ll expand both #include’s, resulting in this:

#ifndef MYCLASS_H // At this point, the macro MYCLASS_H is not defined, so we enter the following block:
#define MYCLASS_H // define the macro MYCLASS_H

class myclass { // allow this code to stay in the translation unit
public:
  int f(float fl);
};

#endif // end the if statement
#ifndef MYCLASS_H // now MYCLASS_H *is* defined, the condition is not true, and so we *skip* the if statement.
//#define MYCLASS_H // of course the preprocessor doesn't actually comment out the code, it simply removes it from the translation unit. I'm commenting it to illustrate what happens
//
//class myclass { // this time, the preprocessor *removes* all this code, because it is inside a #if statement we're skipping
//public:
//  int f(float fl);
//};
//
#endif

so after the preprocessor has run, only this code actually gets inserted in our translation unit:

class myclass {
public:
  int f(float fl);
};

So it seems we’re able to handle multiple inclusions of the same header now.

So to review, we’re now able to split our code across multiple source files, and do it correctly. We don’t need to duplicate any code — all the shared code can be placed in header files, and include guards protect against accidentally including the same file twice in the same compilation unit.

And now you should finally understand what it meant when we included iostream in the original Hello World example. We’re simply pasting in a lot of system code, containing declarations that get linked together with the standard library containing the full definitions.

This turned out a lot longer than I’d originally intended (I had originally, and naïvely, planned to write the entire series in one post), so let’s call it a day here. Part two will be posted very soon, and cover some actual C++, now that we’ve got the fundamentals out of the way. You needed to understand how C++ code is compiled before you’re able to write anything useful in the language.

Everyone who learns C++ fears pointers. Everyone who is new to the language, or who has merely heard of the language consider pointers to be some kind of magic — arcane constructs that give the programmer access to Real Ultimate Power — a feature that both mark C/C++ as superior and more powerful than other languages, but is also feared as dangerous or unsafe*.

None of this is true.

Pointers are simple.

Pointers are not magical.

Pointers are safe (as long as you use them only as allowed by the language)

It is very well-defined what you may, and may not, do with a pointer. The only problem is that the compiler is unable to enforce most of this, so it relies on your own discipline, and knowledge of the rules. But the rules exist. And if you stay within the rules, if your C++ program is legal, then pointers are perfectly safe.

This post is my little attempt to debunk The Great Pointer Conspiracy. It seems there is some hidden rule that whenever we teach others C or C++, we must describe pointers

• as more complicated than they are, and,
• as something they are not. It sometimes makes sense to lie to your pupil in order to teach them the truth a bit at a time (similar to how most of what you learned in elementary school turns out to be wrong when you get to university. They didn’t mislead you, they just taught you simplified versions of the truth to get you on the right track). But in the case of pointers, the model taught is not merely wrong, it is also more complex and harder to understand!

So what is a pointer then?

Let’s start with a crash course in syntax, just to get that out of the way.

• A pointer to type T is denoted T* (pronounced pointer to T)
• A pointer is created with the & operator. Assuming an int i, we can create a pointer to it: int* p = &i; (&i is typically pronounced as take the address of i)
• A pointer can be dereferenced with the * operator, yielding the value it points to: int j = *p;

That’s easy, right? The only point of confusion is the dual role of *, as both part of the type, and as the dereferencing operator. There’s a bit of symmetry here, because & can be used in both places as well. As above, it can be used to take the address of an object, but it can also be used as part of the type, to create a reference: int& k = i creates a reference to the previously defined integer i. But references aren’t the subject of this post. I only mention it because of the related syntax.

So, on to what pointers are, and what they can do:

Pointers are references

A pointer is little more than a reference (in the conceptual sense — not the specific C++ references mentioned in the previous section) to a variable. If we have multiple references to the same variable, they will all see changes made by each others. Here’s an example:

void Foo(int* ptr){ // Because we're passed a pointer, we have a reference to the original variable, and can modify it so the changes are visible outside the function
  *ptr = 2; // set whatever ptr points to, to 2
}

int main(){
  // create a local variable i. This isn't a pointer, but it can be referenced by one.
  int i;
  int* p = &i; // create a pointer to i by taking the address (see below) of i, and store that as a pointer p
  i = 1;
  assert(*p == 1); // the value referenced by p is now equal to 1
  Foo(p);
  assert(i == 2 && *p == 2);
}

important note: Yes, I used the word “address” in the comment above. It is important to realize what I mean by this. I do not mean “the memory address at which the data is physically stored”, but simply an abstract “whatever we need in order to locate the value. The address of i might be anything, but once we have it, we can always find and modify i. If you want a real-world analogy, what is an address in the real world? My email-address has nothing to do with my house address. My phone number could be considered a third address. Even my social security number, or my full name could be considered addresses in this sense. All of these allow you to locate or contact me, which is all we require.

So far, so good. Pointers are simply references to other variables, with slightly quirky syntax in that we have to use *p to get the value that the pointer p points to, and we have to use &i to create a pointer to i.

Of course pointers can do a bit more than this though. They’re not as complex as people often try to convince beginners, but they’re not that simple either.

Pointers can be reseated

Once a pointer exists, we can change what it points to. For example:

int main() {
  int i = 1;
  int j = 2;
  int* p = &i; // make the pointer p point to i
  assert(*p == 1);
  p = &j; // and now make it point to j
  assert(*p == 2);
  *p = 3; // modify the variable p points to
  assert(j == 3);  // j is now 3
  assert(i == 1);  // but i is untouched, because p no longer points to it.
}

See, that’s not rocket science either, is it? Whatever the pointer points to, we can look at and modify. And when it no longer points to that, they have no connection any more.

Pointers can be null

Next up, pointers don’t have to point to something. They can be null pointers. And just like with addresses in the previous example, it is important to be clear on what we mean by this. A null pointer is exactly what I said: a pointer which does not point to any object.

In particular, it is not a pointer to the address zero. Of course, here is where it becomes tricky, because the following does create a null pointer:

int* ptr = 0;

The trick here is that the C++ language standard makes a special rule for this case. Assigning the constant zero to a pointer creates a null pointer, and not a pointer to address zero. The “constant” part is important too. Here is the precise wording in the standard (Section 4.10 [conv.ptr], paragraph 1:

A null pointer constant is an integral constant expression (5.19) rvalue of integer type that evaluates to zero. A null pointer constant can be converted to a pointer type; the result is the null pointer value of that type…

A “constant expression” is essentially an integral value which can be evaluated at compile-time. So 42, 2+2 or const int i = 99 are constant expressions.

int* p0 = 0; // null pointer
const int zero1 = 0; // constant expression
int* p1 = zero1; // null pointer
const int zero2 = 2 - 2; // constant expression
int* p2 = zero2; // null pointer
int zero3 = 0; // not a constant expression
int* p3 = zero3; // not a null pointer
int a = 2;
int b = 2;
int zero4 = a - b; // not a constant expression
int* p4 = zero4; // not a null pointer
const int c = 2;
const int d = 2;
int zero4 = c -d; // constant expression
int* p4 = zero4; // null pointer

Obviously, the compiler is unable to enforce all of this, but that doesn’t make it less true. According to “the rules”, a null pointer is neither a pointer pointing to address zero, or a pointer to which the value zero has been assigned. It is a pointer to which the constant expression zero has been assigned.

As for what you’re allowed to do with a null pointer? Basically nothing. You may compare it to other pointers, and… that’s basically it.

With me so far? You might have noticed that what I have described so far is almost exactly what references in C# or Java (or many other languages) are. A variable of a reference type behaves pretty much exactly like this. We can set it to point to another valid object (but we are not allowed to ever set it to an invalid object), or we can set it to null.

Pointers are much like reference types in most other languages. This is an important point. Like I said to begin with, pointers are not difficult. They are a very simple concept, as the above shows. Where the confusion arises is in the one extra thing they can do, which I will describe next. Note that while this does make them somewhat more flexible than C# references, it is still a far cry from the “raw memory address” concept that people often think pointers are.

Pointers can traverse arrays

Now comes the (slightly) tricky part — the one that usually gets people confused, or gives them the wrong idea. If we have a pointer to an element within an array, we are allowed to move the pointer around within the array

char arr[] = {'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j' };

char* ptr = arr; // arrays are not pointers, but can *decay* into a pointer to the first element. So now we have a pointer to arr[0]
assert(*ptr == 'a');
++ptr; // move ptr to the next element
assert(*ptr == 'b');
ptr += 5;
assert(*ptr == g);
assert(*(ptr + 2) == 'i');
assert(*(--ptr) == 'f');
ptr -= 3;
assert(*ptr == 'c')

So far, so good. At this point it is probably a good idea to mention that when you increment a pointer, it always moves to the next element, and not to the next byte. Once again, being careful with the idea of “addresses” pays off. The pointer stores the address of an object. By adding one to that address, we get the address of the next object, no matter how big the object is. Think of your house address. It doesn’t matter how big your house is, the next address is always the neighboring house. It is not your garage door or your kitchen window.

If, for the sake of argument, pointers had merely been memory addresses, then adding one to a pointer would have produced an address that was one byte higher, which means the pointer would no longer have pointed to a valid object. Good thing we don’t live in that messy kind of world, eh? In C++ land, a pointer points to an object, and incrementing it gives us a pointer to the next object.

Now comes the next little surprise: You are allowed to move the pointer one step past the end of the array. Assuming the same array as above:

char* p = arr + 9; 
assert(*p == 'j'); // no surprises here, just verifying that we're at the end of the array.
char* q = arr + 10; // this is legal
++p; // so is this

But once again, we have to be careful. The language has only given us permission to go one step past the end. A pointer to arr + 11 is downright illegal, even if we don’t dereference it. The mere existence of the pointer is illegal. The compiler probably won’t complain, and your code may even appear to work, but it is no longer a legal C++ program.

We have also not been given permission to dereference the one-past-the-end-pointer. *(arr + 10) is not legal. Again, it may seem to work, on your computer, with your compiler, on this particular day. But it may not work tomorrow. Or on my compiler. Or when I run your program.

So the language allows us to create, and move pointers around freely, from the start of the array, and up to one past the end of the array. And it allows us to dereference pointers that point to any element in the array, but not one past the end.

And that’s basically it. This is the dreaded pointer arithmetic that usually have beginners running scared. Not all that scary, is it?

Of course, For the sake of completeness, there is one other arithmetic operation that is legal under much the same circumstances:

Two pointers pointing to the same array may be subtracted, yielding the distance between them, expressed as a number of elements. And for the purposes of pointer arithmetics, single elements are considered arrays of size one, meaning that all the above is true for single variables too — they’re just treated as arrays with only a single element.

And one final detail

Now let’s get self-referential. There is nothing new in this — it follows as a logical conclusion of the above, but it often comes as a surprise, so let’s mention it:

Pointers may point to pointers. Again, there is no magic, no special cases. A pointer is simply a reference to an object, remember? And a pointer is an object too, so obviously we can point to that as well!

We don’t often need to do that, but there is one case where it is used. Typically when you call a library function, and want it to give you a pointer to some resource it has created, you do this:

Resource* ptr = 0; // this is going to be our pointer to the resource. For now, make it a null pointer to avoid confusion
bool success = CreateResource(&ptr); // pass the address of our pointer to the function

Note that the function wishes to return a status code to let us know if the operation succeeded, so it can’t simply return the pointer we want. So it has to resort to pointer-pointer trickery instead.

The insides of CreateResource might look something like this:

bool CreateResource(Resource** res){
  Resource* actualResource = new Resource(); // create the resource, and temporarily store a pointer to it
  // now we need to pass this pointer to the caller. If res had been a regular "single" pointer, it would simply have been a null pointer. 
  // And sure, we could have made it point to our resource instead, but the caller wouldn't know, because we only received a *copy* of the original null pointer. So even if we change what it points to, we can't change what the *original* points to.
  // Instead, we use a pointer to a pointer. We know that 'res' now points to the caller's Resource pointer. So if we manipulate the value pointed to by 'res', we're actually manipulating the caller's pointer.
  *res = actualResource; // so take our newly allocated resource pointer, and store that into the caller's pointer, which we get by dereferencing res.
}

It may help to remember that function arguments in C++ are always copied. If you pass an int to a function, it receives a copy of that int. And if you pass a pointer, then the function receives a copy of that pointer. A copy which points to the same address, so anything we do to the pointed-at address will be visible outside the function as well. But if we change the pointer itself, no one else will see it, because the function has been given its own copy.

So if we pass a pointer p0 to a pointer p1, then this is again copied. The function receives a copy of p0, let’s call it p2 which points to p1. So if we change what p2 points to, the calling function won’t see it, but if we change what p1 points to, it will be visible to the caller, because p0 still points to p1.

Yes, this added level of indirection may take some getting used to, but the important part is that there’s nothing fundamentally special. It is simply the logical conclusions of the rules I described previously, so even if you don’t get it now, you will when you’ve got a bit more experience with pointers. It’s similar to how, when you first learned to read “See Spot Run”, you had all the rules necessary to read longer words, like “stewardesses” or “programmatically”. After that, you pretty much just needed practice.

So that’s it. That’s all pointers are. If you hadn’t previously encountered pointers, you can stop reading here. But if you were already taught about pointers, we probably have to undo some of the damage.

So the following will discuss what pointers are not — that is, the misconceptions that typically exist about pointers, and which beginners are almost invariably taught. I’ll try to explain why these limitations exist as well, partly so you can take the rule seriously as “something with real-world relevance”.

The Pointer Abuse Rehab and Correction Center

In the following, assume that i, j are integer variables (int), and p, q are pointers to integers (int*) and n is a null pointer:

• A pointer is not just a number. For example, i + j is legal, but p + q is not. Try it. Your compiler will give you an error. Likewise, i*j is valid, but i * p is not. Integers may be added to or subtracted from pointers, and pointers may be subtracted from pointers (as long as they both point to the same array). And on some computers, a pointer isn’t implemented as an integer either. Some machines have segmented memory space, so an address is a tuple consisting of a segment identifier plus an offset. Sure, you can combine those two in a single number, in the same way that you can combine the country code with my phone number to create a single integer. But the address is still, fundamentally, a tuple of two numbers on that machine.

• A pointer is not a memory address! I mentioned this above, but let’s say it again. Pointers are typically implemented by the compiler simply as memory addresses, yes, but they don’t have to be. A pointer may not point to just any address (and again, some computers, which have separate address and integer registers, are actually able to enforce this at runtime, generating a hardware fault if you try to create a pointer to an address that is not allocated to your process.) The same goes for moving past the end of an array. You’re allowed to go one element past, but pointing two past the end is not allowed, and again, some computers are able to enforce this, at least in some cases. (imagine that the array is located at the very top of the address space, so moving two elements past the end produces an overflow. On a CPU with dedicated address registers, overflows probably won’t be allowed. They’ll be caught and they’ll generate an exception).

• All pointers are not born equal. A pointer to T may not be convertible to a valid pointer to U. Some machines require datatypes to be aligned. Typically, a 4-byte integer will have to be aligned so it starts on an address that is divisible by 4. But a single byte datatype such as a char can be placed anywhere. So that means three out of four char pointers will not be valid integer pointers! We also can’t rely on casting as much as we’d typically expect. reinterpret_cast in particular often trips people up. (For non-C++ programmers, you can assume that we had used the “traditional” casting syntax, as in (float*)i. The difference is not important.)

int* i; // assume we have a pointer i and that it points to a valid integer
float* f = reinterpret_cast<float*>(i); // #1
int* j = reinterpret_cast<int*>(f); // #2
assert(i == j);

In the above, we know nothing about the value of f after the cast on line #1. We know that it contains an “implementation-defined mapping” of the original i. But we are not guaranteed that it points to the same address, or even that it contains the same bit pattern!

True, the standard says that the mapping is “intended to be unsurprising to those who know the addressing structure of the underlying machine”, but in general, we can’t rely on that. All we are guaranteed is that once we cast back to the original type, we’re given the original value. So the standard guarantees that i and j in the above will point to the same address. But we know nothing about f, other than that the compiler is able to convert the value stored in it back to the original pointer i.

Conclusion

By now, I hope it’s clear that pointers actually become a lot simpler when we treat them as what they are, reseatable references to objects. If we start pretending that they are memory addresses, we get a whole host of complications: we start thinking that they should be allowed to point to any memory address, or even worse, that they are just numbers, and that all the usual arithmetics work on them. (Remember, adding or subtracting integers is legal, but it adjusts the pointer by that number of objects, not bytes, as we would have expected if pointers were just memory addresses. And pointer + pointer, pointer * pointer or pointer / pointer are simply not defined at all.)

As if that wasn’t bad enough, we also require the student to understand the underlying hardware, in particular the concept of a memory space, and of physical (or virtual) hardware addresses.

But if we treat pointers as what they are, that is no longer necessary. A pointer points to a C++ object, not a memory address, so to understand pointers you merely have to understand C++ objects, not memory addresses.