Closure semantics

The xtensor library is a tensor expression library implementing numpy-style broadcasting and universal functions, but in a lazy fashion.

If x and y are two tensor expressions with compatible shapes, the result of x + y is not a tensor but an expression that does not hold any value. Values of x + y are computed upon access or when it is assigned to a container such as xt::xtensor or xt::xarray. The same holds for most functions in xtensor, views, broadcasting views, etc.

In order to be able to perform the differed computation of x + y, the returned expression must hold references, const references or copies of the members x and y, depending on how arguments were passed to operator+. The actual types of held by the expressions are the closure types.

The concept of closure type is key in the implementation of xtensor and appears in all the expression defined in xtensor, and the utility functions and meta functions complements the tools of the standard libary for the move semantics.

Basic rules for determinning closure types

The two main requirements are the following:

  • when an argument passed to the function returning an expression (here, operator+) is an rvalue, the closure type is always a value and the rvalue is moved.
  • when an argument passed to the function returning an expression is an lvalue reference, the closure type is a reference of the same type.

It is important for the closure type not to be a reference when the passed argument is an rvalue, which can result in dangling references.

Following the idioms of the C++ standard library for naming type traits, we provide two type traits classes providing an implementation of these rules in the xutils.hpp header, closure, and const_closure. The latter adds the const qualifier even when the provided argument is not const.

template <class S>
struct closure
{
    using underlying_type = std::conditional_t<
        std::is_const<std::remove_reference_t<S>>::value,
        const std::decay_t<S>,
        std::decay_t<S>>;
    using type = typename std::conditional<
        std::is_lvalue_reference<S>::value,
        underlying_type&,
        underlying_type>::type;
};

template <class S>
using closure_t = typename closure<S>::type;

The implementation for const_closure is slightly shorter.

template <class S>
struct const_closure
{
    using underlying_type = const std::decay_t<S>;
    using type = typename std::conditional<
        std::is_lvalue_reference<S>::value,
        underlying_type&,
        underlying_type>::type;
};

template <class S>
using const_closure_t = typename const_closure<S>::type;

Using this mechanism, we were able to

  • avoid dangling references in nested expressions,
  • hold references whenever possible,
  • take advantage of the move semantics when holding references is not possible.

Closure types and scalar wrappers

A requirement for xtensor is the ability to mix scalars and tensors in tensor expressions. In order to do so, scalar values are wrapped into the xscalar wrapper, which is a cheap 0-D tensor expression holding a single scalar value.

For the xscalar to be a proper proxy on the scalar value, if actually holds a closure type on the scalar value.

The logics for this is encoded into xtensor’s xclosure type trait.

template <class E, class EN = void>
struct xclosure
{
    using type = detail::closure_t<E>;
};

template <class E>
struct xclosure<E, disable_xexpression<std::decay_t<E>>>
{
    using type = xscalar<detail::closure_t<E>>;
};

template <class E>
using xclosure_t = typename xclosure<E>::type;

In doing so, we ensure const-correctness, we avoid dangling reference, and ensure that lvalues remain lvalues. The const_xclosure follows the same scheme:

template <class E, class EN = void>
struct const_xclosure
{
    using type = detail::const_closure_t<E>;
};

template <class E>
struct const_xclosure<E, disable_xexpression<std::decay_t<E>>>
{
    using type = xscalar<std::decay_t<E>>;
};

template <class E>
using const_xclosure_t = typename const_xclosure<E>::type;

Writing functions that return expressions

xtensor closure semantics are not meant to prevent users from doing something wrong, since it would also prevent them from doing something clever.

This section covers cases where understanding C++ move semantics and xtensor closure semantics helps writing better code with xtensor.

Returning evaluated or unevaluated expressions

A key feature of xtensor is that a function returning e.g. x + y / z where x, y and z are xtensor expressions does not actually perform any computation. It is only evaluated upon access or assignment. The returned expression holds values or references for x, y and z depending on the lvalue-ness of the variables passed to the expression, using the closure semantics described earlier.

However, this may result in dangling references when using local variables of a function in an unevaluated expression, unless one properly forwards / move the variables.

  • In any case, if the laziness is not important for your usecase, returning xt::eval(x + y / z) will return an evaluated container and avoid these complications.
  • Otherwise, the key is to move lvalues that become invalid when leaving the current scope.

Example: moving local variables and forwarding universal references

Let us first consider the following implementation of the mean function in xtensor:

template <class E>
inline auto mean(E&& e) noexcept
{
    using value_type = typename std::decay_t<E>::value_type;
    auto size = e.size();
    auto s = sum(std::forward<E>(e));
    return std::move(s) / value_type(size);
}

The first thing to understand is that the result of the final division is an expression, which performs the actual computation upon access or assignent.

  • In order to perform the division, the expression must hold the values or references on the numerator and denominator.
  • Since s is a local variable, it will be destroyed upon leaving the scope of the function, and more importantly it is an lvalue.
  • A consequence of s being an lvalue and a local variable, is that the s / value_type(size) would end up holding a dangling const reference on s.
  • Hence we must call return std::move(s) / value_type(size).

The other place in this example where the C++ move semantics is used is the line s = sum(std::forward<E>(e)). The goal is to have the unevaluated s expression hold a const reference or a value for e depending on the lvalue-ness of the parameter passed to the function.