| Home | Libraries | People | FAQ | More

### Call Traits

#### Introduction

All of the contents of `<boost/call_traits.hpp>` are defined inside `namespace boost`.

The template class `call_traits<T>` encapsulates the "best" method to pass a parameter of some type `T` to or from a function, and consists of a collection of `typedef`s defined as in the table below. The purpose of `call_traits` is to ensure that problems like "references to references" never occur, and that parameters are passed in the most efficient manner possible, as in the examples. In each case, if your existing practice is to use the type defined on the left, then replace it with the `call_traits` defined type on the right.

Note that for compilers that do not support either partial specialization or member templates, no benefit will occur from using `call_traits`: the `call_traits` defined types will always be the same as the existing practice in this case. In addition if only member templates and not partial template specialisation is support by the compiler (for example Visual C++ 6) then `call_traits` cannot be used with array types, although it can still be used to solve the reference to reference problem.

Table 1.2. `call_traits` types

Existing practice | `call_traits` equivalent | Description | Notes
--- | --- | --- | ---
`T` (return by value) | `call_traits<T>``::value_type` | Defines a type that represents the "value" of type `T`. Use this for functions that return by value, or possibly for stored values of type `T`. | 2
`T&` (return value) | `call_traits<T>``::reference` | Defines a type that represents a reference to type `T`. Use for functions that would normally return a `T&`. | 1
`const T&` (return value) | `call_traits<T>``::const_reference` | Defines a type that represents a constant reference to type `T`. Use for functions that would normally return a `const T&`. | 1
`const T&` (function parameter) | `call_traits<T>``::param_type` | Defines a type that represents the "best" way to pass a parameter of type `T` to a function. | 1,3

Notes:

1. If `T` is already reference type, then `call_traits` is defined such that "references to references" do not occur (requires partial specialization).
2. If `T` is an array type, then `call_traits` defines `value_type` as a "constant pointer to type" rather than an "array of type" (requires partial specialization). Note that if you are using `value_type` as a stored value then this will result in storing a "constant pointer to an array" rather than the array itself. This may or may not be a good thing depending upon what you actually need (in other words take care!).
3. If `T` is a small built in type or a pointer, then `param_type` is defined as `T const`, instead of `T const&`. This can improve the ability of the compiler to optimize loops in the body of the function if they depend upon the passed parameter, the semantics of the passed parameter is otherwise unchanged (requires partial specialization).

#### Copy constructibility

The following table defines which `call_traits` types can always be copy-constructed from which other types:

Table 1.3. Which `call_traits` types can always be copy-constructed from which other types

| To `T` | To `value_type` | To `reference` | To `const_reference` | To `param_type`
--- | --- | --- | --- | --- | ---
From `T` | iff `T` is copy constructible | iff `T` is copy constructible | Yes | Yes | Yes
From `value_type` | iff `T` is copy constructible | iff `T` is copy constructible | No | No | Yes
From `reference` | iff `T` is copy constructible | iff `T` is copy constructible | Yes | Yes | Yes
From `const_reference` | iff `T` is copy constructible | No | No | Yes | Yes
From `param_type` | iff `T` is copy constructible | iff `T` is copy constructible | No | No | Yes

If `T` is an assignable type the following assignments are possible:

Table 1.4. Which `call_traits` types are assignable from which other types

| To `T` | To `value_type` | To `reference` | To `const_reference` | To `param_type`
--- | --- | --- | --- | --- | ---
From `T` | Yes | Yes | - | - | -
From `value_type` | Yes | Yes | - | - | -
From `reference` | Yes | Yes | - | - | -
From `const_reference` | Yes | Yes | - | - | -
From `param_type` | Yes | Yes | - | - | -

#### Examples

The following table shows the effect that `call_traits` has on various types.

Table 1.5. Examples of `call_traits` types

