THUAI6/CAPI/cpp/grpc/include/absl/functional/function_ref.h

// 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 invokable 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 invokable 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.
    template<typename R, typename... Args>
    class FunctionRef<R(Args...)>
    {
    private:
        // Used to disable constructors for objects that are not compatible with the
        // signature of this FunctionRef.
        template<typename F, typename FR = absl::base_internal::invoke_result_t<F, Args&&...>>
        using EnableIfCompatible =
            typename std::enable_if<std::is_void<R>::value || std::is_convertible<FR, R>::value>::type;

    public:
        // Constructs a FunctionRef from any invokable type.
        template<typename F, typename = EnableIfCompatible<const F&>>
        // NOLINTNEXTLINE(runtime/explicit)
        FunctionRef(const F& f ABSL_ATTRIBUTE_LIFETIME_BOUND) :
            invoker_(&absl::functional_internal::InvokeObject<F, R, Args...>)
        {
            absl::functional_internal::AssertNonNull(f);
            ptr_.obj = &f;
        }

        // Overload for function pointers. This eliminates a level of indirection that
        // would happen if the above overload was used (it lets us store the pointer
        // instead of a pointer to a pointer).
        //
        // This overload is also used for references to functions, since references to
        // functions can decay to function pointers implicitly.
        template<
            typename F,
            typename = EnableIfCompatible<F*>,
            absl::functional_internal::EnableIf<absl::is_function<F>::value> = 0>
        FunctionRef(F* f)  // NOLINT(runtime/explicit)
            :
            invoker_(&absl::functional_internal::InvokeFunction<F*, R, Args...>)
        {
            assert(f != nullptr);
            ptr_.fun = reinterpret_cast<decltype(ptr_.fun)>(f);
        }

        // To help prevent subtle lifetime bugs, FunctionRef is not assignable.
        // Typically, it should only be used as an argument type.
        FunctionRef& operator=(const FunctionRef& rhs) = delete;
        FunctionRef(const FunctionRef& rhs) = default;

        // Call the underlying object.
        R operator()(Args... args) const
        {
            return invoker_(ptr_, std::forward<Args>(args)...);
        }

    private:
        absl::functional_internal::VoidPtr ptr_;
        absl::functional_internal::Invoker<R, Args...> invoker_;
    };

    ABSL_NAMESPACE_END
}  // namespace absl

#endif  // ABSL_FUNCTIONAL_FUNCTION_REF_H_