1 // Copyright 2021 The Pigweed Authors
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
4 // use this file except in compliance with the License. You may obtain a copy of
5 // the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12 // License for the specific language governing permissions and limitations under
13 // the License.
14 #pragma once
15
16 #include <cstddef>
17
18 #include "lib/fit/function.h"
19 #include "pw_function/config.h"
20
21 namespace pw {
22
23 /// `pw::Function` is a wrapper for an arbitrary callable object. It can be used
24 /// by callback-based APIs to allow callers to provide any type of callable.
25 ///
26 /// Example:
27 /// @code{.cpp}
28 ///
29 /// template <typename T>
30 /// bool All(const pw::Vector<T>& items,
31 /// const pw::Function<bool(const T& item)>& predicate) {
32 /// for (const T& item : items) {
33 /// if (!predicate(item)) {
34 /// return false;
35 /// }
36 /// }
37 /// return true;
38 /// }
39 ///
40 /// bool ElementsArePositive(const pw::Vector<int>& items) {
41 /// return All(items, [](const int& i) { return i > 0; });
42 /// }
43 ///
44 /// bool IsEven(const int& i) { return i % 2 == 0; }
45 ///
46 /// bool ElementsAreEven(const pw::Vector<int>& items) {
47 /// return All(items, IsEven);
48 /// }
49 ///
50 /// @endcode
51 ///
52 /// @tparam Allocator The Allocator used to dynamically allocate the callable,
53 /// if it exceeds `inline_target_size` and dynamic allocation is enabled. Its
54 /// `value_type` is irrelevant, since it must support rebinding.
55 template <typename FunctionType,
56 std::size_t inline_target_size =
57 function_internal::config::kInlineCallableSize,
58 typename Allocator = PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE>
59 using Function = fit::function_impl<
60 inline_target_size,
61 /*require_inline=*/!function_internal::config::kEnableDynamicAllocation,
62 FunctionType,
63 Allocator>;
64
65 /// Version of `pw::Function` that exclusively uses inline storage.
66 ///
67 /// IMPORTANT: If `pw::Function` is configured to allow dynamic allocations then
68 /// any attempt to convert `pw::InlineFunction` to `pw::Function` will ALWAYS
69 /// allocate.
70 ///
71 // TODO: b/252852651 - Remove warning above when conversion from
72 // `fit::inline_function` to `fit::function` doesn't allocate anymore.
73 template <typename FunctionType,
74 std::size_t inline_target_size =
75 function_internal::config::kInlineCallableSize>
76 using InlineFunction = fit::inline_function<FunctionType, inline_target_size>;
77
78 using Closure = Function<void()>;
79
80 /// `pw::Callback` is identical to @cpp_type{pw::Function} except:
81 ///
82 /// 1. On the first call to invoke a `pw::Callback`, the target function held
83 /// by the `pw::Callback` cannot be called again.
84 /// 2. When a `pw::Callback` is invoked for the first time, the target function
85 /// is released and destructed, along with any resources owned by that
86 /// function (typically the objects captured by a lambda).
87 ///
88 /// A `pw::Callback` in the "already called" state has the same state as a
89 /// `pw::Callback` that has been assigned to `nullptr`.
90 template <typename FunctionType,
91 std::size_t inline_target_size =
92 function_internal::config::kInlineCallableSize,
93 typename Allocator = PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE>
94 using Callback = fit::callback_impl<
95 inline_target_size,
96 /*require_inline=*/!function_internal::config::kEnableDynamicAllocation,
97 FunctionType,
98 Allocator>;
99
100 /// Version of `pw::Callback` that exclusively uses inline storage.
101 template <typename FunctionType,
102 std::size_t inline_target_size =
103 function_internal::config::kInlineCallableSize>
104 using InlineCallback = fit::inline_callback<FunctionType, inline_target_size>;
105
106 /// Returns a `Callable` which, when called, invokes `method` on `instance`
107 /// using the arguments provided.
108 ///
109 /// This is useful for binding the `this` argument of a callable.
110 ///
111 /// `pw::bind_member<&T::MethodName>(instance)` is roughly equivalent to
112 /// `[instance](Arg arg1, ...) { instance->MethodName(arg1, ...) }`, albeit with
113 /// proper support for overloads and argument forwarding.
114 template <auto method, typename T>
bind_member(T * instance)115 auto bind_member(T* instance) {
116 return fit::bind_member<method, T>(instance);
117 }
118
119 } // namespace pw
120