constexpr-contracts

C++20 was looking good to have contracts until the C++ Standards Committee meeting in Cologne,
Germany of 2019. There, some strong turbulence happened, and the committee ultimately felt that
significantly more work was necessary before contracts are ready for Standard C++.

As one of the authors requesting contracts be removed from the C++20 Working Paper, I’d like to
offer a consolation library, which emulates how I’d like contracts to behave.

Prerequisites

1. CMake 3.14 or later
2. Conan 1.18 or later (if using Conan)
3. A standard library that supports std::is_constant_evaluated (e.g. libstdc++11-9 or libc++-9)

Installation

Without Conan

You can clone this repository and place the directory cjdb in your own include directory.

With Conan

1. Add https://api.bintray.com/conan/cjdb/cjdb to your list of remotes.
2. Add constexpr-contracts to your list of required packages.

Linking in CMake

To link in CMake, you’ll need to use find_package(constexpr-contracts REQUIRED) to import the library.
To link against the library, use target_link_libraries(target PRIVATE cjdb::constexpr-contracts).

Usage

This library provides three macros:

As the name of this library implies, you can use all of these macros in constant expressions. Your
contracts are always checked at compile-time. If the contract’s predicate isn’t satisfied, then the
program won’t compile. This is a huge advantage over using <cassert> or the GSL’s Expects and
Ensures macros.

When optimisations are diabled and NDEBUG is not defined as a macro, the contract will check your
predicate at run-time. If the predicate fails, then a diagnostic will be emit, and the program will
crash.

When optimisations are enabled, and NDEBUG remains undefined, the program will emit a diagnostic
for failed predicates, but the program continues to run, under the assumption that the
predicate was actually true. Your program will be slightly larger than if you hadn’t used the
contract, but this might be useful for identifiying cases where users report bugs (in a release
build) that aren’t being caught by your assertions.

When optimisations are disabled, but NDEBUG is defined as a macro, the program will crash when
the predicate fails, but no diagnostic is emitted. Code generation also appears to be significantly
worse.

When both optimisations and NDEBUG are enabled, the optimiser is allowed to make assumptions that
could improve code generation and no diagnostics are emitted. Toy examples demonstrate better code
generation than when the contract isn’t used. See for yourself.

*Rudimentary testing has identified that neither GCC nor Clang perform optimisations before
the contract.

Assertions

You should use assertions to indicate when a programming error has occurred in the middle of your
code. For example, the following program performs division operation, and checks that f never
returns 0. If f returns zero, then the programmer has communicated that there’s a logic error
somewhere.

// file: example1.cpp
#include <cjdb/contracts.hpp>
#include <concepts>
int main()
{
    std::integral auto x = f();
    CJDB_ASSERT(x != 0);
    std::cout << (5 / x) << '\n';
}

The above program will behave as if the assertion is not present in the event x != 0. If, however,
x == 0, the program will print the following message in debug-mode and then crash.

./example.cpp:8: assertion `x != 0` failed in `int main()`

In this case, nothing is different with -O3 -DNDEBUG, but take a look at what
happens when the compiler can see what we’re expecting.

Pre-conditions

You should use a pre-condition to indicate that the expected input for a function is not met.
Although it can’t be compiler-enforced, you should only use a pre-condition to check that a
parameter doesn’t meet its expected input values; everything else should be checked using an
assertion. This will help your users determine when they have provided bad parameters, and when
their state is the cause of a logic error.

// example2.cpp
#include <cjdb/contracts.hpp>
#include <string_view>
class person {
public:
    constexpr explicit person(std::string_view first_name, std::string_view surname, int age)
    : first_name_{first_name}
    , surname_{surname}
    , age_{(CJDB_EXPECTS(age >= 0), age)} // parens are necessary!
    {}
private:
    std::string first_name_;
    std::string surname_;
    int age_;
};
auto const ada_lovelace = person{
    "Ada",
    "Lovelace",
    -1
};

In our second example, we’re establishing that a person’s age must be 0 or greater. We do this
before we initialise age_, so that we know that the expectation is met before we ever get a chance
to use it. The run-time diagnostic we get is:

./example2.cpp:10: pre-condition `age >= 0` failed in `person::person(std::string_view, std::string_view, int)`

Post-conditions

