1 // Copyright 2019 The Abseil Authors.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of 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,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 //
15 // -----------------------------------------------------------------------------
16 // File: function_ref.h
17 // -----------------------------------------------------------------------------
18 //
19 // This header file defines the `absl::FunctionRef` type for holding a
20 // non-owning reference to an object of any invocable type. This function
21 // reference is typically most useful as a type-erased argument type for
22 // accepting function types that neither take ownership nor copy the type; using
23 // the reference type in this case avoids a copy and an allocation. Best
24 // practices of other non-owning reference-like objects (such as
25 // `absl::string_view`) apply here.
26 //
27 //  An `absl::FunctionRef` is similar in usage to a `std::function` but has the
28 //  following differences:
29 //
30 //  * It doesn't own the underlying object.
31 //  * It doesn't have a null or empty state.
32 //  * It never performs deep copies or allocations.
33 //  * It's much faster and cheaper to construct.
34 //  * It's trivially copyable and destructable.
35 //
36 // Generally, `absl::FunctionRef` should not be used as a return value, data
37 // member, or to initialize a `std::function`. Such usages will often lead to
38 // problematic lifetime issues. Once you convert something to an
39 // `absl::FunctionRef` you cannot make a deep copy later.
40 //
41 // This class is suitable for use wherever a "const std::function<>&"
42 // would be used without making a copy. ForEach functions and other versions of
43 // the visitor pattern are a good example of when this class should be used.
44 //
45 // This class is trivial to copy and should be passed by value.
46 #ifndef ABSL_FUNCTIONAL_FUNCTION_REF_H_
47 #define ABSL_FUNCTIONAL_FUNCTION_REF_H_
48 
49 #include <cassert>
50 #include <functional>
51 #include <type_traits>
52 
53 #include "absl/functional/internal/function_ref.h"
54 #include "absl/meta/type_traits.h"
55 
56 namespace absl {
57 ABSL_NAMESPACE_BEGIN
58 
59 // FunctionRef
60 //
61 // Dummy class declaration to allow the partial specialization based on function
62 // types below.
63 template <typename T>
64 class FunctionRef;
65 
66 // FunctionRef
67 //
68 // An `absl::FunctionRef` is a lightweight wrapper to any invokable object with
69 // a compatible signature. Generally, an `absl::FunctionRef` should only be used
70 // as an argument type and should be preferred as an argument over a const
71 // reference to a `std::function`.
72 //
73 // Example:
74 //
75 //   // The following function takes a function callback by const reference
76 //   bool Visitor(const std::function<void(my_proto&,
77 //                                         absl::string_view)>& callback);
78 //
79 //   // Assuming that the function is not stored or otherwise copied, it can be
80 //   // replaced by an `absl::FunctionRef`:
81 //   bool Visitor(absl::FunctionRef<void(my_proto&, absl::string_view)>
82 //                  callback);
83 //
84 // Note: the assignment operator within an `absl::FunctionRef` is intentionally
85 // deleted to prevent misuse; because the `absl::FunctionRef` does not own the
86 // underlying type, assignment likely indicates misuse.
87 template <typename R, typename... Args>
88 class FunctionRef<R(Args...)> {
89  private:
90   // Used to disable constructors for objects that are not compatible with the
91   // signature of this FunctionRef.
92   template <typename F,
93             typename FR = absl::base_internal::InvokeT<F, Args&&...>>
94   using EnableIfCompatible =
95       typename std::enable_if<std::is_void<R>::value ||
96                               std::is_convertible<FR, R>::value>::type;
97 
98  public:
99   // Constructs a FunctionRef from any invokable type.
100   template <typename F, typename = EnableIfCompatible<const F&>>
FunctionRef(const F & f)101   FunctionRef(const F& f)  // NOLINT(runtime/explicit)
102       : invoker_(&absl::functional_internal::InvokeObject<F, R, Args...>) {
103     absl::functional_internal::AssertNonNull(f);
104     ptr_.obj = &f;
105   }
106 
107   // Overload for function pointers. This eliminates a level of indirection that
108   // would happen if the above overload was used (it lets us store the pointer
109   // instead of a pointer to a pointer).
110   //
111   // This overload is also used for references to functions, since references to
112   // functions can decay to function pointers implicitly.
113   template <
114       typename F, typename = EnableIfCompatible<F*>,
115       absl::functional_internal::EnableIf<absl::is_function<F>::value> = 0>
FunctionRef(F * f)116   FunctionRef(F* f)  // NOLINT(runtime/explicit)
117       : invoker_(&absl::functional_internal::InvokeFunction<F*, R, Args...>) {
118     assert(f != nullptr);
119     ptr_.fun = reinterpret_cast<decltype(ptr_.fun)>(f);
120   }
121 
122   // To help prevent subtle lifetime bugs, FunctionRef is not assignable.
123   // Typically, it should only be used as an argument type.
124   FunctionRef& operator=(const FunctionRef& rhs) = delete;
125 
126   // Call the underlying object.
operator()127   R operator()(Args... args) const {
128     return invoker_(ptr_, std::forward<Args>(args)...);
129   }
130 
131  private:
132   absl::functional_internal::VoidPtr ptr_;
133   absl::functional_internal::Invoker<R, Args...> invoker_;
134 };
135 
136 ABSL_NAMESPACE_END
137 }  // namespace absl
138 
139 #endif  // ABSL_FUNCTIONAL_FUNCTION_REF_H_
140