1 /* 2 * Copyright 2016-present Facebook, Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 /* 17 * @author Eric Niebler (eniebler@fb.com), Sven Over (over@fb.com) 18 * Acknowledgements: Giuseppe Ottaviano (ott@fb.com) 19 */ 20 21 /** 22 * @class Function 23 * 24 * @brief A polymorphic function wrapper that is not copyable and does not 25 * require the wrapped function to be copy constructible. 26 * 27 * `folly::Function` is a polymorphic function wrapper, similar to 28 * `std::function`. The template parameters of the `folly::Function` define 29 * the parameter signature of the wrapped callable, but not the specific 30 * type of the embedded callable. E.g. a `folly::Function<int(int)>` 31 * can wrap callables that return an `int` when passed an `int`. This can be a 32 * function pointer or any class object implementing one or both of 33 * 34 * int operator(int); 35 * int operator(int) const; 36 * 37 * If both are defined, the non-const one takes precedence. 38 * 39 * Unlike `std::function`, a `folly::Function` can wrap objects that are not 40 * copy constructible. As a consequence of this, `folly::Function` itself 41 * is not copyable, either. 42 * 43 * Another difference is that, unlike `std::function`, `folly::Function` treats 44 * const-ness of methods correctly. While a `std::function` allows to wrap 45 * an object that only implements a non-const `operator()` and invoke 46 * a const-reference of the `std::function`, `folly::Function` requires you to 47 * declare a function type as const in order to be able to execute it on a 48 * const-reference. 49 * 50 * For example: 51 * 52 * class Foo { 53 * public: 54 * void operator()() { 55 * // mutates the Foo object 56 * } 57 * }; 58 * 59 * class Bar { 60 * std::function<void(void)> foo_; // wraps a Foo object 61 * public: 62 * void mutateFoo() const 63 * { 64 * foo_(); 65 * } 66 * }; 67 * 68 * Even though `mutateFoo` is a const-method, so it can only reference `foo_` 69 * as const, it is able to call the non-const `operator()` of the Foo 70 * object that is embedded in the foo_ function. 71 * 72 * `folly::Function` will not allow you to do that. You will have to decide 73 * whether you need to invoke your wrapped callable from a const reference 74 * (like in the example above), in which case it will only wrap a 75 * `operator() const`. If your functor does not implement that, 76 * compilation will fail. If you do not require to be able to invoke the 77 * wrapped function in a const context, you can wrap any functor that 78 * implements either or both of const and non-const `operator()`. 79 * 80 * The template parameter of `folly::Function`, the `FunctionType`, can be 81 * const-qualified. Be aware that the const is part of the function signature. 82 * It does not mean that the function type is a const type. 83 * 84 * using FunctionType = R(Args...); 85 * using ConstFunctionType = R(Args...) const; 86 * 87 * In this example, `FunctionType` and `ConstFunctionType` are different 88 * types. `ConstFunctionType` is not the same as `const FunctionType`. 89 * As a matter of fact, trying to use the latter should emit a compiler 90 * warning or error, because it has no defined meaning. 91 * 92 * // This will not compile: 93 * folly::Function<void(void) const> func = Foo(); 94 * // because Foo does not have a member function of the form: 95 * // void operator()() const; 96 * 97 * // This will compile just fine: 98 * folly::Function<void(void)> func = Foo(); 99 * // and it will wrap the existing member function: 100 * // void operator()(); 101 * 102 * When should a const function type be used? As a matter of fact, you will 103 * probably not need to use const function types very often. See the following 104 * example: 105 * 106 * class Bar { 107 * folly::Function<void()> func_; 108 * folly::Function<void() const> constFunc_; 109 * 110 * void someMethod() { 111 * // Can call func_. 112 * func_(); 113 * // Can call constFunc_. 114 * constFunc_(); 115 * } 116 * 117 * void someConstMethod() const { 118 * // Can call constFunc_. 119 * constFunc_(); 120 * // However, cannot call func_ because a non-const method cannot 121 * // be called from a const one. 122 * } 123 * }; 124 * 125 * As you can see, whether the `folly::Function`'s function type should 126 * be declared const or not is identical to whether a corresponding method 127 * would be declared const or not. 128 * 129 * You only require a `folly::Function` to hold a const function type, if you 130 * intend to invoke it from within a const context. This is to ensure that 131 * you cannot mutate its inner state when calling in a const context. 132 * 133 * This is how the const/non-const choice relates to lambda functions: 134 * 135 * // Non-mutable lambdas: can be stored in a non-const... 136 * folly::Function<void(int)> print_number = 137 * [] (int number) { std::cout << number << std::endl; }; 138 * 139 * // ...as well as in a const folly::Function 140 * folly::Function<void(int) const> print_number_const = 141 * [] (int number) { std::cout << number << std::endl; }; 142 * 143 * // Mutable lambda: can only be stored in a non-const folly::Function: 144 * int number = 0; 145 * folly::Function<void()> print_number = 146 * [number] () mutable { std::cout << ++number << std::endl; }; 147 * // Trying to store the above mutable lambda in a 148 * // `folly::Function<void() const>` would lead to a compiler error: 149 * // error: no viable conversion from '(lambda at ...)' to 150 * // 'folly::Function<void () const>' 151 * 152 * Casting between const and non-const `folly::Function`s: 153 * conversion from const to non-const signatures happens implicitly. Any 154 * function that takes a `folly::Function<R(Args...)>` can be passed 155 * a `folly::Function<R(Args...) const>` without explicit conversion. 156 * This is safe, because casting from const to non-const only entails giving 157 * up the ability to invoke the function from a const context. 158 * Casting from a non-const to a const signature is potentially dangerous, 159 * as it means that a function that may change its inner state when invoked 160 * is made possible to call from a const context. Therefore this cast does 161 * not happen implicitly. The function `folly::constCastFunction` can 162 * be used to perform the cast. 163 * 164 * // Mutable lambda: can only be stored in a non-const folly::Function: 165 * int number = 0; 166 * folly::Function<void()> print_number = 167 * [number] () mutable { std::cout << ++number << std::endl; }; 168 * 169 * // const-cast to a const folly::Function: 170 * folly::Function<void() const> print_number_const = 171 * constCastFunction(std::move(print_number)); 172 * 173 * When to use const function types? 174 * Generally, only when you need them. When you use a `folly::Function` as a 175 * member of a struct or class, only use a const function signature when you 176 * need to invoke the function from const context. 177 * When passing a `folly::Function` to a function, the function should accept 178 * a non-const `folly::Function` whenever possible, i.e. when it does not 179 * need to pass on or store a const `folly::Function`. This is the least 180 * possible constraint: you can always pass a const `folly::Function` when 181 * the function accepts a non-const one. 182 * 183 * How does the const behaviour compare to `std::function`? 184 * `std::function` can wrap object with non-const invokation behaviour but 185 * exposes them as const. The equivalent behaviour can be achieved with 186 * `folly::Function` like so: 187 * 188 * std::function<void(void)> stdfunc = someCallable; 189 * 190 * folly::Function<void(void) const> uniqfunc = constCastFunction( 191 * folly::Function<void(void)>(someCallable) 192 * ); 193 * 194 * You need to wrap the callable first in a non-const `folly::Function` to 195 * select a non-const invoke operator (or the const one if no non-const one is 196 * present), and then move it into a const `folly::Function` using 197 * `constCastFunction`. 198 * The name of `constCastFunction` should warn you that something 199 * potentially dangerous is happening. As a matter of fact, using 200 * `std::function` always involves this potentially dangerous aspect, which 201 * is why it is not considered fully const-safe or even const-correct. 202 * However, in most of the cases you will not need the dangerous aspect at all. 203 * Either you do not require invokation of the function from a const context, 204 * in which case you do not need to use `constCastFunction` and just 205 * use the inner `folly::Function` in the example above, i.e. just use a 206 * non-const `folly::Function`. Or, you may need invokation from const, but 207 * the callable you are wrapping does not mutate its state (e.g. it is a class 208 * object and implements `operator() const`, or it is a normal, 209 * non-mutable lambda), in which case you can wrap the callable in a const 210 * `folly::Function` directly, without using `constCastFunction`. 211 * Only if you require invokation from a const context of a callable that 212 * may mutate itself when invoked you have to go through the above procedure. 213 * However, in that case what you do is potentially dangerous and requires 214 * the equivalent of a `const_cast`, hence you need to call 215 * `constCastFunction`. 216 */ 217 218 #pragma once 219 220 #include <functional> 221 #include <memory> 222 #include <new> 223 #include <type_traits> 224 #include <utility> 225 226 #include <folly/CppAttributes.h> 227 #include <folly/Portability.h> 228 #include <folly/Traits.h> 229 #include <folly/functional/Invoke.h> 230 #include <folly/lang/Exception.h> 231 232 namespace folly { 233 234 template <typename FunctionType> 235 class Function; 236 237 template <typename ReturnType, typename... Args> 238 Function<ReturnType(Args...) const> constCastFunction( 239 Function<ReturnType(Args...)>&&) noexcept; 240 241 #if FOLLY_HAVE_NOEXCEPT_FUNCTION_TYPE 242 template <typename ReturnType, typename... Args> 243 Function<ReturnType(Args...) const noexcept> constCastFunction( 244 Function<ReturnType(Args...) noexcept>&&) noexcept; 245 #endif 246 247 namespace detail { 248 namespace function { 249 250 enum class Op { MOVE, NUKE, HEAP }; 251 252 union Data { Data()253 Data() {} 254 void* big; 255 std::aligned_storage<6 * sizeof(void*)>::type tiny; 256 }; 257 258 template <typename Fun, typename = Fun*> 259 using IsSmall = Conjunction< 260 bool_constant<(sizeof(Fun) <= sizeof(Data::tiny))>, 261 std::is_nothrow_move_constructible<Fun>>; 262 using SmallTag = std::true_type; 263 using HeapTag = std::false_type; 264 265 template <typename T> 266 struct NotFunction : std::true_type {}; 267 template <typename T> 268 struct NotFunction<Function<T>> : std::false_type {}; 269 270 template <typename T> 271 using EnableIfNotFunction = 272 typename std::enable_if<NotFunction<T>::value>::type; 273 274 struct CoerceTag {}; 275 276 template <typename T> 277 bool isNullPtrFn(T* p) { 278 return p == nullptr; 279 } 280 template <typename T> 281 std::false_type isNullPtrFn(T&&) { 282 return {}; 283 } 284 285 template <typename F, typename... Args> 286 using CallableResult = decltype(std::declval<F>()(std::declval<Args>()...)); 287 288 template < 289 typename From, 290 typename To, 291 typename = typename std::enable_if< 292 !std::is_reference<To>::value || std::is_reference<From>::value>::type> 293 using SafeResultOf = decltype(static_cast<To>(std::declval<From>())); 294 295 template <typename FunctionType> 296 struct FunctionTraits; 297 298 template <typename ReturnType, typename... Args> 299 struct FunctionTraits<ReturnType(Args...)> { 300 using Call = ReturnType (*)(Data&, Args&&...); 301 using IsConst = std::false_type; 302 using ConstSignature = ReturnType(Args...) const; 303 using NonConstSignature = ReturnType(Args...); 304 using OtherSignature = ConstSignature; 305 306 template <typename F> 307 using ResultOf = 308 SafeResultOf<CallableResult<_t<std::decay<F>>&, Args...>, ReturnType>; 309 310 template <typename Fun> 311 static ReturnType callSmall(Data& p, Args&&... args) { 312 return static_cast<ReturnType>((*static_cast<Fun*>( 313 static_cast<void*>(&p.tiny)))(static_cast<Args&&>(args)...)); 314 } 315 316 template <typename Fun> 317 static ReturnType callBig(Data& p, Args&&... args) { 318 return static_cast<ReturnType>( 319 (*static_cast<Fun*>(p.big))(static_cast<Args&&>(args)...)); 320 } 321 322 static ReturnType uninitCall(Data&, Args&&...) { 323 throw std::bad_function_call(); 324 } 325 326 ReturnType operator()(Args... args) { 327 auto& fn = *static_cast<Function<NonConstSignature>*>(this); 328 return fn.call_(fn.data_, static_cast<Args&&>(args)...); 329 } 330 331 class SharedProxy { 332 std::shared_ptr<Function<NonConstSignature>> sp_; 333 334 public: 335 explicit SharedProxy(Function<NonConstSignature>&& func) 336 : sp_(std::make_shared<Function<NonConstSignature>>(std::move(func))) {} 337 ReturnType operator()(Args&&... args) const { 338 return (*sp_)(static_cast<Args&&>(args)...); 339 } 340 }; 341 }; 342 343 template <typename ReturnType, typename... Args> 344 struct FunctionTraits<ReturnType(Args...) const> { 345 using Call = ReturnType (*)(Data&, Args&&...); 346 using IsConst = std::true_type; 347 using ConstSignature = ReturnType(Args...) const; 348 using NonConstSignature = ReturnType(Args...); 349 using OtherSignature = NonConstSignature; 350 351 template <typename F> 352 using ResultOf = SafeResultOf< 353 CallableResult<const _t<std::decay<F>>&, Args...>, 354 ReturnType>; 355 356 template <typename Fun> 357 static ReturnType callSmall(Data& p, Args&&... args) { 358 return static_cast<ReturnType>((*static_cast<const Fun*>( 359 static_cast<void*>(&p.tiny)))(static_cast<Args&&>(args)...)); 360 } 361 362 template <typename Fun> 363 static ReturnType callBig(Data& p, Args&&... args) { 364 return static_cast<ReturnType>( 365 (*static_cast<const Fun*>(p.big))(static_cast<Args&&>(args)...)); 366 } 367 368 static ReturnType uninitCall(Data&, Args&&...) { 369 throw std::bad_function_call(); 370 } 371 372 ReturnType operator()(Args... args) const { 373 auto& fn = *static_cast<const Function<ConstSignature>*>(this); 374 return fn.call_(fn.data_, static_cast<Args&&>(args)...); 375 } 376 377 class SharedProxy { 378 std::shared_ptr<Function<ConstSignature>> sp_; 379 380 public: 381 explicit SharedProxy(Function<ConstSignature>&& func) 382 : sp_(std::make_shared<Function<ConstSignature>>(std::move(func))) {} 383 ReturnType operator()(Args&&... args) const { 384 return (*sp_)(static_cast<Args&&>(args)...); 385 } 386 }; 387 }; 388 389 #if FOLLY_HAVE_NOEXCEPT_FUNCTION_TYPE 390 template <typename ReturnType, typename... Args> 391 struct FunctionTraits<ReturnType(Args...) noexcept> { 392 using Call = ReturnType (*)(Data&, Args&&...) noexcept; 393 using IsConst = std::false_type; 394 using ConstSignature = ReturnType(Args...) const noexcept; 395 using NonConstSignature = ReturnType(Args...) noexcept; 396 using OtherSignature = ConstSignature; 397 398 template <typename F> 399 using ResultOf = 400 SafeResultOf<CallableResult<_t<std::decay<F>>&, Args...>, ReturnType>; 401 402 template <typename Fun> 403 static ReturnType callSmall(Data& p, Args&&... args) noexcept { 404 return static_cast<ReturnType>((*static_cast<Fun*>( 405 static_cast<void*>(&p.tiny)))(static_cast<Args&&>(args)...)); 406 } 407 408 template <typename Fun> 409 static ReturnType callBig(Data& p, Args&&... args) noexcept { 410 return static_cast<ReturnType>( 411 (*static_cast<Fun*>(p.big))(static_cast<Args&&>(args)...)); 412 } 413 414 static ReturnType uninitCall(Data&, Args&&...) noexcept { 415 terminate_with<std::bad_function_call>(); 416 } 417 418 ReturnType operator()(Args... args) noexcept { 419 auto& fn = *static_cast<Function<NonConstSignature>*>(this); 420 return fn.call_(fn.data_, static_cast<Args&&>(args)...); 421 } 422 423 class SharedProxy { 424 std::shared_ptr<Function<NonConstSignature>> sp_; 425 426 public: 427 explicit SharedProxy(Function<NonConstSignature>&& func) 428 : sp_(std::make_shared<Function<NonConstSignature>>(std::move(func))) {} 429 ReturnType operator()(Args&&... args) const { 430 return (*sp_)(static_cast<Args&&>(args)...); 431 } 432 }; 433 }; 434 435 template <typename ReturnType, typename... Args> 436 struct FunctionTraits<ReturnType(Args...) const noexcept> { 437 using Call = ReturnType (*)(Data&, Args&&...) noexcept; 438 using IsConst = std::true_type; 439 using ConstSignature = ReturnType(Args...) const noexcept; 440 using NonConstSignature = ReturnType(Args...) noexcept; 441 using OtherSignature = NonConstSignature; 442 443 template <typename F> 444 using ResultOf = SafeResultOf< 445 CallableResult<const _t<std::decay<F>>&, Args...>, 446 ReturnType>; 447 448 template <typename Fun> 449 static ReturnType callSmall(Data& p, Args&&... args) noexcept { 450 return static_cast<ReturnType>((*static_cast<const Fun*>( 451 static_cast<void*>(&p.tiny)))(static_cast<Args&&>(args)...)); 452 } 453 454 template <typename Fun> 455 static ReturnType callBig(Data& p, Args&&... args) noexcept { 456 return static_cast<ReturnType>( 457 (*static_cast<const Fun*>(p.big))(static_cast<Args&&>(args)...)); 458 } 459 460 static ReturnType uninitCall(Data&, Args&&...) noexcept { 461 throw std::bad_function_call(); 462 } 463 464 ReturnType operator()(Args... args) const noexcept { 465 auto& fn = *static_cast<const Function<ConstSignature>*>(this); 466 return fn.call_(fn.data_, static_cast<Args&&>(args)...); 467 } 468 469 class SharedProxy { 470 std::shared_ptr<Function<ConstSignature>> sp_; 471 472 public: 473 explicit SharedProxy(Function<ConstSignature>&& func) 474 : sp_(std::make_shared<Function<ConstSignature>>(std::move(func))) {} 475 ReturnType operator()(Args&&... args) const { 476 return (*sp_)(static_cast<Args&&>(args)...); 477 } 478 }; 479 }; 480 #endif 481 482 template <typename Fun> 483 bool execSmall(Op o, Data* src, Data* dst) { 484 switch (o) { 485 case Op::MOVE: 486 ::new (static_cast<void*>(&dst->tiny)) 487 Fun(std::move(*static_cast<Fun*>(static_cast<void*>(&src->tiny)))); 488 FOLLY_FALLTHROUGH; 489 case Op::NUKE: 490 static_cast<Fun*>(static_cast<void*>(&src->tiny))->~Fun(); 491 break; 492 case Op::HEAP: 493 break; 494 } 495 return false; 496 } 497 498 template <typename Fun> 499 bool execBig(Op o, Data* src, Data* dst) { 500 switch (o) { 501 case Op::MOVE: 502 dst->big = src->big; 503 src->big = nullptr; 504 break; 505 case Op::NUKE: 506 delete static_cast<Fun*>(src->big); 507 break; 508 case Op::HEAP: 509 break; 510 } 511 return true; 512 } 513 514 } // namespace function 515 } // namespace detail 516 517 template <typename FunctionType> 518 class Function final : private detail::function::FunctionTraits<FunctionType> { 519 // These utility types are defined outside of the template to reduce 520 // the number of instantiations, and then imported in the class 521 // namespace for convenience. 522 using Data = detail::function::Data; 523 using Op = detail::function::Op; 524 using SmallTag = detail::function::SmallTag; 525 using HeapTag = detail::function::HeapTag; 526 using CoerceTag = detail::function::CoerceTag; 527 528 using Traits = detail::function::FunctionTraits<FunctionType>; 529 using Call = typename Traits::Call; 530 using Exec = bool (*)(Op, Data*, Data*); 531 532 template <typename Fun> 533 using IsSmall = detail::function::IsSmall<Fun>; 534 535 // The `data_` member is mutable to allow `constCastFunction` to work without 536 // invoking undefined behavior. Const-correctness is only violated when 537 // `FunctionType` is a const function type (e.g., `int() const`) and `*this` 538 // is the result of calling `constCastFunction`. 539 mutable Data data_{}; 540 Call call_{&Traits::uninitCall}; 541 Exec exec_{nullptr}; 542 543 bool exec(Op o, Data* src, Data* dst) const { 544 return exec_ && exec_(o, src, dst); 545 } 546 547 friend Traits; 548 friend Function<typename Traits::ConstSignature> folly::constCastFunction<>( 549 Function<typename Traits::NonConstSignature>&&) noexcept; 550 friend class Function<typename Traits::OtherSignature>; 551 552 template <typename Fun> 553 Function(Fun&& fun, SmallTag) noexcept { 554 using FunT = typename std::decay<Fun>::type; 555 if (!detail::function::isNullPtrFn(fun)) { 556 ::new (static_cast<void*>(&data_.tiny)) FunT(static_cast<Fun&&>(fun)); 557 call_ = &Traits::template callSmall<FunT>; 558 exec_ = &detail::function::execSmall<FunT>; 559 } 560 } 561 562 template <typename Fun> 563 Function(Fun&& fun, HeapTag) { 564 using FunT = typename std::decay<Fun>::type; 565 data_.big = new FunT(static_cast<Fun&&>(fun)); 566 call_ = &Traits::template callBig<FunT>; 567 exec_ = &detail::function::execBig<FunT>; 568 } 569 570 template <typename Signature> 571 Function(Function<Signature>&& that, CoerceTag) 572 : Function(static_cast<Function<Signature>&&>(that), HeapTag{}) {} 573 574 Function(Function<typename Traits::OtherSignature>&& that, CoerceTag) noexcept 575 : call_(that.call_), exec_(that.exec_) { 576 that.call_ = &Traits::uninitCall; 577 that.exec_ = nullptr; 578 exec(Op::MOVE, &that.data_, &data_); 579 } 580 581 public: 582 /** 583 * Default constructor. Constructs an empty Function. 584 */ 585 Function() = default; 586 587 // not copyable 588 Function(const Function&) = delete; 589 590 #if __OBJC__ 591 // Make sure Objective C blocks are copied 592 template <class ReturnType, class... Args> 593 /*implicit*/ Function(ReturnType (^objCBlock)(Args... args)) 594 : Function([blockCopy = (ReturnType(^)(Args...))[objCBlock copy]]( 595 Args... args) { return blockCopy(args...); }){}; 596 #endif 597 598 /** 599 * Move constructor 600 */ 601 Function(Function&& that) noexcept : call_(that.call_), exec_(that.exec_) { 602 // that must be uninitialized before exec() call in the case of self move 603 that.call_ = &Traits::uninitCall; 604 that.exec_ = nullptr; 605 exec(Op::MOVE, &that.data_, &data_); 606 } 607 608 /** 609 * Constructs an empty `Function`. 610 */ 611 /* implicit */ Function(std::nullptr_t) noexcept {} 612 613 /** 614 * Constructs a new `Function` from any callable object that is _not_ a 615 * `folly::Function`. This handles function pointers, pointers to static 616 * member functions, `std::reference_wrapper` objects, `std::function` 617 * objects, and arbitrary objects that implement `operator()` if the parameter 618 * signature matches (i.e. it returns an object convertible to `R` when called 619 * with `Args...`). 620 * 621 * \note `typename Traits::template ResultOf<Fun>` prevents this overload 622 * from being selected by overload resolution when `fun` is not a compatible 623 * function. 624 * 625 * \note The noexcept requires some explanation. `IsSmall` is true when the 626 * decayed type fits within the internal buffer and is noexcept-movable. But 627 * this ctor might copy, not move. What we need here, if this ctor does a 628 * copy, is that this ctor be noexcept when the copy is noexcept. That is not 629 * checked in `IsSmall`, and shouldn't be, because once the `Function` is 630 * constructed, the contained object is never copied. This check is for this 631 * ctor only, in the case that this ctor does a copy. 632 */ 633 template < 634 typename Fun, 635 typename = detail::function::EnableIfNotFunction<Fun>, 636 typename = typename Traits::template ResultOf<Fun>> 637 /* implicit */ Function(Fun fun) noexcept( 638 IsSmall<Fun>::value&& noexcept(Fun(std::declval<Fun>()))) 639 : Function(std::move(fun), IsSmall<Fun>{}) {} 640 641 /** 642 * For move-constructing from a `folly::Function<X(Ys...) [const?]>`. 643 * For a `Function` with a `const` function type, the object must be 644 * callable from a `const`-reference, i.e. implement `operator() const`. 645 * For a `Function` with a non-`const` function type, the object will 646 * be called from a non-const reference, which means that it will execute 647 * a non-const `operator()` if it is defined, and falls back to 648 * `operator() const` otherwise. 649 */ 650 template < 651 typename Signature, 652 typename = typename Traits::template ResultOf<Function<Signature>>> 653 Function(Function<Signature>&& that) noexcept( 654 noexcept(Function(std::move(that), CoerceTag{}))) 655 : Function(std::move(that), CoerceTag{}) {} 656 657 /** 658 * If `ptr` is null, constructs an empty `Function`. Otherwise, 659 * this constructor is equivalent to `Function(std::mem_fn(ptr))`. 660 */ 661 template < 662 typename Member, 663 typename Class, 664 // Prevent this overload from being selected when `ptr` is not a 665 // compatible member function pointer. 666 typename = decltype(Function(std::mem_fn((Member Class::*)0)))> 667 /* implicit */ Function(Member Class::*ptr) noexcept { 668 if (ptr) { 669 *this = std::mem_fn(ptr); 670 } 671 } 672 673 ~Function() { 674 exec(Op::NUKE, &data_, nullptr); 675 } 676 677 Function& operator=(const Function&) = delete; 678 679 #if __OBJC__ 680 // Make sure Objective C blocks are copied 681 template <class ReturnType, class... Args> 682 /* implicit */ Function& operator=(ReturnType (^objCBlock)(Args... args)) { 683 (*this) = [blockCopy = (ReturnType(^)(Args...))[objCBlock copy]]( 684 Args... args) { return blockCopy(args...); }; 685 return *this; 686 } 687 #endif 688 689 /** 690 * Move assignment operator 691 * 692 * \note Leaves `that` in a valid but unspecified state. If `&that == this` 693 * then `*this` is left in a valid but unspecified state. 694 */ 695 Function& operator=(Function&& that) noexcept { 696 // Q: Why is it safe to destroy and reconstruct this object in place? 697 // A: Two reasons: First, `Function` is a final class, so in doing this 698 // we aren't slicing off any derived parts. And second, the move 699 // operation is guaranteed not to throw so we always leave the object 700 // in a valid state. 701 // In the case of self-move (this == &that), this leaves the object in 702 // a default-constructed state. First the object is destroyed, then we 703 // pass the destroyed object to the move constructor. The first thing the 704 // move constructor does is default-construct the object. That object is 705 // "moved" into itself, which is a no-op for a default-constructed Function. 706 this->~Function(); 707 ::new (this) Function(std::move(that)); 708 return *this; 709 } 710 711 /** 712 * Assigns a callable object to this `Function`. If the operation fails, 713 * `*this` is left unmodified. 714 * 715 * \note `typename = decltype(Function(std::declval<Fun>()))` prevents this 716 * overload from being selected by overload resolution when `fun` is not a 717 * compatible function. 718 */ 719 template <typename Fun, typename = decltype(Function(std::declval<Fun>()))> 720 Function& operator=(Fun fun) noexcept( 721 noexcept(/* implicit */ Function(std::declval<Fun>()))) { 722 // Doing this in place is more efficient when we can do so safely. 723 if (noexcept(/* implicit */ Function(std::declval<Fun>()))) { 724 // Q: Why is is safe to destroy and reconstruct this object in place? 725 // A: See the explanation in the move assignment operator. 726 this->~Function(); 727 ::new (this) Function(std::move(fun)); 728 } else { 729 // Construct a temporary and (nothrow) swap. 730 Function(std::move(fun)).swap(*this); 731 } 732 return *this; 733 } 734 735 /** 736 * For assigning from a `Function<X(Ys..) [const?]>`. 737 */ 738 template < 739 typename Signature, 740 typename = typename Traits::template ResultOf<Function<Signature>>> 741 Function& operator=(Function<Signature>&& that) noexcept( 742 noexcept(Function(std::move(that)))) { 743 return (*this = Function(std::move(that))); 744 } 745 746 /** 747 * Clears this `Function`. 748 */ 749 Function& operator=(std::nullptr_t) noexcept { 750 return (*this = Function()); 751 } 752 753 /** 754 * If `ptr` is null, clears this `Function`. Otherwise, this assignment 755 * operator is equivalent to `*this = std::mem_fn(ptr)`. 756 */ 757 template <typename Member, typename Class> 758 auto operator=(Member Class::*ptr) noexcept 759 // Prevent this overload from being selected when `ptr` is not a 760 // compatible member function pointer. 761 -> decltype(operator=(std::mem_fn(ptr))) { 762 return ptr ? (*this = std::mem_fn(ptr)) : (*this = Function()); 763 } 764 765 /** 766 * Call the wrapped callable object with the specified arguments. 767 */ 768 using Traits::operator(); 769 770 /** 771 * Exchanges the callable objects of `*this` and `that`. 772 */ 773 void swap(Function& that) noexcept { 774 std::swap(*this, that); 775 } 776 777 /** 778 * Returns `true` if this `Function` contains a callable, i.e. is 779 * non-empty. 780 */ 781 explicit operator bool() const noexcept { 782 return exec_ != nullptr; 783 } 784 785 /** 786 * Returns `true` if this `Function` stores the callable on the 787 * heap. If `false` is returned, there has been no additional memory 788 * allocation and the callable is stored inside the `Function` 789 * object itself. 790 */ 791 bool hasAllocatedMemory() const noexcept { 792 return exec(Op::HEAP, nullptr, nullptr); 793 } 794 795 using typename Traits::SharedProxy; 796 797 /** 798 * Move this `Function` into a copyable callable object, of which all copies 799 * share the state. 800 */ 801 SharedProxy asSharedProxy() && { 802 return SharedProxy{std::move(*this)}; 803 } 804 805 /** 806 * Construct a `std::function` by moving in the contents of this `Function`. 807 * Note that the returned `std::function` will share its state (i.e. captured 808 * data) across all copies you make of it, so be very careful when copying. 809 */ 810 std::function<typename Traits::NonConstSignature> asStdFunction() && { 811 return std::move(*this).asSharedProxy(); 812 } 813 }; 814 815 template <typename FunctionType> 816 void swap(Function<FunctionType>& lhs, Function<FunctionType>& rhs) noexcept { 817 lhs.swap(rhs); 818 } 819 820 template <typename FunctionType> 821 bool operator==(const Function<FunctionType>& fn, std::nullptr_t) { 822 return !fn; 823 } 824 825 template <typename FunctionType> 826 bool operator==(std::nullptr_t, const Function<FunctionType>& fn) { 827 return !fn; 828 } 829 830 template <typename FunctionType> 831 bool operator!=(const Function<FunctionType>& fn, std::nullptr_t) { 832 return !(fn == nullptr); 833 } 834 835 template <typename FunctionType> 836 bool operator!=(std::nullptr_t, const Function<FunctionType>& fn) { 837 return !(nullptr == fn); 838 } 839 840 /** 841 * NOTE: See detailed note about `constCastFunction` at the top of the file. 842 * This is potentially dangerous and requires the equivalent of a `const_cast`. 843 */ 844 template <typename ReturnType, typename... Args> 845 Function<ReturnType(Args...) const> constCastFunction( 846 Function<ReturnType(Args...)>&& that) noexcept { 847 return Function<ReturnType(Args...) const>{std::move(that), 848 detail::function::CoerceTag{}}; 849 } 850 851 template <typename ReturnType, typename... Args> 852 Function<ReturnType(Args...) const> constCastFunction( 853 Function<ReturnType(Args...) const>&& that) noexcept { 854 return std::move(that); 855 } 856 857 #if FOLLY_HAVE_NOEXCEPT_FUNCTION_TYPE 858 template <typename ReturnType, typename... Args> 859 Function<ReturnType(Args...) const noexcept> constCastFunction( 860 Function<ReturnType(Args...) noexcept>&& that) noexcept { 861 return Function<ReturnType(Args...) const noexcept>{ 862 std::move(that), detail::function::CoerceTag{}}; 863 } 864 865 template <typename ReturnType, typename... Args> 866 Function<ReturnType(Args...) const noexcept> constCastFunction( 867 Function<ReturnType(Args...) const noexcept>&& that) noexcept { 868 return std::move(that); 869 } 870 #endif 871 872 /** 873 * @class FunctionRef 874 * 875 * @brief A reference wrapper for callable objects 876 * 877 * FunctionRef is similar to std::reference_wrapper, but the template parameter 878 * is the function signature type rather than the type of the referenced object. 879 * A folly::FunctionRef is cheap to construct as it contains only a pointer to 880 * the referenced callable and a pointer to a function which invokes the 881 * callable. 882 * 883 * The user of FunctionRef must be aware of the reference semantics: storing a 884 * copy of a FunctionRef is potentially dangerous and should be avoided unless 885 * the referenced object definitely outlives the FunctionRef object. Thus any 886 * function that accepts a FunctionRef parameter should only use it to invoke 887 * the referenced function and not store a copy of it. Knowing that FunctionRef 888 * itself has reference semantics, it is generally okay to use it to reference 889 * lambdas that capture by reference. 890 */ 891 892 template <typename FunctionType> 893 class FunctionRef; 894 895 template <typename ReturnType, typename... Args> 896 class FunctionRef<ReturnType(Args...)> final { 897 using Call = ReturnType (*)(void*, Args&&...); 898 899 static ReturnType uninitCall(void*, Args&&...) { 900 throw std::bad_function_call(); 901 } 902 903 template <typename Fun> 904 static ReturnType call(void* object, Args&&... args) { 905 using Pointer = _t<std::add_pointer<Fun>>; 906 return static_cast<ReturnType>(invoke( 907 static_cast<Fun&&>(*static_cast<Pointer>(object)), 908 static_cast<Args&&>(args)...)); 909 } 910 911 void* object_{nullptr}; 912 Call call_{&FunctionRef::uninitCall}; 913 914 public: 915 /** 916 * Default constructor. Constructs an empty FunctionRef. 917 * 918 * Invoking it will throw std::bad_function_call. 919 */ 920 FunctionRef() = default; 921 922 /** 923 * Construct a FunctionRef from a reference to a callable object. 924 */ 925 template < 926 typename Fun, 927 typename std::enable_if< 928 Conjunction< 929 Negation<std::is_same<FunctionRef, _t<std::decay<Fun>>>>, 930 is_invocable_r<ReturnType, Fun&&, Args&&...>>::value, 931 int>::type = 0> 932 constexpr /* implicit */ FunctionRef(Fun&& fun) noexcept 933 // `Fun` may be a const type, in which case we have to do a const_cast 934 // to store the address in a `void*`. This is safe because the `void*` 935 // will be cast back to `Fun*` (which is a const pointer whenever `Fun` 936 // is a const type) inside `FunctionRef::call` 937 : object_( 938 const_cast<void*>(static_cast<void const*>(std::addressof(fun)))), 939 call_(&FunctionRef::call<Fun>) {} 940 941 ReturnType operator()(Args... args) const { 942 return call_(object_, static_cast<Args&&>(args)...); 943 } 944 945 constexpr explicit operator bool() const { 946 return object_; 947 } 948 }; 949 950 } // namespace folly 951