| `call_traits`::`value_type` | `call_traits`::`reference` | `call_traits`::`const_reference` | `call_traits`::`param_type` | Applies to:
--- | --- | --- | --- | --- | ---
From `my_class` | `my_class` | `my_class&` | `const my_class&` | `my_class const&` | All user-defined types
From `int` | `int` | `int&` | `const int&` | `int const` | All small built-in types
From `int*` | `int*` | `int*&` | `int* const &` | `int* const` | All pointer types
From `int&` | `int&` | `int&` | `const int&` | `int&` | All reference types
From `const int&` | `const int&` | `const int&` | `const int&` | `const int&` | All constant reference types
From `int[3]` | `const int*` | `int(&)[3]` | `const int(&)[3]` | `const int* const` | All array types
From `const int[3]` | `const int*` | `const int(&)[3]` | `const int(&)[3]` | `const int* const` | All constant array types

The table assumes the compiler supports partial specialization: if it does not then all types behave in the same way as the entry for "`my_class`", and `call_traits` can not be used with reference or array types.

##### Example 1:

The following class is a trivial class that stores some type `T` by value (see the `call_traits_test.cpp` file). The aim is to illustrate how each of the available `call_traits` `typedef`s may be used:

    template <class T>
    struct contained
    {
       // define our typedefs first, arrays are stored by value
       // so value_type is not the same as result_type:
       typedef typename boost::call_traits<T>::param_type       param_type;
       typedef typename boost::call_traits<T>::reference        reference;
       typedef typename boost::call_traits<T>::const_reference  const_reference;
       typedef T                                                value_type;
       typedef typename boost::call_traits<T>::value_type       result_type;

       // stored value:
       value_type v_;

       // constructors:
       contained() {}
       contained(param_type p) : v_(p){}
       // return byval:
       result_type value() { return v_; }
       // return by_ref:
       reference get() { return v_; }
       const_reference const_get()const { return v_; }
       // pass value:
       void call(param_type p){}

    };

##### Example 2 (the reference to reference problem):

Consider the definition of `std::binder1st`:

    template <class Operation>
    class binder1st :
       public std::unary_function<typename Operation::second_argument_type, typename Operation::result_type>
    {
    protected:
       Operation op;
       typename Operation::first_argument_type value;
    public:
       binder1st(const Operation& x, const typename Operation::first_argument_type& y);
       typename Operation::result_type operator()(const typename Operation::second_argument_type& x) const;
    };

Now consider what happens in the relatively common case that the functor takes its second argument as a reference, that implies that `Operation::second_argument_type` is a reference type, `operator()` will now end up taking a reference to a reference as an argument, and that is not currently legal. The solution here is to modify `operator()` to use `call_traits`:

    typename Operation::result_type operator()(typename call_traits<typename Operation::second_argument_type>::param_type x) const;

Now in the case that `Operation::second_argument_type` is a reference type, the argument is passed as a reference, and the no "reference to reference" occurs.

##### Example 3 (the `make_pair` problem):

If we pass the name of an array as one (or both) arguments to ``std::make_pair``, then template argument deduction deduces the passed parameter as "const reference to array of `T`", this also applies to string literals (which are really array literals). Consequently instead of returning a pair of pointers, it tries to return a pair of arrays, and since an array type is not copy-constructible the code fails to compile. One solution is to explicitly cast the arguments to `std::make_pair` to pointers, but `call_traits` provides a better automatic solution that works safely even in generic code where the cast might do the wrong thing:

    template <class T1, class T2>
    std::pair<
       typename boost::call_traits<T1>::value_type,
       typename boost::call_traits<T2>::value_type>
          make_pair(const T1& t1, const T2& t2)
    {
       return std::pair<
          typename boost::call_traits<T1>::value_type,
          typename boost::call_traits<T2>::value_type>(t1, t2);
    }

Here, the deduced argument types will be automatically degraded to pointers if the deduced types are arrays, similar situations occur in the standard binders and adapters: in principle in any function that "wraps" a temporary whose type is deduced. Note that the function arguments to `std::make_pair` are not expressed in terms of `call_traits`: doing so would prevent template argument deduction from functioning.

##### Example 4 (optimising fill):

The `call_traits` template will "optimize" the passing of a small built-in type as a function parameter. This mainly has an effect when the parameter is used within a loop body.

