function_ref: a type-erased callable reference

Table of contents

• function_ref: a type-erased callable reference
  • Table of contents
  • Changelog
    • R7
    • R6
    • R5
    • R4
    • R3
    • R2
    • R1
  • Abstract
  • Motivating example
    • Using function pointers
    • Using a template
    • Using std::function or std::move_only_function
    • Using the proposed function_ref
  • Design considerations
    • Survey
    • Proposal
    • Additional information
  • Wording
  • Feature test macro
  • Implementation Experience
  • Acknowledgments
  • References

Changelog

R7

• Clarify the proposal to handle function and function pointers in the same way.

R6

• Avoid double-wrapping existing references to callables;
• Reworked the wording to follow the latest standardese;
• Applied changes requested by LWG (2020-07);
• Removed a deduction guide that is incompatible with explicit object parameters.

R5

• Removed “qualifiers” from operator() specification (typo);

R4

• Removed constexpr due to implementation concerns;
• Explicitly say that the type is trivially copyable;
• Added brief before synopsis;
• Reworded specification following P1369.

R3

• Constructing or assigning from std::function no longer has a precondition;
• function_ref::operator() is now unconditionally const-qualified.

R2

• Made copy constructor and assignment operator = default;
• Added exposition only data members.

R1

• Removed empty state, comparisons with nullptr, and default constructor;
• Added support for noexcept and const-qualified function signatures;
• Added deduction guides similar to std::function;
• Added example implementation;
• Added feature test macro;
• Removed noexcept from constructor and assignment operator.

Abstract

This paper proposes the addition of function_ref<R(Args...)>, a vocabulary type with reference semantics for passing entities to call, to the standard library.

Motivating example

Here’s one example use case that benefits from higher-order functions: a retry(n, f) function that attempts to call f up to n times synchronously until success. This example might model the real-world scenario of repeatedly querying a flaky web service.

using payload = std::optional< /* ... */ >;

// Repeatedly invokes `action` up to `times` repetitions.
// Immediately returns if `action` returns a valid `payload`.
// Returns `std::nullopt` otherwise.
payload retry(size_t times, /* ????? */ action);

The passed-in action should be a callable entity that takes no arguments and returns a payload. Let’s see how to implemented retry with various techniques.

Using function pointers

payload retry(size_t times, payload(*action)())
{
    /* ... */
}

• Advantages:

  • Easy to implement: no template, nor constraint. The function pointer type has a signature that nails down which functions to pass.

  • Minimal overhead: no allocations, no exceptions, and major calling conventions can pass a function pointer in a register.

• Drawbacks:

  • A function is usually not stateful, nor does captureless closure objects. One cannot pass other function objects in C++ this way.

Using a template

template<class F>
auto retry(size_t times, F&& action)
requires std::is_invocable_r_v<payload, F>
{
    /* ... */
}

• Advantages:

  • Support arbitrary function objects, such as closures with captures.

  • Zero-overhead: no allocations, no exceptions, no indirections.

• Drawbacks:

  • Harder to implement: users must constrain action’s signature.

  • Fail to support separable compilation: the implementation of retry must appear in a header file. A slight change at the call site will cause recompilation of the function body.

Using std::function or std::move_only_function

payload retry(size_t times, std::move_only_function<payload()> action)
{
    /* ... */
}

• Advantages:

  • Take more callable objects, from closures to pointer-to-members.

  • Easy to implement: no need to use a template or any explicit constraint. std::function and std::move_only_function constructor is constrained.

• Drawbacks:

  • std::function and std::move_only_function’s converting constructor^[1] require their target objects to be copy-constructible or move-constructible, respectively;

  • Comes with potentially significant overhead:

    • The call wrappers start to allocate the target objects when they do not fit in a small buffer, introducing more indirection when calling the objects.

    • No calling conventions can pass these call wrappers in registers.

    • Modern compilers cannot inline these call wrappers, often resulting in inferior codegen then previously mentioned techniques.

  One rarely known technique is to pass callable objects to call wrappers via a std::reference_wrapper:

  auto result = retry(3, std::ref(downloader));
  

  But users cannot replace the downloader in the example with a lambda expression as such an expression is an rvalue. Meanwhile, all the machinery that implements type-erased copying or moving must still be present in the codegen.

Using the proposed function_ref

payload retry(size_t times, function_ref<payload()> action)
{
    /* ... */
}

