Class invariants

The primary motivation for defining a class in C++ is to reflect and maintain a class invariant. In this post we will see what class invariants are and how you deal with them. Class invariants are important part of C++, even though there is no “invariant” keyword in C++.

Contrast the following two class definitions:

struct Point
{
  int x;
  int y;
};

class Range
{
  int _min;
  int _max;

public:
  // ...
};

In C++ a struct is practically a class but with a different default member access. The first is an aggregate: it only allows two pieces of data to travel together. If it was not for the nice member names, we might have as well used std::pair<int, int> instead. The second is a bit more. Its members are not just two pieces of data. Here we need to pay more attention to the situation where _min is greater than _max. We will probably have one of these:

Range::Range(int mn, int mx) 
  : _min(mn), _max(mx)
{
  if (_min > _max)
    throw some_exception();
}

Range::Range(int mn, int mx) 
  // precondition: mn <= mx
  : _min(mn), _max(mx)
{
  assert (_min <= _max);
}

void Range::set(int mn, int mx) 
{
  if (mn > mx)
    throw some_exception();

  _min = mn;
  _max = mx;
}

void Range::set(int mn, int mx) 
  // precondition: mn <= mx
{
  assert (mn <= mx);
  _min = mn;
  _max = mx;
}

What these functions are doing is maintaining the class invariant. It can be even expressed with a C++ expression:

_min <= _max

Many developers design invariant-maintaining classes without ever needing to give a name to this activity. But when we give it a name, we can see more. For instance, we can form a criterion for when we need to define our own class.

We only define a new class proper when we need an invariant to maintain.

If we don’t need an invariant, a simple aggregate or a tuple will do. Of course, in C++ we like doing clever things, so you will surely find exceptions to this criterion. But I think it is a good starting point. Sometimes an invariant is difficult to spot, though. Sometimes it cannot be expressed with a C++ expression. For instance, for a class representing a session with a resource, such as access to a file, the class invariant may be that for as long as the object is alive — its initialization has finished but its destruction hasn’t started — it provides access to an open file.

By defining a class proper (not just an aggregate) we provide a guarantee to our users that we will maintain the invariant. Now it is our, quite difficult, job to implement this guarantee by carefully choosing the interface of our class, as well as its implementation. The tools that help us are:

• class member access (private, protected, public),
• contract-related features (preconditions, assertions),
• the exception handling mechanism.

Class invariants, more formally, specify a condition — not necessarily representable via a C++ expression — that must hold immediately after a class object is constructed, and after every function belonging to its interface has finished — normally or via exception. The class design also needs to make sure that no-one else can compromise the invariant via other means than its interface. As a consequence, we get an additional guarantee that whenever an interface function, or destructor, from the class is invoked, the invariant is also satisfied.

I use a vague term “interface”, because apart from public member functions I mean other things, like protected members, public data members and friends.

One natural thing to do when deciding to maintain the invariant is to declare the non-static data members private. Recall our example class Range. If its members _min and _max were public, anyone could easily, even inadvertently, spoil our invariant without our control. We make them private to control their modification.

A class invariant is more than a postcondition upon every member function of the class. A function postcondition is expected to be satisfied unless the function reports failure (via an exception). A class invariant is expected to hold even if a function that modified the class object reports failure. In fact, throwing an exception may be a way to make sure that the class invariant is preserved. This is what we did Range::set:

void Range::set(int mn, int mx) 
{
  if (mn > mx)
    throw some_exception();

  _min = mn;
  _max = mx;
}

Why we need class invariants

The reason we need class invariants is because they help us think about the programs in more abstract terms. It is easier to program when you deal with a Range than a pair<int, int> or even struct{int min, max;}. You may have been taught that it is classes that we use to make our code more abstract, but classes are really only means of delivering the invariant. It is all really about guaranteeing the class invariants.

If you have made an effort to guarantee your class invariant, your users no longer have to worry about it. Suppose that you only used the aggregate version of a range in your program:

struct Rng
{
  int min, max;
};

int fun(Rng rng, int val)
{
  if (is_in_range(val, rng))
    return size(rng);

  return values[rng.max - rng.min + 1];
}

At every point of your program, in every function, you would now have to consider what happens, or should happen, when rng.min > rng.max. You would have to investigate if it happens, all the time. Your attention — if you care for correctness — would be distracted with all these questions.

But all these questions disappear once you delegate the responsibility of keeping track of this condition to a class managing its invariant. From now on, you are dealing with a mathematical range rather than the relationship between two types of type int.

Strong and weak invariants

So suppose you have created a class Socket that gives you a guarantee that a living object is always representing an exclusive access to the OS-managed socket. The class acquires access to the socket in the constructor and releases the access in the destructor. Now you probably also want to make your class movable by providing a move constructor. Implementing a move constructor is quite easy. You just have to invent a special “null-state” that you will put your object in when it is being moved from. But now you have compromised your class invariant. You can no longer say “a living object is always representing an access to the socket”. Now you have to say, “a living object either represents a null-socket or an access to the socket”. Thus, whoever gets a reference to the object of type Socket will have to ask themselves a question: is this a null-socket or a proper socket? We call this effect a weakened invariant. The invariant is not as strong as it could have been. We have now “lowered” the abstraction level. We no longer think in terms of sockets, we now start thinking in terms of something that can be one of two things: a socket or a not-a-socket. We now move some responsibility of checking the correctness of the state on our users. A weak invariant is still better than no invariant. And making Socket movable may be worth it. But we do lose something.

At this point someone might think, “now that we have a null-socket state, we can add a default constructor, and we know what it will do: it will create a null-socket”. I personally find it a bad idea, as it will cause even more null-sockets to appear in our program. Sometimes, however, different frameworks force you to provide a default constructor, and you have no choice.

The choice of how strong you want your class invariant to be is much up to you. The stronger the class invariant, the less conditions your users have to pay attention to, and you leave fewer opportunities for bugs.

There may be also a practical reason for not providing a class invariant. Designing a class is in fact a difficult an error-prone task. You only do it when you know the effort will pay off: when you, or your users, will benefit from the class invariant in many places. However, if you are only going to use a new thing in one of two places, creating a class is an overkill and an unnecessary risk.

Consider algorithm minmax_element that scans through an STL-like range of elements and returns the smallest as well as the biggest element in the range. It needs to return two things, so they have to be packed together. There is an obvious relation between the two data: the first cannot be greater than the second, so specifying a class with an invariant would be an option, but we have to draw the line there. The user will surely unpack these two pieces and use them separately or with their own interface. In this case it is better to go with something simpler. And this is what STL did. The non-range version returns a std::pair, whereas the range version returns an aggregate.

And that’s it for today. I hope that this post will stir some comments or discussion. If you think that I have taken it too far or conversely, that I should have gone further, I would be interested to know about it.