In the following example (see `fill_example.cpp`), a version of `std::fill` is optimized in two ways: if the type passed is a single byte built-in type then `std::memset` is used to effect the fill, otherwise a conventional C++ implementation is used, but with the passed parameter "optimized" using `call_traits`:

    template <bool opt>
    struct filler
    {
       template <typename I, typename T>
       static void do_fill(I first, I last, typename boost::call_traits<T>::param_type val)
       {
          while(first != last)
          {
             *first = val;
             ++first;
          }
       }
    };

    template <>
    struct filler<true>
    {
       template <typename I, typename T>
       static void do_fill(I first, I last, T val)
       {
          std::memset(first, val, last-first);
       }
    };

    template <class I, class T>
    inline void fill(I first, I last, const T& val)
    {
       enum { can_opt = boost::is_pointer<I>::value
                       && boost::is_arithmetic<T>::value
                       && (sizeof(T) == 1) };
       typedef filler<can_opt> filler_t;
       filler_t::template do_fill<I,T>(first, last, val);
    }

The reason that this is "optimal" for small built-in types is that with the value passed as `T const` instead of `const T&` the compiler is able to tell both that the value is constant and that it is free of aliases. With this information the compiler is able to cache the passed value in a register, unroll the loop, or use explicitly parallel instructions: if any of these are supported. Exactly how much mileage you will get from this depends upon your compiler - we could really use some accurate benchmarking software as part of boost for cases like this.

Note that the function arguments to fill are not expressed in terms of `call_traits`: doing so would prevent template argument deduction from functioning. Instead fill acts as a "thin wrapper" that is there to perform template argument deduction, the compiler will optimise away the call to fill all together, replacing it with the call to `filler<>::do_fill`, which does use `call_traits`.

#### Rationale

The following notes are intended to briefly describe the rationale behind choices made in `call_traits`.

All user-defined types follow "existing practice" and need no comment.

Small built-in types, what the standard calls fundamental types, differ from existing practice only in the `param_type` `typedef`. In this case passing `T const` is compatible with existing practice, but may improve performance in some cases (see Example 4). In any case this should never be any worse than existing practice.

Pointers follow the same rationale as small built-in types.

For reference types the rationale follows Example 2 - references to references are not allowed, so the `call_traits` members must be defined such that these problems do not occur. There is a proposal to modify the language such that "a reference to a reference is a reference" (issue #106, submitted by Bjarne Stroustrup). `call_traits<T>``::value_type` and `call_traits<T>``::param_type` both provide the same effect as that proposal, without the need for a language change. In other words, it's a workaround.

For array types, a function that takes an array as an argument will degrade the array type to a pointer type: this means that the type of the actual parameter is different from its declared type, something that can cause endless problems in template code that relies on the declared type of a parameter.

For example:

    template <class T>
    struct A
    {
       void foo(T t);
    };

In this case if we instantiate `A<int[2]>` then the declared type of the parameter passed to member function `foo` is `int[2]`, but its actual type is `const int*`. If we try to use the type `T` within the function body, then there is a strong likelihood that our code will not compile:

    template <class T>
    void A<T>::foo(T t)
    {
       T dup(t); // doesn't compile for case that T is an array.
    }

By using `call_traits` the degradation from array to pointer is explicit, and the type of the parameter is the same as it's declared type:

    template <class T>
    struct A
    {
       void foo(typename call_traits<T>::value_type t);
    };

    template <class T>
    void A<T>::foo(typename call_traits<T>::value_type t)
    {
       typename call_traits<T>::value_type dup(t); // OK even if T is an array type.
    }

For `value_type` (return by value), again only a pointer may be returned, not a copy of the whole array, and again `call_traits` makes the degradation explicit. The `value_type` member is useful whenever an array must be explicitly degraded to a pointer - Example 3 provides the test case.

Footnote: the array specialisation for `call_traits` is the least well understood of all the `call_traits` specialisations. If the given semantics cause specific problems for you, or does not solve a particular array-related problem, then I would be interested to hear about it. Most people though will probably never need to use this specialisation.

#### Reference

##### Header <boost/detail/call_traits.hpp>

    namespace boost {
      template<typename T> struct call_traits;

      template<typename T, std::size_t N> struct call_traits<const T[N]>;
      template<typename T> struct call_traits<T &>;
      template<typename T, std::size_t N> struct call_traits<T[N]>;
    }