• Advantages:

  • Takes any callable objects regardless of whether they are constructible.

  • Easy to implement: no need to use a template or any constraint. function_ref is constrained.

  • Clean ownership semantics: function_ref has reference semantics as its name suggests.

  • Minimal overhead: no allocations, no exceptions, certain calling conventions can pass function_ref in registers.

    • Modern compilers can perform tail-call optimization when generating thunks. If the function body is visible, they can deliver optimal codegen, identical to the template solution.

Design considerations

This paper went through LEWG at R5, with a number of consensuses reached and applied to the wording:

1. Do not provide target() or target_type;
2. Do not provide operator bool, default constructor, or comparison with nullptr;
3. Provide R(Args...) noexcept specializations;
4. Provide R(Args...) const specializations;
5. Require the target entity to be Lvalue-Callable;
6. Make operator() unconditionally const;
7. Choose function_ref as the right name.

One design question remains not fully understood by many: how should a function pointer initialize function_ref?

In a typical scenario, there is no lifetime issue no matter whether the download entity below is a function, a function pointer, or a closure:

auto result = retry(3, download); // always safe

However, even if the users use function_ref only as parameters initially, it’s not uncommon to evolve the API by grouping parameters into structures,

struct retry_options
{
    size_t times;
    function_ref<payload()> action;
    seconds step_back;
};

payload retry(retry_options);

/* ... */

auto result = retry({.times = 3,
                     .action = download,
                     .step_back = 1.5s});

and structures start to need constructors or factories to simplify initialization:

auto opt = default_strategy();
opt.action = download;
auto result = retry(opt);

According to the P0792R5^[2] wording, the code has well-defined behavior if download is a function. However, one cannot write the code as

auto opt = default_strategy();
opt.action = &download;
auto result = retry(opt);

since this will create a function_ref with a dangling object pointer that points to a temporary object – the function pointer.

In other words, the following code also has undefined behavior:

auto opt = default_strategy();
opt.action = ssh.get_download_callback(); // a function pointer
auto result = retry(opt);

The users have to write the following to get well-defined behavior.

auto opt = default_strategy();
opt.action = *ssh.get_download_callback();
auto result = retry(opt);

Survey

We collected the following function_ref implementations available today:

■llvm::function_ref – from LLVM^[3]

■tl::function_ref – by Sy Brand

■folly::FunctionRef – from Meta

■gdb::function_view – from GNU

■type_safe::function_ref – by Jonathan Müller^[4]

■absl::function_ref – from Google

They have diverging behaviors when initialized from function pointers:

opt.action = ssh.get_download_callback();

opt.action = download;

opt.action = ssh.get_download_callback();

opt.action = download;

P0792R5 wording gives Behavior A.1.

A related question is what happens when initialized from pointer-to-members. In the following tables, assume &Ssh::connect is a pointer to member function:

lib.send_cmd(&Ssh::connect);

function_ref<void(Ssh&)> cmd = &Ssh::connect;

lib.send_cmd(&Ssh::connect);

function_ref<void(Ssh&)> cmd = &Ssh::connect;

lib.send_cmd(std::mem_fn(&Ssh::connect));

P0792R5-R7 wording gives Behavior B.1.

Proposal

We propose Behavior A.2 to eliminate the difference between initializing function_ref from a function and initializing function_ref from a function pointer.

Additional information

P2472R1 “make function_ref more functional” ^[5] suggests a way to initialize function_ref from pointer-to-members without dangling in all contexts:

function_ref<void(Ssh&)> cmd = nontype<&Ssh::connect>;

Not convertible from pointer-to-members means that function_ref does not need to use invoke_r, improving debug codegen in specific toolchains with little effort.

Making function_ref large enough to fit a thunk pointer plus any pointer-to-member-function may render std::function_ref irrelevant in the real world. Some platform ABIs can pass a trivially copyable type of a 2-word size in registers and cannot do the same to a bigger type. Here is some LLVM IR to show the difference: https://godbolt.org/z/Ke3475vz8.

Wording

The wording is relative to N4901.

Add the template to [functional.syn], header <functional> synopsis:

[…]

  // [func.wrap.move], move only wrapper
  template<class... S> class move_only_function;        // not defined
  template<class R, class... ArgTypes>
    class move_only_function<R(ArgTypes...) cv ref noexcept(noex)>; // see below

  // [func.wrap.ref], non-owning wrapper
  template<class S> class function_ref;                 // not defined
  template<class R, class... ArgTypes>
    class function_ref<R(ArgTypes...) cv noexcept(noex)>;           // see below

