// Copyright 2019 The Abseil Authors. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // ----------------------------------------------------------------------------- // File: function_ref.h // ----------------------------------------------------------------------------- // // This header file defines the `absl::FunctionRef` type for holding a // non-owning reference to an object of any invocable type. This function // reference is typically most useful as a type-erased argument type for // accepting function types that neither take ownership nor copy the type; using // the reference type in this case avoids a copy and an allocation. Best // practices of other non-owning reference-like objects (such as // `absl::string_view`) apply here. // // An `absl::FunctionRef` is similar in usage to a `std::function` but has the // following differences: // // * It doesn't own the underlying object. // * It doesn't have a null or empty state. // * It never performs deep copies or allocations. // * It's much faster and cheaper to construct. // * It's trivially copyable and destructable. // // Generally, `absl::FunctionRef` should not be used as a return value, data // member, or to initialize a `std::function`. Such usages will often lead to // problematic lifetime issues. Once you convert something to an // `absl::FunctionRef` you cannot make a deep copy later. // // This class is suitable for use wherever a "const std::function<>&" // would be used without making a copy. ForEach functions and other versions of // the visitor pattern are a good example of when this class should be used. // // This class is trivial to copy and should be passed by value. #ifndef ABSL_FUNCTIONAL_FUNCTION_REF_H_ #define ABSL_FUNCTIONAL_FUNCTION_REF_H_ #include <cassert> #include <functional> #include <type_traits> #include "absl/base/attributes.h" #include "absl/functional/internal/function_ref.h" #include "absl/meta/type_traits.h" namespace absl { ABSL_NAMESPACE_BEGIN // FunctionRef // // Dummy class declaration to allow the partial specialization based on function // types below. template <typename T> class FunctionRef; // FunctionRef // // An `absl::FunctionRef` is a lightweight wrapper to any invocable object with // a compatible signature. Generally, an `absl::FunctionRef` should only be used // as an argument type and should be preferred as an argument over a const // reference to a `std::function`. `absl::FunctionRef` itself does not allocate, // although the wrapped invocable may. // // Example: // // // The following function takes a function callback by const reference // bool Visitor(const std::function<void(my_proto&, // absl::string_view)>& callback); // // // Assuming that the function is not stored or otherwise copied, it can be // // replaced by an `absl::FunctionRef`: // bool Visitor(absl::FunctionRef<void(my_proto&, absl::string_view)> // callback); // // Note: the assignment operator within an `absl::FunctionRef` is intentionally // deleted to prevent misuse; because the `absl::FunctionRef` does not own the // underlying type, assignment likely indicates misuse. FunctionRef<R (Args...)>; // Allow const qualified function signatures. Since FunctionRef requires // constness anyway we can just make this a no-op. FunctionRef<R (Args...) const>; ABSL_NAMESPACE_END } // namespace absl #endif // ABSL_FUNCTIONAL_FUNCTION_REF_H_