Named Requirements#
[named_requirements]
This section describes named requirements used in the oneTBB Specification.
A named requirement is a set of requirements on a type. The requirements may be syntactic or semantic. The named requirement term is similar to “Requirements on types and expressions” term which is defined by the ISO C++ Standard (chapter “Library Introduction”) or “Named Requirements” section on the cppreference.com site.
For example, the named requirement of sortable could be defined as a set of requirements that enable
an array to be sorted. A type T would be sortable if:
x < yreturns a boolean value, and represents a total order on items of typeT.swap(x,y)swaps itemsxandy
You can write a sorting template function in C++ that sorts an array of any type that is sortable.
Pseudo-Signatures#
Two approaches for defining named requirements are valid expressions and pseudo-signatures. The ISO C++ standard follows the valid expressions approach, which shows what the usage pattern looks like for a requirement. It has the drawback of relegating important details to notational conventions. This document mostly uses pseudo-signatures because they are concise and can be cut-and-pasted for an initial implementation.
A pseudo-signature describes how an implementation interacts with a type or a function. A real function signature (after template instantiation, if applicable) may differ from the pseudo-signature that it implements in ways where implicit conversions would deal with the difference, transforming function parameter types from the ones in the pseudo-signature to the real signature, and transforming the actual return value type to the one in the pseudo-signature.
For example, the table below shows pseudo-signatures for a sortable type T:
Sortable Requirements : Pseudo-Signature, Semantics
-
bool operator<(const T &x, const T &y)#
Compare
xandy.
-
void swap(T &x, T &y)#
Swap
xandy.
For a given type U, the real signature that implements operator< in the table above
can be expressed as int operator<( U x, U y ), because C++ permits implicit conversion from
int to bool, and implicit conversion from const U& to U if the type is copy-constructible.
As a counter-example, the real signature bool operator<( U& x, U& y ) is not acceptable
because C++ does not permit implicit removal of the const qualifier from a type, and so the code
would not compile if the implementation attempts to pass a constant object to the function.
Besides pseudo-signatures, semantic requirements also need to be met by real types and functions.
For example, while std::pair<U, U> swap(U x, U y) fits the pseudo-signature for Sortable
via implicit conversion of references to values and implicit drop of the returned value
(ignored by a library implementation), it is unable to swap the actual variables passed to the function
and therefore does not meet the semantic requirements of Sortable.
The following table provides guidance for the types of parameters used in pseudo-signatures and potential alternatives in real signatures. In practice, suitable alternatives might depend on the semantic requirements as well as type properties, such as availability of copy- or move-constructors.
Pseudo-signature parameter |
General semantics |
Alternative real parameters |
|---|---|---|
|
The function is not supposed to modify the argument. |
Here and below |
|
The argument is an lvalue. The function can or is supposed to modify the argument. |
|
|
The argument is an rvalue. The function can use the argument as a source in move operations. |
|