concept_archetype.hpp`

Generic programming in C++ is characterized by the use of template parameters to represent abstract data types (or ``concepts''). However, the C++ language itself does not provide a mechanism for explicitly handling concepts. As a result, it can be difficult to insure that a concrete type meets the requirements of the concept it is supposed to represent. Error messages resulting from incorrect use of a concrete type can be particularly difficult to decipher. The Boost Concept Checking Library (BCCL) provides mechanisms for checking parameters in C++ template libraries. The mechanisms use standard C++ and introduce no run-time overhead. The main cost of using the mechanism is in compile-time. The documentation is organized into the following sections.

Jeremy Siek contributed this library. X managed the formal review.

Introduction

A concept is a set of requirements (valid expressions, associated types, semantic invariants, complexity guarantees, etc.) that a type must fulfill to be correctly used as arguments in a call to a generic algorithm. In C++, concepts are represented by formal template parameters to function templates (generic algorithms). However, C++ has no explicit mechanism for representing concepts --- template parameters are merely placeholders. By convention, these parameters are given names corresponding to the concept that is required, but a C++ compiler does not enforce compliance to the concept when the template parameter is bound to an actual type.

Naturally, if a generic algorithm is invoked with a type that does not fulfill at least the syntactic requirements of the concept, a compile-time error will occur. However, this error will not per se reflect the fact that the type did not meet all of the requirements of the concept. Rather, the error may occur deep inside the instantiation hierarchy at the point where an expression is not valid for the type, or where a presumed associated type is not available. The resulting error messages are largely uninformative and basically impenetrable.

What is required is a mechanism for enforcing ``concept safety'' at (or close to) the point of instantiation. The Boost Concept Checking Library uses some standard C++ constructs to enforce early concept compliance and that provides more informative error messages upon non-compliance.

Note that this technique only addresses the syntactic requirements of concepts (the valid expressions and associated types). We do not address the semantic invariants or complexity guarantees, which are also part of concept requirements..

Motivating Example

We present a simple example to illustrate incorrect usage of a template library and the resulting error messages. In the code below, the generic std::stable_sort() algorithm from the Standard Template Library (STL)[3, 4,5] is applied to a linked list.

  bad_error_eg.cpp:
   1  #include <list>
   2  #include <algorithm>
   3
   4  struct foo {
   5    bool operator<(const foo&) const { return false; }
   6  };
   7  int main(int, char*[]) {
   8    std::list<foo> v;
   9    std::stable_sort(v.begin(), v.end());
  10    return 0;
  11  }

Here, the std::stable_sort() algorithm is prototyped as follows:

  template <class RandomAccessIterator>
  void stable_sort(RandomAccessIterator first, RandomAccessIterator last);

Attempting to compile this code with Gnu C++ produces the following compiler error. The output from other compilers is listed in the Appendix.

stl_algo.h: In function `void __merge_sort_loop<_List_iterator
  <foo,foo &,foo *>, foo *, int>(_List_iterator<foo,foo &,foo *>,
  _List_iterator<foo,foo &,foo *>, foo *, int)':
stl_algo.h:1448:   instantiated from `__merge_sort_with_buffer
  <_List_iterator<foo,foo &,foo *>, foo *, int>(
   _List_iterator<foo,foo &,foo *>, _List_iterator<foo,foo &,foo *>,
   foo *, int *)'
stl_algo.h:1485:   instantiated from `__stable_sort_adaptive<
  _List_iterator<foo,foo &,foo *>, foo *, int>(_List_iterator
  <foo,foo &,foo *>, _List_iterator<foo,foo &,foo *>, foo *, int)'
stl_algo.h:1524:   instantiated from here
stl_algo.h:1377: no match for `_List_iterator<foo,foo &,foo *> & -
  _List_iterator<foo,foo &,foo *> &'

In this case, the fundamental error is that std:list::iterator does not model the concept of RandomAccessIterator. The list iterator is only bidirectional, not fully random access (as would be a vector iterator). Unfortunately, there is nothing in the error message to indicate this to the user.

To a C++ programmer having enough experience with template libraries the error may be obvious. However, for the uninitiated, there are several reasons why this message would be hard to understand.

The location of the error, line 9 of bad_error_eg.cpp is not pointed to by the error message, despite the fact that Gnu C++ prints up to 4 levels deep in the instantiation stack.
There is no textual correlation between the error message and the documented requirements for std::stable_sort() and for RandomAccessIterator.
The error message is overly long, listing functions internal to the STL that the user does not (and should not!) know or care about.
With so many internal library functions listed in the error message, the programmer could easily infer that the error is due to the library, rather than to his or her own code.

The following is an example of what we might expect from a more informative message (and is in fact what the Boost Concept Checking Library produces):

concept_check.hpp: In method `void LessThanComparable_concept
  <_List_iterator<foo,foo &,foo *> >::constraints()':
concept_check.hpp:334:   instantiated from `RandomAccessIterator_concept
  <_List_iterator<foo,foo &,foo *> >::constraints()'
bad_error_eg.cpp:9:   instantiated from `stable_sort<_List_iterator
  <foo,foo &,foo *> >(_List_iterator<foo,foo &,foo *>, 
  _List_iterator<foo,foo &,foo *>)'
concept_check.hpp:209: no match for `_List_iterator<foo,foo &,foo *> &
  < _List_iterator<foo,foo &,foo *> &'

This message rectifies several of the shortcomings of the standard error messages.

The location of the error, bad_error_eg.cpp:9 is specified in the error message.
The message refers explicitly to concepts that the user can look up in the STL documentation ( RandomAccessIterator).
The error message is now much shorter and does not reveal internal STL functions.
The presence of concept_check.hpp and constraints() in the error message alerts the user to the fact that the error lies in the user code and not in the library implementation.

jsiek@lsc.nd.edu)

header boost/concept_check.hpp and boost/concept_archetype.hpp

Introduction

Motivating Example

header `boost/concept_check.hpp` and `boost/concept_archetype.hpp`