Finally, post-conditions allow us to provide a guarantee that our invariants hold upon exiting a
function. These are a bit different in usage: instead of providing just an expression, the intended
usage is to place your post-condition in a return-statement. As such, there should only be one
post-condition per return-statement in a function.

#include <cjdb/contracts.hpp>
int f()
{
    auto result = g();
    return CJDB_ENSURES(result >= 0), result;
}

This usage lets us chain post-conditions before our result is returned. As with pre-conditions and
assertions, the diagnostic indicates what kind of contract was violated.

constexpr-contracts in constant expressions

Notice that person::person is constexpr. constexpr-contracts has a huge advantage over both
assert and static_assert, because it can be evaluated at compile-time or at run-time,
depending on the context. If we wanted to constant-initialise ada_lovelace, then we’d get a
compile-time diagnostic instead. They’re fairly difficult to read, so I’ve put one below to guide
you.

Clang

constexpr auto ada_lovelace = person{
               ^              ~~~~~~~
../include/cjdb/contracts.hpp:57:4: note: subexpression not valid in a constant expression
                        __builtin_unreachable();
                        ^
../test/person.cpp:8:10: note: in call to 'contract_impl(false, {&"../test/person.cpp:8: pre-condition `age >= 0` failed in `%s`\n"[0], 62}, {&__PRETTY_FUNCTION__[0], 73})'
        , age_{(CJDB_EXPECTS(age >= 0), age)}
                ^
../include/cjdb/contracts.hpp:29:27: note: expanded from macro 'CJDB_EXPECTS'
#define CJDB_EXPECTS(...) CJDB_CONTRACT_IMPL("pre-condition", __VA_ARGS__)
                          ^
../include/cjdb/contracts.hpp:66:4: note: expanded from macro 'CJDB_CONTRACT_IMPL'
   ::cjdb::contracts_detail::contract_impl(static_cast<bool>(__VA_ARGS__),    \
   ^
../test/person.cpp:16:31: note: in call to 'person({&"Ada"[0], 3}, {&"Lovelace"[0], 8}, -1)'
constexpr auto ada_lovelace = person{
                              ^

That’s a lot of error to say that age < 0! We can fortunately ignore 90% of the above. The only
useful information in the entire diagnostic for our purposes are the first eight lines.

constexpr auto ada_lovelace = person{
               ^              ~~~~~~~
../include/cjdb/contracts.hpp:57:4: note: subexpression not valid in a constant expression
                        __builtin_unreachable();
                        ^
../test/person.cpp:8:10: note: in call to 'contract_impl(false, {&"../test/person.cpp:8: pre-condition `age >= 0` failed in `%s`\n"[0], 62}, {&__PRETTY_FUNCTION__[0], 73})'
        , age_{(CJDB_EXPECTS(age >= 0), age)}
                ^

Here, we see that constexpr auto ada_lovelace = person{ is the offending call-site, and that
CJDB_EXPECTS(age >= 0) is the contract that we broke. Literally everything else is helper
information that the compiler needs to give us, but we don’t need.

GCC

In file included from ../test/person.cpp:1:
../test/person.cpp:20:1:   in ‘constexpr’ expansion of ‘person(std::basic_string_view<char>(((const char*)"Ada")), std::basic_string_view<char>(((const char*)"Lovelace")), -1)’
../test/person.cpp:8:10:   in ‘constexpr’ expansion of ‘cjdb::contracts_detail::contract_impl(((int)(((int)age) >= 0)), std::basic_string_view<char>(((const char*)"../test/person.cpp:8: pre-condition `age >= 0` failed in `%s`\012")), std::basic_string_view<char>(((const char*)(& __PRETTY_FUNCTION__))))’
../include/cjdb/contracts.hpp:57:25: error: ‘__builtin_unreachable()’ is not a constant expression
   57 |    __builtin_unreachable();
      |    ~~~~~~~~~~~~~~~~~~~~~^~

Sadly, GCC’s diagnostic is much more technical, and harder to read. You’ll need to look for
cjdb::contract_impl(((int)(((int)age) >= 0)).
cjdb::contract_impl is an implementation detail, so only look for it in
diagnostics, as it is subject to change. As such, I’m working on a way to provide a much better
diagnostic.

Pitfalls

Because we’re peering into the definition here, the code is somewhat brittle: any user-facing
declaration needs to match the definition right down to parameter names; otherwise the contract won’t
make much sense to the user.