[…]

Create a new section “Non-owning wrapper”, [func.wrap.ref] with the following:

General

[func.wrap.ref.general]

The header provides partial specializations of function_ref for each combination of the possible replacements of the placeholders cv and noex where:

• cv is either const or empty.
• noex is either true or false.

An object of class function_ref<S> stores a pointer to thunk and a bound argument entity. A thunk is a function where a pointer to that function is a perfect forwarding call wrapper [func.def]. The bound argument is of an implementation-defined type to represent a pointer to object value, a pointer to function value, or a null pointer value.

function_ref<S> is a trivially copyable type [basic.types].

Within this subclause, call_args is an argument pack used in a function call expression [expr.call] of *this, and val is the value that the bound argument stores.

Class template function_ref

[func.wrap.ref.class]

namespace std
{
  template<class S> class function_ref;       // not defined

  template<class R, class... ArgTypes>
  class function_ref<R(ArgTypes...) cv noexcept(noex)>
  {
  public:
    // [func.wrap.ref.ctor], constructors and assignment operator
    constexpr template<class F> function_ref(F*) noexcept;
    constexpr template<class F> function_ref(F&&) noexcept;

    constexpr function_ref(const function_ref&) noexcept = default;
    constexpr function_ref& operator=(const function_ref&) noexcept = default;

    // [func.wrap.ref.inv], invocation
    R operator()(ArgsTypes...) const noexcept(noex);
  private:
    template<class... T>
      static constexpr bool is-invocable-using = see below;   // exposition only
  };

  // [func.wrap.ref.deduct], deduction guides
  template<class F>
    function_ref(F*) -> function_ref<F>;
}

Constructors and assignment operator

[func.wrap.ref.ctor]

template<class... T>
  static constexpr bool is-invocable-using = see below;

If noex is true, is-invocable-using<T...> is equal to:

  is_nothrow_invocable_r_v<R, T..., ArgTypes...>

Otherwise, is-invocable-using<T...> is equal to:

  is_invocable_r_v<R, T..., ArgTypes...>

template<class F> constexpr function_ref(F* f);

Constraints:

• is_function_v<F> is true, and
• is-invocable-using<F> is true.

Effects: Constructs a function_ref object with the following properties:

• Its bound argument stores the value f.
• Its target object points to a thunk with call pattern invoke_r<R>(val, call_args...).

template<class F> constexpr function_ref(F&& f);

Let T be remove_reference_t<F>.

Constraints:

• remove_cvref_t<F> is not the same type as function_ref, and
• is-invocable-using<cv T&> is true.

Effects: Constructs a function_ref object with the following properties:

• Its bound argument stores the value addressof(f).
• Its target object points to a thunk with call pattern invoke_r<R>(obj, call_args...) where obj is an invented variable introduced in:
  
    cv T& obj = *val;
  
  

constexpr function_ref(const function_ref& f) noexcept = default;

Effects: Constructs a function_ref object with a copy of f’s state entities.

Remarks: This constructor is trivial.

constexpr function_ref& operator=(const function_ref& f) noexcept = default;

Effects: Replaces the state entities of *this with the state entities of f.

Returns: *this.

Remarks: This assignment operator is trivial.

Invocation

[func.wrap.ref.inv]

R operator()(ArgsTypes... args) const noexcept(noex);

Let g be the target object and p be the bound argument entity of *this.

Preconditions: p stores a non-null pointer value.

Effects: Equivalent to return g(p, std::forward<ArgTypes>(args)...);

Deduction guides

[func.wrap.ref.deduct]

template<class F>
  function_ref(F*) -> function_ref<F>;

Constraints: is_function_v<F> is true.

Feature test macro

Insert the following to [version.syn], header <version> synopsis, after __cpp_lib_move_only_function:

#define __cpp_lib_function_ref 20XXXXL // also in <functional>

Implementation Experience

A complete implementation is available from ■ zhihaoy/nontype_functional@p0792r7. You can play with it in Godbolt.

An older

Many facilities similar to function_ref exist and are widely used in large codebases. See Survey for details.

Acknowledgments

Thanks to Agustín Bergé, Dietmar Kühl, Eric Niebler, Tim van Deurzen, and Alisdair Meredith for providing very valuable feedback on earlier drafts of this proposal.

Thanks to Jens Maurer for encouraging participation.

References