4a88884b39
* Add ranges * Initial Hugo setup * Work in progress * Added selection for local or remote site * Updated to 'light' theme * Changed to using Hextra Hugo theme * Changed to using Hextra Hugo theme * Changed to Hextra Hugo theme * Change to Hextra Hugo theme * Updated Hugo setup. * Updated Hugo setup. # Conflicts: # docs/releases/_index.md * Work in progress * Added new fonts Added new documentation * Latest documentation updates * Latest documentation updates # Conflicts: # docs/containers/array.md # docs/containers/array_view.md # docs/containers/array_wrapper.md # docs/containers/bip_buffer_spsc_atomic.md # docs/containers/bitset.md # docs/containers/indirect_vector.md # docs/containers/vector.md # docs/getting-started/compilers.md * Added bloom_filter markdown doc * Added more documentation Updated CSS for light and dark modes * Fixed some menus Added mode documentation files * Updated CSS rules Added badges to home page Added uniqur_ptr + pool tutorial * Fixed formatting on the home page markdown Modified light amd dark code formatting * Updated unique_ptr-with-pool * Added container and shared message tutorials * Updates to documentation * Added const_multimap * Updated source-formatting.md * Added initial raw text files form Web site editor * Innore coverage build directory * Exported raw text documentation files from the web site editor * Hugo updates * Added Hugo intalation and markdown descriptions * More addition to the documentation * Added closure.md and updates to delegate.md * Added format.md * Added documentation for etl::delegate_observable, etl::function, Base64 codec * Added io_port documentation * Added basic_format_spec * Added documentation for string_stream and string utilities. * Added more documentation Updated the documentation CSS * Added documentation for clocks, day, duration * Added more documentation for chrono classes Updated callouts * More chrono documentation * Completed chrono documentation * Maths functions documentation * Completed maths documentation * Completed maths documentation * Completed maths documentation * Completed maths documentation * Added multiple documentation files * Added iterator.md * Added debug_count.md and versions.md * Added debug_count.md and versions.md * Added more documentation * More documentation * Added some design pattern documentation Modified some of the layout files Modified the About documentation * Converted more documentation pages Modified the site CSS * Added more documentation Moced some documentation files to new directories * Added more documentation Tweaks to CSS * Added callback_timer_deferred_locked documentation * Added callback_timer_locked documentation * More documentation updates * More documentation updates * More documentation updates * New documentation files. Harmonised file name format * New documentation files. * Multiple document updates * Multiple document updates * Final conversion of web pages * Updates before PR * Updates before PR * Updates before PR # Conflicts: # docs/blog/_index.md * Final pre PR updates * Updates to message framework documentation * Renamed directory * Fix spelling * Added author and date to blog files Moved documentation files merged from development * Fixed 'Description' typo * Fix typos # Conflicts: # docs/IO/io_port.md # docs/containers/sets/const-multiset.md # docs/containers/sets/const-set.md # docs/maths/correlation.md # docs/maths/gamma.md * Renamed two files to lower case * Minor renaming * Added author and date * Updated callout on bresenham_line.md Added support for showing the ETL version on the documentation first page, by copying the version.txt file as a hugo asset. Updated the Python 'update_release.py' to copy 'version.txt' * Replace space in filename with hyphen. Added more information to hugo-commands.md * Replace space in filename with hyphen. Added more information to hugo-commands.md # Conflicts: # docs/getting-started/view-the-docs-locally/hugo-commands.md * Added a link to pseudo_moving_average.md * Updated title pages for groups * Fixed missing 404 for non-existent pages * Fixed coordinate variable names in the 'Calculating the intersection' example --------- Co-authored-by: Roland Reichwein <Roland.Reichwein@bmw.de> Co-authored-by: John Wellbelove <john.wellbelove@etlcpp.com> Co-authored-by: John Wellbelove <john.wellbelove@etlcpp.co.uk>
9.9 KiB
| title |
|---|
| delegate |
{{< callout type="info">}}
Header: delegate.h
Since: TBC
Similar to: std::function_ref
{{< /callout >}}
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 some 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<myFunction>();
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 parameters.
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 a parameter.
>=20.42.0
etl::delegate is noexcept
>=20.47.0
A delegate can be created from a run-time global function pointer, or a non-capturing lambda.
>=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<test>();
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<global>();
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)>::create<Test::member_static>();
Global functions or non-capturing lambdas
From 20.47.0
auto d = etl::delegate<int(int)>::create(+[](int a){ return a * 2; })
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);
Types
return_type The return type of the callback.
argument_types An etl::type_list of the arguments.
Constructors
ETL_CONSTEXPR14 delegate() ETL_NOEXCEPT
Description
Constructs an uninitialised delegate.
ETL_CONSTEXPR14 delegate(const delegate& other) ETL_NOEXCEPT
Description
Copy constructs a delegate.
delegate(TReturn (*)(TArgs...) fp) ETL_NOEXCEPT
Description
Constructs from a run-time function pointer, or non-capturing lambda converted to a function pointer.
From 20.47.0
Creation
template <TReturn (*Method)(TArgs...)>
ETL_NODISCARD
static ETL_CONSTEXPR14 delegate create() ETL_NOEXCEPT
Description
Create from a global function (Compile time).
Returns
A constructed delegate.
ETL_NODISCARD
static delegate create(function_ptr fp) ETL_NOEXCEPT
Description
Create from a run-time function pointer.
From 20.47.0
Returns
A constructed delegate.
template <typename TLambda>
ETL_NODISCARD
static ETL_CONSTEXPR14 delegate create(TLambda& instance) ETL_NOEXCEPT
Description
Create from lambda or functor.
Returns
A constructed delegate.
Calling the delegate
ETL_CONSTEXPR14 TReturn operator()(TParams... args) const ETL_NOEXCEPT
Description
Calls the delegate.
constexpr from 20.42.1
20.17.0
ETL_CONSTEXPR14 bool call_if(TParams... args) const ETL_NOEXCEPT
Description
For delegates returning void.
Calls the delegate if valid.
Returns true if valid, otherwise false.
constexpr from 20.42.2
ETL_CONSTEXPR14 etl::optional<TReturn> call_if(TParams... args) const ETL_NOEXCEPT
Description
For delegates returning TReturn.
Calls the delegate if valid.
Returns a valid etl::optional<TReturn> containing the return value, if valid.
constexpr from 20.42.2
20.17.0
template <typename TAlternative>
ETL_CONSTEXPR14 TReturn call_or(TAlternative alternative, TParams... args) const ETL_NOEXCEPT
Description
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
Description
Calls the delegate if valid, otherwise calls Method.
Modifiers
void clear() ETL_NOEXCEPT
Description
Sets the delegate back to the uninitialised state.
Status
ETL_NODISCARD ETL_CONSTEXPR14 bool is_valid() const ETL_NOEXCEPT
ETL_CONSTEXPR14 operator bool() const
Description
Returns true if the delegate has been initialised, otherwise false.
ETL_CONSTEXPR14 operator =() ETL_NOEXCEPT
Description
Assigns from a delegate or lambda.
ETL_CONSTEXPR14 operator ==() ETL_NOEXCEPT
ETL_CONSTEXPR14 operator !=() ETL_NOEXCEPT
Description
Compares delegates.
Make a delegate
make_delegate
Description
For C++17 and above.
20.39.5
template <auto Function>
constexpr auto make_delegate() noexcept
Description
Make a delegate from a free function.
Returns etl::delegate<function_type>::create<Function>()
template <typename TLambda>
constexpr auto make_delegate(TLambda& instance) noexcept
Description
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
Description
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
Description
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
Description
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
Description
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
Description
Make a delegate from a member function at run time.
Returns etl::delegate<function_type>::create<T, Method>(instance)