// Copyright (c) 2011 The Chromium Authors. All rights reserved. // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. #ifndef BASE_BIND_INTERNAL_H_ #define BASE_BIND_INTERNAL_H_ #include #include #include #include "base/callback_internal.h" #include "base/memory/raw_scoped_refptr_mismatch_checker.h" #include "base/memory/weak_ptr.h" #include "base/template_util.h" #include "util/build_config.h" // See base/callback.h for user documentation. // // // CONCEPTS: // Functor -- A movable type representing something that should be called. // All function pointers and Callback<> are functors even if the // invocation syntax differs. // RunType -- A function type (as opposed to function _pointer_ type) for // a Callback<>::Run(). Usually just a convenience typedef. // (Bound)Args -- A set of types that stores the arguments. // // Types: // ForceVoidReturn<> -- Helper class for translating function signatures to // equivalent forms with a "void" return type. // FunctorTraits<> -- Type traits used to determine the correct RunType and // invocation manner for a Functor. This is where function // signature adapters are applied. // InvokeHelper<> -- Take a Functor + arguments and actully invokes it. // Handle the differing syntaxes needed for WeakPtr<> // support. This is separate from Invoker to avoid creating // multiple version of Invoker<>. // Invoker<> -- Unwraps the curried parameters and executes the Functor. // BindState<> -- Stores the curried parameters, and is the main entry point // into the Bind() system. namespace base { template struct IsWeakReceiver; template struct BindUnwrapTraits; template struct CallbackCancellationTraits; namespace internal { template struct FunctorTraits; template class UnretainedWrapper { public: explicit UnretainedWrapper(T* o) : ptr_(o) {} T* get() const { return ptr_; } private: T* ptr_; }; template class ConstRefWrapper { public: explicit ConstRefWrapper(const T& o) : ptr_(&o) {} const T& get() const { return *ptr_; } private: const T* ptr_; }; template class RetainedRefWrapper { public: explicit RetainedRefWrapper(T* o) : ptr_(o) {} explicit RetainedRefWrapper(scoped_refptr o) : ptr_(std::move(o)) {} T* get() const { return ptr_.get(); } private: scoped_refptr ptr_; }; template struct IgnoreResultHelper { explicit IgnoreResultHelper(T functor) : functor_(std::move(functor)) {} explicit operator bool() const { return !!functor_; } T functor_; }; // An alternate implementation is to avoid the destructive copy, and instead // specialize ParamTraits<> for OwnedWrapper<> to change the StorageType to // a class that is essentially a std::unique_ptr<>. // // The current implementation has the benefit though of leaving ParamTraits<> // fully in callback_internal.h as well as avoiding type conversions during // storage. template class OwnedWrapper { public: explicit OwnedWrapper(T* o) : ptr_(o) {} ~OwnedWrapper() { delete ptr_; } T* get() const { return ptr_; } OwnedWrapper(OwnedWrapper&& other) { ptr_ = other.ptr_; other.ptr_ = NULL; } private: mutable T* ptr_; }; // PassedWrapper is a copyable adapter for a scoper that ignores const. // // It is needed to get around the fact that Bind() takes a const reference to // all its arguments. Because Bind() takes a const reference to avoid // unnecessary copies, it is incompatible with movable-but-not-copyable // types; doing a destructive "move" of the type into Bind() would violate // the const correctness. // // This conundrum cannot be solved without either C++11 rvalue references or // a O(2^n) blowup of Bind() templates to handle each combination of regular // types and movable-but-not-copyable types. Thus we introduce a wrapper type // that is copyable to transmit the correct type information down into // BindState<>. Ignoring const in this type makes sense because it is only // created when we are explicitly trying to do a destructive move. // // Two notes: // 1) PassedWrapper supports any type that has a move constructor, however // the type will need to be specifically whitelisted in order for it to be // bound to a Callback. We guard this explicitly at the call of Passed() // to make for clear errors. Things not given to Passed() will be forwarded // and stored by value which will not work for general move-only types. // 2) is_valid_ is distinct from NULL because it is valid to bind a "NULL" // scoper to a Callback and allow the Callback to execute once. template class PassedWrapper { public: explicit PassedWrapper(T&& scoper) : is_valid_(true), scoper_(std::move(scoper)) {} PassedWrapper(PassedWrapper&& other) : is_valid_(other.is_valid_), scoper_(std::move(other.scoper_)) {} T Take() const { CHECK(is_valid_); is_valid_ = false; return std::move(scoper_); } private: mutable bool is_valid_; mutable T scoper_; }; template using Unwrapper = BindUnwrapTraits>; template decltype(auto) Unwrap(T&& o) { return Unwrapper::Unwrap(std::forward(o)); } // IsWeakMethod is a helper that determine if we are binding a WeakPtr<> to a // method. It is used internally by Bind() to select the correct // InvokeHelper that will no-op itself in the event the WeakPtr<> for // the target object is invalidated. // // The first argument should be the type of the object that will be received by // the method. template struct IsWeakMethod : std::false_type {}; template struct IsWeakMethod : IsWeakReceiver {}; // Packs a list of types to hold them in a single type. template struct TypeList {}; // Used for DropTypeListItem implementation. template struct DropTypeListItemImpl; // Do not use enable_if and SFINAE here to avoid MSVC2013 compile failure. template struct DropTypeListItemImpl> : DropTypeListItemImpl> {}; template struct DropTypeListItemImpl<0, TypeList> { using Type = TypeList; }; template <> struct DropTypeListItemImpl<0, TypeList<>> { using Type = TypeList<>; }; // A type-level function that drops |n| list item from given TypeList. template using DropTypeListItem = typename DropTypeListItemImpl::Type; // Used for TakeTypeListItem implementation. template struct TakeTypeListItemImpl; // Do not use enable_if and SFINAE here to avoid MSVC2013 compile failure. template struct TakeTypeListItemImpl, Accum...> : TakeTypeListItemImpl, Accum..., T> {}; template struct TakeTypeListItemImpl<0, TypeList, Accum...> { using Type = TypeList; }; template struct TakeTypeListItemImpl<0, TypeList<>, Accum...> { using Type = TypeList; }; // A type-level function that takes first |n| list item from given TypeList. // E.g. TakeTypeListItem<3, TypeList> is evaluated to // TypeList. template using TakeTypeListItem = typename TakeTypeListItemImpl::Type; // Used for ConcatTypeLists implementation. template struct ConcatTypeListsImpl; template struct ConcatTypeListsImpl, TypeList> { using Type = TypeList; }; // A type-level function that concats two TypeLists. template using ConcatTypeLists = typename ConcatTypeListsImpl::Type; // Used for MakeFunctionType implementation. template struct MakeFunctionTypeImpl; template struct MakeFunctionTypeImpl> { // MSVC 2013 doesn't support Type Alias of function types. // Revisit this after we update it to newer version. typedef R Type(Args...); }; // A type-level function that constructs a function type that has |R| as its // return type and has TypeLists items as its arguments. template using MakeFunctionType = typename MakeFunctionTypeImpl::Type; // Used for ExtractArgs and ExtractReturnType. template struct ExtractArgsImpl; template struct ExtractArgsImpl { using ReturnType = R; using ArgsList = TypeList; }; // A type-level function that extracts function arguments into a TypeList. // E.g. ExtractArgs is evaluated to TypeList. template using ExtractArgs = typename ExtractArgsImpl::ArgsList; // A type-level function that extracts the return type of a function. // E.g. ExtractReturnType is evaluated to R. template using ExtractReturnType = typename ExtractArgsImpl::ReturnType; template struct ExtractCallableRunTypeImpl; template struct ExtractCallableRunTypeImpl { using Type = R(Args...); }; template struct ExtractCallableRunTypeImpl { using Type = R(Args...); }; // Evaluated to RunType of the given callable type. // Example: // auto f = [](int, char*) { return 0.1; }; // ExtractCallableRunType // is evaluated to // double(int, char*); template using ExtractCallableRunType = typename ExtractCallableRunTypeImpl::Type; // IsCallableObject is std::true_type if |Functor| has operator(). // Otherwise, it's std::false_type. // Example: // IsCallableObject::value is false. // // struct Foo {}; // IsCallableObject::value is false. // // int i = 0; // auto f = [i]() {}; // IsCallableObject::value is false. template struct IsCallableObject : std::false_type {}; template struct IsCallableObject> : std::true_type {}; // HasRefCountedTypeAsRawPtr selects true_type when any of the |Args| is a raw // pointer to a RefCounted type. // Implementation note: This non-specialized case handles zero-arity case only. // Non-zero-arity cases should be handled by the specialization below. template struct HasRefCountedTypeAsRawPtr : std::false_type {}; // Implementation note: Select true_type if the first parameter is a raw pointer // to a RefCounted type. Otherwise, skip the first parameter and check rest of // parameters recursively. template struct HasRefCountedTypeAsRawPtr : std::conditional_t::value, std::true_type, HasRefCountedTypeAsRawPtr> {}; // ForceVoidReturn<> // // Set of templates that support forcing the function return type to void. template struct ForceVoidReturn; template struct ForceVoidReturn { using RunType = void(Args...); }; // FunctorTraits<> // // See description at top of file. template struct FunctorTraits; // For empty callable types. // This specialization is intended to allow binding captureless lambdas by // base::Bind(), based on the fact that captureless lambdas are empty while // capturing lambdas are not. This also allows any functors as far as it's an // empty class. // Example: // // // Captureless lambdas are allowed. // []() {return 42;}; // // // Capturing lambdas are *not* allowed. // int x; // [x]() {return x;}; // // // Any empty class with operator() is allowed. // struct Foo { // void operator()() const {} // // No non-static member variable and no virtual functions. // }; template struct FunctorTraits::value && std::is_empty::value>> { using RunType = ExtractCallableRunType; static constexpr bool is_method = false; static constexpr bool is_nullable = false; template static ExtractReturnType Invoke(RunFunctor&& functor, RunArgs&&... args) { return std::forward(functor)(std::forward(args)...); } }; // For functions. template struct FunctorTraits { using RunType = R(Args...); static constexpr bool is_method = false; static constexpr bool is_nullable = true; template static R Invoke(Function&& function, RunArgs&&... args) { return std::forward(function)(std::forward(args)...); } }; #if defined(OS_WIN) && !defined(ARCH_CPU_X86_64) // For functions. template struct FunctorTraits { using RunType = R(Args...); static constexpr bool is_method = false; static constexpr bool is_nullable = true; template static R Invoke(R(__stdcall* function)(Args...), RunArgs&&... args) { return function(std::forward(args)...); } }; // For functions. template struct FunctorTraits { using RunType = R(Args...); static constexpr bool is_method = false; static constexpr bool is_nullable = true; template static R Invoke(R(__fastcall* function)(Args...), RunArgs&&... args) { return function(std::forward(args)...); } }; #endif // defined(OS_WIN) && !defined(ARCH_CPU_X86_64) // For methods. template struct FunctorTraits { using RunType = R(Receiver*, Args...); static constexpr bool is_method = true; static constexpr bool is_nullable = true; template static R Invoke(Method method, ReceiverPtr&& receiver_ptr, RunArgs&&... args) { return ((*receiver_ptr).*method)(std::forward(args)...); } }; // For const methods. template struct FunctorTraits { using RunType = R(const Receiver*, Args...); static constexpr bool is_method = true; static constexpr bool is_nullable = true; template static R Invoke(Method method, ReceiverPtr&& receiver_ptr, RunArgs&&... args) { return ((*receiver_ptr).*method)(std::forward(args)...); } }; #ifdef __cpp_noexcept_function_type // noexcept makes a distinct function type in C++17. // I.e. `void(*)()` and `void(*)() noexcept` are same in pre-C++17, and // different in C++17. template struct FunctorTraits : FunctorTraits { }; template struct FunctorTraits : FunctorTraits {}; template struct FunctorTraits : FunctorTraits {}; #endif // For IgnoreResults. template struct FunctorTraits> : FunctorTraits { using RunType = typename ForceVoidReturn::RunType>::RunType; template static void Invoke(IgnoreResultType&& ignore_result_helper, RunArgs&&... args) { FunctorTraits::Invoke( std::forward(ignore_result_helper).functor_, std::forward(args)...); } }; // For OnceCallbacks. template struct FunctorTraits> { using RunType = R(Args...); static constexpr bool is_method = false; static constexpr bool is_nullable = true; template static R Invoke(CallbackType&& callback, RunArgs&&... args) { DCHECK(!callback.is_null()); return std::forward(callback).Run( std::forward(args)...); } }; // For RepeatingCallbacks. template struct FunctorTraits> { using RunType = R(Args...); static constexpr bool is_method = false; static constexpr bool is_nullable = true; template static R Invoke(CallbackType&& callback, RunArgs&&... args) { DCHECK(!callback.is_null()); return std::forward(callback).Run( std::forward(args)...); } }; template using MakeFunctorTraits = FunctorTraits>; // InvokeHelper<> // // There are 2 logical InvokeHelper<> specializations: normal, WeakCalls. // // The normal type just calls the underlying runnable. // // WeakCalls need special syntax that is applied to the first argument to check // if they should no-op themselves. template struct InvokeHelper; template struct InvokeHelper { template static inline ReturnType MakeItSo(Functor&& functor, RunArgs&&... args) { using Traits = MakeFunctorTraits; return Traits::Invoke(std::forward(functor), std::forward(args)...); } }; template struct InvokeHelper { // WeakCalls are only supported for functions with a void return type. // Otherwise, the function result would be undefined if the the WeakPtr<> // is invalidated. static_assert(std::is_void::value, "weak_ptrs can only bind to methods without return values"); template static inline void MakeItSo(Functor&& functor, BoundWeakPtr&& weak_ptr, RunArgs&&... args) { if (!weak_ptr) return; using Traits = MakeFunctorTraits; Traits::Invoke(std::forward(functor), std::forward(weak_ptr), std::forward(args)...); } }; // Invoker<> // // See description at the top of the file. template struct Invoker; template struct Invoker { static R RunOnce(BindStateBase* base, PassingTraitsType... unbound_args) { // Local references to make debugger stepping easier. If in a debugger, // you really want to warp ahead and step through the // InvokeHelper<>::MakeItSo() call below. StorageType* storage = static_cast(base); static constexpr size_t num_bound_args = std::tuple_sizebound_args_)>::value; return RunImpl(std::move(storage->functor_), std::move(storage->bound_args_), std::make_index_sequence(), std::forward(unbound_args)...); } static R Run(BindStateBase* base, PassingTraitsType... unbound_args) { // Local references to make debugger stepping easier. If in a debugger, // you really want to warp ahead and step through the // InvokeHelper<>::MakeItSo() call below. const StorageType* storage = static_cast(base); static constexpr size_t num_bound_args = std::tuple_sizebound_args_)>::value; return RunImpl(storage->functor_, storage->bound_args_, std::make_index_sequence(), std::forward(unbound_args)...); } private: template static inline R RunImpl(Functor&& functor, BoundArgsTuple&& bound, std::index_sequence, UnboundArgs&&... unbound_args) { static constexpr bool is_method = MakeFunctorTraits::is_method; using DecayedArgsTuple = std::decay_t; static constexpr bool is_weak_call = IsWeakMethod...>(); return InvokeHelper::MakeItSo( std::forward(functor), Unwrap(std::get(std::forward(bound)))..., std::forward(unbound_args)...); } }; // Extracts necessary type info from Functor and BoundArgs. // Used to implement MakeUnboundRunType, BindOnce and BindRepeating. template struct BindTypeHelper { static constexpr size_t num_bounds = sizeof...(BoundArgs); using FunctorTraits = MakeFunctorTraits; // Example: // When Functor is `double (Foo::*)(int, const std::string&)`, and BoundArgs // is a template pack of `Foo*` and `int16_t`: // - RunType is `double(Foo*, int, const std::string&)`, // - ReturnType is `double`, // - RunParamsList is `TypeList`, // - BoundParamsList is `TypeList`, // - UnboundParamsList is `TypeList`, // - BoundArgsList is `TypeList`, // - UnboundRunType is `double(const std::string&)`. using RunType = typename FunctorTraits::RunType; using ReturnType = ExtractReturnType; using RunParamsList = ExtractArgs; using BoundParamsList = TakeTypeListItem; using UnboundParamsList = DropTypeListItem; using BoundArgsList = TypeList; using UnboundRunType = MakeFunctionType; }; template std::enable_if_t::is_nullable, bool> IsNull( const Functor& functor) { return !functor; } template std::enable_if_t::is_nullable, bool> IsNull( const Functor&) { return false; } // Used by ApplyCancellationTraits below. template bool ApplyCancellationTraitsImpl(const Functor& functor, const BoundArgsTuple& bound_args, std::index_sequence) { return CallbackCancellationTraits::IsCancelled( functor, std::get(bound_args)...); } // Relays |base| to corresponding CallbackCancellationTraits<>::Run(). Returns // true if the callback |base| represents is canceled. template bool ApplyCancellationTraits(const BindStateBase* base) { const BindStateType* storage = static_cast(base); static constexpr size_t num_bound_args = std::tuple_sizebound_args_)>::value; return ApplyCancellationTraitsImpl( storage->functor_, storage->bound_args_, std::make_index_sequence()); }; // BindState<> // // This stores all the state passed into Bind(). template struct BindState final : BindStateBase { using IsCancellable = std::integral_constant< bool, CallbackCancellationTraits>::is_cancellable>; template explicit BindState(BindStateBase::InvokeFuncStorage invoke_func, ForwardFunctor&& functor, ForwardBoundArgs&&... bound_args) // IsCancellable is std::false_type if // CallbackCancellationTraits<>::IsCancelled returns always false. // Otherwise, it's std::true_type. : BindState(IsCancellable{}, invoke_func, std::forward(functor), std::forward(bound_args)...) {} Functor functor_; std::tuple bound_args_; private: template explicit BindState(std::true_type, BindStateBase::InvokeFuncStorage invoke_func, ForwardFunctor&& functor, ForwardBoundArgs&&... bound_args) : BindStateBase(invoke_func, &Destroy, &ApplyCancellationTraits), functor_(std::forward(functor)), bound_args_(std::forward(bound_args)...) { DCHECK(!IsNull(functor_)); } template explicit BindState(std::false_type, BindStateBase::InvokeFuncStorage invoke_func, ForwardFunctor&& functor, ForwardBoundArgs&&... bound_args) : BindStateBase(invoke_func, &Destroy), functor_(std::forward(functor)), bound_args_(std::forward(bound_args)...) { DCHECK(!IsNull(functor_)); } ~BindState() = default; static void Destroy(const BindStateBase* self) { delete static_cast(self); } }; // Used to implement MakeBindStateType. template struct MakeBindStateTypeImpl; template struct MakeBindStateTypeImpl { static_assert(!HasRefCountedTypeAsRawPtr...>::value, "A parameter is a refcounted type and needs scoped_refptr."); using Type = BindState, std::decay_t...>; }; template struct MakeBindStateTypeImpl { using Type = BindState>; }; template struct MakeBindStateTypeImpl { private: using DecayedReceiver = std::decay_t; static_assert(!std::is_array>::value, "First bound argument to a method cannot be an array."); static_assert( !std::is_pointer::value || IsRefCountedType>::value, "Receivers may not be raw pointers. If using a raw pointer here is safe" " and has no lifetime concerns, use base::Unretained() and document why" " it's safe."); static_assert(!HasRefCountedTypeAsRawPtr...>::value, "A parameter is a refcounted type and needs scoped_refptr."); public: using Type = BindState< std::decay_t, std::conditional_t::value, scoped_refptr>, DecayedReceiver>, std::decay_t...>; }; template using MakeBindStateType = typename MakeBindStateTypeImpl::is_method, Functor, BoundArgs...>::Type; } // namespace internal // An injection point to control |this| pointer behavior on a method invocation. // If IsWeakReceiver<> is true_type for |T| and |T| is used for a receiver of a // method, base::Bind cancels the method invocation if the receiver is tested as // false. // E.g. Foo::bar() is not called: // struct Foo : base::SupportsWeakPtr { // void bar() {} // }; // // WeakPtr oo = nullptr; // base::Bind(&Foo::bar, oo).Run(); template struct IsWeakReceiver : std::false_type {}; template struct IsWeakReceiver> : IsWeakReceiver {}; template struct IsWeakReceiver> : std::true_type {}; // An injection point to control how bound objects passed to the target // function. BindUnwrapTraits<>::Unwrap() is called for each bound objects right // before the target function is invoked. template struct BindUnwrapTraits { template static T&& Unwrap(T&& o) { return std::forward(o); } }; template struct BindUnwrapTraits> { static T* Unwrap(const internal::UnretainedWrapper& o) { return o.get(); } }; template struct BindUnwrapTraits> { static const T& Unwrap(const internal::ConstRefWrapper& o) { return o.get(); } }; template struct BindUnwrapTraits> { static T* Unwrap(const internal::RetainedRefWrapper& o) { return o.get(); } }; template struct BindUnwrapTraits> { static T* Unwrap(const internal::OwnedWrapper& o) { return o.get(); } }; template struct BindUnwrapTraits> { static T Unwrap(const internal::PassedWrapper& o) { return o.Take(); } }; // CallbackCancellationTraits allows customization of Callback's cancellation // semantics. By default, callbacks are not cancellable. A specialization should // set is_cancellable = true and implement an IsCancelled() that returns if the // callback should be cancelled. template struct CallbackCancellationTraits { static constexpr bool is_cancellable = false; }; // Specialization for method bound to weak pointer receiver. template struct CallbackCancellationTraits< Functor, std::tuple, std::enable_if_t< internal::IsWeakMethod::is_method, BoundArgs...>::value>> { static constexpr bool is_cancellable = true; template static bool IsCancelled(const Functor&, const Receiver& receiver, const Args&...) { return !receiver; } }; // Specialization for a nested bind. template struct CallbackCancellationTraits, std::tuple> { static constexpr bool is_cancellable = true; template static bool IsCancelled(const Functor& functor, const BoundArgs&...) { return functor.IsCancelled(); } }; template struct CallbackCancellationTraits, std::tuple> { static constexpr bool is_cancellable = true; template static bool IsCancelled(const Functor& functor, const BoundArgs&...) { return functor.IsCancelled(); } }; // Returns a RunType of bound functor. // E.g. MakeUnboundRunType is evaluated to R(C). template using MakeUnboundRunType = typename internal::BindTypeHelper::UnboundRunType; } // namespace base #endif // BASE_BIND_INTERNAL_H_