C++ named requirements: Callable

From cppreference.com
< cpp‎ | named req
 
 
C++ named requirements
Basic
Type properties
Library-Wide
Container
Container Elements
Iterator
Stream I/O
Formatting
(C++20)
Random Numbers
Concurrency
(C++11)
(C++11)
Other
 

A Callable type is a type for which the INVOKE operation (used by, e.g., std::function, std::bind, and std::thread::thread) is applicable.

The INVOKE operation may be performed explicitly using the library function std::invoke.

(since C++17)

The INVOKE operation with explicitly specified return type (INVOKE<R>) may be performed explicitly using the library function std::invoke_r.

(since C++23)

Requirements

The type T satisfies Callable if

Given

  • f, an object of type T
  • ArgTypes, suitable list of argument types
  • R, suitable return type

The following expressions must be valid:

Expression Requirements
INVOKE<R>(f, std::declval<ArgTypes>()...) the expression is well-formed in unevaluated context

where INVOKE<R>(f, t1, t2, ..., tN) is defined as static_cast<void>(INVOKE(f, t1, t2, ..., tN)) if R is possibly cv-qualified void, otherwise, INVOKE(f, t1, t2, ..., tN) is implicitly converted to R. If R is a reference type and the implicit conversion binds a reference to a temporary object, the program is ill-formed, which may result in substitution failure. (since C++23)

where INVOKE(f, t1, t2, ..., tN) is defined as follows:

  • If std::is_base_of<T, std::remove_reference_t<decltype(t1)>>::value is true, then INVOKE(f, t1, t2, ..., tN) is equivalent to (t1.*f)(t2, ..., tN)
  • otherwise, if std::remove_cvref_t<decltype(t1)> is a specialization of std::reference_wrapper, then INVOKE(f, t1, t2, ..., tN) is equivalent to (t1.get().*f)(t2, ..., tN)
  • otherwise, if t1 does not satisfy the previous items, then INVOKE(f, t1, t2, ..., tN) is equivalent to ((*t1).*f)(t2, ..., tN).
  • otherwise, INVOKE(f, t1, t2, ..., tN) is equivalent to f(t1, t2, ..., tN) (that is, f is a FunctionObject)

Notes

For pointers to member functions and pointers to data members, t1 may be a regular pointer or an object of class type that overloads operator*, such as std::unique_ptr or std::shared_ptr.

Pointers to data members are Callable, even though no function calls take place.

Standard library

In addition, the following standard library facilities accept any Callable type (not just FunctionObject)

(C++11)
wraps callable object of any copy constructible type with specified function call signature
(class template)
wraps callable object of any type with specified function call signature
(class template)
(C++11)
binds one or more arguments to a function object
(function template)
(C++20)(C++23)
bind a variable number of arguments, in order, to a function object
(function template)
CopyConstructible and CopyAssignable reference wrapper
(class template)
(C++11)(removed in C++20)(C++17)
deduces the result type of invoking a callable object with a set of arguments
(class template)
(C++11)
manages a separate thread
(class)
(C++20)
std::thread with support for auto-joining and cancellation
(class)
(C++11)
invokes a function only once even if called from multiple threads
(function template)
(C++11)
runs a function asynchronously (potentially in a new thread) and returns a std::future that will hold the result
(function template)
packages a function to store its return value for asynchronous retrieval
(class template)

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
LWG 2219 C++11 it's impossible to INVOKE a pointer to member
with a reference_wrapper as the object expression
reference_wrapper is detected and handled
LWG 2420 C++11 impossible implicit conversion from the result
to void was required when R is void
the result is discarded when R is cv void

See also

checks if a type can be invoked (as if by std::invoke) with the given argument types
(class template)
specifies that a callable type can be invoked with a given set of argument types
(concept)
(C++17)(C++23)
invokes any Callable object with given arguments and possibility to specify return type (since C++23)
(function template)