9.9 KiB
| title | weight |
|---|---|
| delegate | 1 |
etl::delegate is a type-safe, generic, and efficient delegate implementation. A delegate is essentially a type-safe function pointer. It can be used to encapsulate a callable unit (like a function, a function pointer, member function, or a callable object like a functor or a lambda function) and call it later.
etl::delegate is similar in a lot of ways to std::function_ref introduced with C++26.
The delegate functions may be defined at compile time and/or runtime, depending on the function type. Most delegates can only be constructed via a create function, except lambdas and functors, which can be created by the delegate constructor.
This may be used to implement a platform abstraction layer that allows an embedded application to interface with multiple hardware platforms.
Here's a high-level overview of how etl::delegate works: Creation: When you create a delegate, you specify the function signature that it should match. This is done using template parameters. For example, etl::delegate<void(int)> creates a delegate that can hold references to functions that take an integer as an argument and return void. Assignment: You can assign a function to the delegate using the create method. The function you assign must match the delegate's function signature. For example, if you have a delegate of type etl::delegate<void(int)>, you could assign a function void myFunction(int) to it like this: auto myDelegate = etl::delegate<void(int)>::create(); Invocation: Once a function has been assigned to the delegate, you can call that function through the delegate just like you would call a regular function. For example, if myDelegate is a delegate that holds a reference to myFunction, you could call myFunction through the delegate like this: myDelegate(123);
Notes: <=20.21.0 This class only supports >=C++11.
=20.22.0 This class is automatically selects C++03 or C++11 versions based on the value of ETL_USING_CPP11 The C++03 variant only supports delegates taking 0 or 1 parameter.
etl::delegate is non-owning. You cannot use lambdas that capture variables that will have gone out of scope when the delegate is called. This would result in dangling references. Lambdas are not copied; The delegate merely keeps pointers to lambdas. This also applies to functors.
=20.40.0 Move constructors from lambdas or functors are disabled, thereby stopping a delegate being created from a temporary defined in aparameter.
=20.42.0 etl::delegate is noexcept
etl::delegate<TReturn(TParams…)>
20.22.0 For C++03 etl::delegate<TReturn(void)> etl::delegate<TReturn(TParam)>
For the examples below, assume the following definitions.
class Test { public:
int member_function(int); static int member_static(int); int operator()(int); int operator()(int) const; };
Test test;
int global(int);
auto lambda = [](int i){ return i; };
Public types
return_type TReturn 20.43.0 argument_types etl::type_list<TParams...> 20.43.0
Run time construction
Lambdas etl::delegate<int(int)> d(lambda); etl::delegate<int(int)> d = lambda; etl::delegate<int(int)> d = etl::delegate<int(int)>::create(lambda);
d.set(lambda);
Functors etl::delegate<int(int)> d(test); etl::delegate<int(int)> d = test; etl::delegate<int(int)> d = etl::delegate<int(int)>::create(test);
d.set();
Member functions etl::delegate<int(int)> d = etl::delegate<int(int)>::create<Test, &Test::member_function>(test);
d.set<Test, &Test::member_function>(test); d.set<Test, test, &Test::member_function>();
Compile time construction
Global functions auto d = etl::delegate<int(int)>::create();
Member functions (if the instance is known at compile time) auto d = etl::delegate<int(int)>::create<Test, test, &Test::member_function>(); // Deprecated auto d = etl::delegate<int(int)>::create<Test, &Test::member_function, test>(); // New
Functors (if the instance is known at compile time) auto d = etl::delegate<int(int)>::create<Test, test>(); auto d = etl::delegate<int(int)>::create<const Test, test>(); Note: These are disabled for GCC <= v8.1 as it generates an 'Internal Compiler Error'.
Static member functions auto d = etl::delegate<int(int)>::createTest::member_static();
Constexpr
Most delegates can be declared as constexpr. (C++11 and above) static Test test; constexpr auto d = etl::delegate<int(int)>::create<Test, test, &Test::member_function>();
All create functions are constexpr under C++14. All create functions are nodiscard under C++17.
Calling the delegate
The delegate may be called as a function with the defined parameter signature.
etl::delegate<int(int)> d;
int r = d(3);
Operations
ETL_CONSTEXPR14 delegate() Constructs an uninitialised delegate.
ETL_CONSTEXPR14 delegate(const delegate& other) Copy constructs a delegate.
ETL_CONSTEXPR14 TReturn operator()(TParams... args) const ETL_NOEXCEPT Executes the delegate. constexpr from 20.42.1
20.17.0 ETL_CONSTEXPR14 bool call_if(TParams... args) const ETL_NOEXCEPT For delegates returning void. Calls the delegate if valid. Returns true if valid, otherwise false. constexpr from 20.42.2
ETL_CONSTEXPR14 etl::optional call_if(TParams... args) const ETL_NOEXCEPT For delegates returning TReturn. Calls the delegate if valid. Returns a valid etl::optional containing the return value, if valid. constexpr from 20.42.2
20.17.0 template ETL_CONSTEXPR14 TReturn call_or(TAlternative alternative, TParams... args) const ETL_NOEXCEPT Calls the delegate if valid, otherwise calls alternative. constexpr from 20.42.2
template <TReturn(*Method)(TParams...)> ETL_CONSTEXPR14 TReturn call_or(TParams... args) const ETL_NOEXCEPT Calls the delegate if valid, otherwise calls Method.
void clear() ETL_NOEXCEPT Sets the delegate back to the uninitialised state.
ETL_NODISCARD ETL_CONSTEXPR14 bool is_valid() const ETL_NOEXCEPT ETL_CONSTEXPR14 operator bool() const Returns true if the delegate has been initialised, otherwise false.
ETL_CONSTEXPR14 operator =() ETL_NOEXCEPT Assigns from another delegate or lambda.
ETL_CONSTEXPR14 operator ==() ETL_NOEXCEPT ETL_CONSTEXPR14 operator !=() ETL_NOEXCEPT Compares delegates.
make_delegate For C++17 and above. 20.39.5
template constexpr auto make_delegate() noexcept Make a delegate from a free function. Returns etl::delegate<function_type>::create();
template constexpr auto make_delegate(TLambda& instance) noexcept Make a delegate from a functor or lambda function. Returns etl::delegate<function_type>(instance);
template <typename T, T& Instance> constexpr auto make_delegate() noexcept Make a delegate from a functor, compile time. Returns etl::delegate<function_type>::create<T, Instance>();
template <typename T, auto Method, T& Instance> constexpr auto make_delegate() noexcept Make a delegate from a member function at compile time. Returns etl::delegate<function_type>::create<T, Method, Instance>();
template <typename T, auto Method, const T& Instance> constexpr auto make_delegate() noexcept Make a delegate from a const member function at compile time. Returns etl::delegate<function_type>::create<T, Method, Instance>();
template <typename T, auto Method> constexpr auto make_delegate(T& instance) noexcept Make a delegate from a member function at run time. Returns etl::delegate<function_type>::create<T, Method>(instance);
template <typename T, auto Method> constexpr auto make_delegate(const T& instance) noexcept Make a delegate from a member function at run time. Returns etl::delegate<function_type>::create<T, Method>(instance);