1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171 |
- /*
- * Copyright 2017-present Facebook, Inc.
- *
- * 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
- *
- * http://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.
- */
- // TODO: [x] "cast" from Poly<C&> to Poly<C&&>
- // TODO: [ ] copy/move from Poly<C&>/Poly<C&&> to Poly<C>
- // TODO: [ ] copy-on-write?
- // TODO: [ ] down- and cross-casting? (Possible?)
- // TODO: [ ] shared ownership? (Dubious.)
- // TODO: [ ] can games be played with making the VTable a member of a struct
- // with strange alignment such that the address of the VTable can
- // be used to tell whether the object is stored in-situ or not?
- #pragma once
- #if defined(__GNUC__) && !defined(__clang__) && __GNUC__ < 5
- #error Folly.Poly requires gcc-5 or greater
- #endif
- #include <cassert>
- #include <new>
- #include <type_traits>
- #include <typeinfo>
- #include <utility>
- #include <folly/CPortability.h>
- #include <folly/CppAttributes.h>
- #include <folly/Traits.h>
- #include <folly/detail/TypeList.h>
- #include <folly/lang/Assume.h>
- #if !defined(__cpp_inline_variables)
- #define FOLLY_INLINE_CONSTEXPR constexpr
- #else
- #define FOLLY_INLINE_CONSTEXPR inline constexpr
- #endif
- #include <folly/PolyException.h>
- #include <folly/detail/PolyDetail.h>
- namespace folly {
- template <class I>
- struct Poly;
- /**
- * Within the definition of interface `I`, `PolySelf<Base>` is an alias for
- * the instance of `Poly` that is currently being instantiated. It is
- * one of: `Poly<J>`, `Poly<J&&>`, `Poly<J&>`, or `Poly<J const&>`; where
- * `J` is either `I` or some interface that extends `I`.
- *
- * It can be used within interface definitions to declare members that accept
- * other `Poly` objects of the same type as `*this`.
- *
- * The first parameter may optionally be cv- and/or reference-qualified, in
- * which case, the qualification is applies to the type of the interface in the
- * resulting `Poly<>` instance. The second template parameter controls whether
- * or not the interface is decayed before the cv-ref qualifiers of the first
- * argument are applied. For example, given the following:
- *
- * struct Foo {
- * template <class Base>
- * struct Interface : Base {
- * using A = PolySelf<Base>;
- * using B = PolySelf<Base &>;
- * using C = PolySelf<Base const &>;
- * using X = PolySelf<Base, PolyDecay>;
- * using Y = PolySelf<Base &, PolyDecay>;
- * using Z = PolySelf<Base const &, PolyDecay>;
- * };
- * // ...
- * };
- * struct Bar : PolyExtends<Foo> {
- * // ...
- * };
- *
- * Then for `Poly<Bar>`, the typedefs are aliases for the following types:
- * - `A` is `Poly<Bar>`
- * - `B` is `Poly<Bar &>`
- * - `C` is `Poly<Bar const &>`
- * - `X` is `Poly<Bar>`
- * - `Y` is `Poly<Bar &>`
- * - `Z` is `Poly<Bar const &>`
- *
- * And for `Poly<Bar &>`, the typedefs are aliases for the following types:
- * - `A` is `Poly<Bar &>`
- * - `B` is `Poly<Bar &>`
- * - `C` is `Poly<Bar &>`
- * - `X` is `Poly<Bar>`
- * - `Y` is `Poly<Bar &>`
- * - `Z` is `Poly<Bar const &>`
- */
- template <
- class Node,
- class Tfx = detail::MetaIdentity,
- class Access = detail::PolyAccess>
- using PolySelf = decltype(Access::template self_<Node, Tfx>());
- /**
- * When used in conjunction with `PolySelf`, controls how to construct `Poly`
- * types related to the one currently being instantiated.
- *
- * \sa PolySelf
- */
- using PolyDecay = detail::MetaQuote<std::decay_t>;
- #if !defined(__cpp_template_auto)
- /**
- * Use `FOLLY_POLY_MEMBERS(MEMS...)` on pre-C++17 compilers to specify a
- * comma-separated list of member function bindings.
- *
- * For example:
- *
- * struct IFooBar {
- * template <class Base>
- * struct Interface : Base {
- * int foo() const { return folly::poly_call<0>(*this); }
- * void bar() { folly::poly_call<1>(*this); }
- * };
- * template <class T>
- * using Members = FOLLY_POLY_MEMBERS(&T::foo, &T::bar);
- * };
- */
- #define FOLLY_POLY_MEMBERS(...) \
- typename decltype(::folly::detail::deduceMembers( \
- __VA_ARGS__))::template Members<__VA_ARGS__>
- /**
- * Use `FOLLY_POLY_MEMBER(SIG, MEM)` on pre-C++17 compilers to specify a member
- * function binding that needs to be disambiguated because of overloads. `SIG`
- * should the (possibly const-qualified) signature of the `MEM` member function
- * pointer.
- *
- * For example:
- *
- * struct IFoo {
- * template <class Base> struct Interface : Base {
- * int foo() const { return folly::poly_call<0>(*this); }
- * };
- * template <class T> using Members = FOLLY_POLY_MEMBERS(
- * // This works even if T::foo is overloaded:
- * FOLLY_POLY_MEMBER(int()const, &T::foo)
- * );
- * };
- */
- #define FOLLY_POLY_MEMBER(SIG, MEM) \
- ::folly::detail::MemberDef< \
- ::folly::detail::Member<decltype(::folly::sig<SIG>(MEM)), MEM>>::value
- /**
- * A list of member function bindings.
- */
- template <class... Ts>
- using PolyMembers = detail::TypeList<Ts...>;
- #else
- #define FOLLY_POLY_MEMBER(SIG, MEM) ::folly::sig<SIG>(MEM)
- #define FOLLY_POLY_MEMBERS(...) ::folly::PolyMembers<__VA_ARGS__>
- template <auto... Ps>
- struct PolyMembers {};
- #endif
- /**
- * Used in the definition of a `Poly` interface to say that the current
- * interface is an extension of a set of zero or more interfaces.
- *
- * Example:
- *
- * struct IFoo {
- * template <class Base> struct Interface : Base {
- * void foo() { folly::poly_call<0>(*this); }
- * };
- * template <class T> using Members = FOLLY_POLY_MEMBERS(&T::foo);
- * }
- * struct IBar : PolyExtends<IFoo> {
- * template <class Base> struct Interface : Base {
- * void bar(int i) { folly::poly_call<0>(*this, i); }
- * };
- * template <class T> using Members = FOLLY_POLY_MEMBERS(&T::bar);
- * }
- */
- template <class... I>
- struct PolyExtends : virtual I... {
- using Subsumptions = detail::TypeList<I...>;
- template <class Base>
- struct Interface : Base {
- Interface() = default;
- using Base::Base;
- };
- template <class...>
- using Members = PolyMembers<>;
- };
- ////////////////////////////////////////////////////////////////////////////////
- /**
- * Call the N-th member of the currently-being-defined interface. When the
- * first parameter is an object of type `PolySelf<Base>` (as opposed to `*this`)
- * you must explicitly specify which interface through which to dispatch.
- * For instance:
- *
- * struct IAddable {
- * template <class Base>
- * struct Interface : Base {
- * friend PolySelf<Base, Decay>
- * operator+(PolySelf<Base> const& a, PolySelf<Base> const& b) {
- * return folly::poly_call<0, IAddable>(a, b);
- * }
- * };
- * template <class T>
- * static auto plus_(T const& a, T const& b) -> decltype(a + b) {
- * return a + b;
- * }
- * template <class T>
- * using Members = FOLLY_POLY_MEMBERS(&plus_<std::decay_t<T>>);
- * };
- *
- * \sa PolySelf
- */
- template <std::size_t N, typename This, typename... As>
- auto poly_call(This&& _this, As&&... as)
- -> decltype(detail::PolyAccess::call<N>(
- static_cast<This&&>(_this),
- static_cast<As&&>(as)...)) {
- return detail::PolyAccess::call<N>(
- static_cast<This&&>(_this), static_cast<As&&>(as)...);
- }
- /// \overload
- template <std::size_t N, class I, class Tail, typename... As>
- decltype(auto) poly_call(detail::PolyNode<I, Tail>&& _this, As&&... as) {
- using This = detail::InterfaceOf<I, detail::PolyNode<I, Tail>>;
- return detail::PolyAccess::call<N>(
- static_cast<This&&>(_this), static_cast<As&&>(as)...);
- }
- /// \overload
- template <std::size_t N, class I, class Tail, typename... As>
- decltype(auto) poly_call(detail::PolyNode<I, Tail>& _this, As&&... as) {
- using This = detail::InterfaceOf<I, detail::PolyNode<I, Tail>>;
- return detail::PolyAccess::call<N>(
- static_cast<This&>(_this), static_cast<As&&>(as)...);
- }
- /// \overload
- template <std::size_t N, class I, class Tail, typename... As>
- decltype(auto) poly_call(detail::PolyNode<I, Tail> const& _this, As&&... as) {
- using This = detail::InterfaceOf<I, detail::PolyNode<I, Tail>>;
- return detail::PolyAccess::call<N>(
- static_cast<This const&>(_this), static_cast<As&&>(as)...);
- }
- /// \overload
- template <
- std::size_t N,
- class I,
- class Poly,
- typename... As,
- std::enable_if_t<detail::IsPoly<Poly>::value, int> = 0>
- auto poly_call(Poly&& _this, As&&... as) -> decltype(poly_call<N, I>(
- static_cast<Poly&&>(_this).get(),
- static_cast<As&&>(as)...)) {
- return poly_call<N, I>(
- static_cast<Poly&&>(_this).get(), static_cast<As&&>(as)...);
- }
- /// \cond
- /// \overload
- template <std::size_t N, class I, typename... As>
- [[noreturn]] detail::Bottom poly_call(detail::ArchetypeBase const&, As&&...) {
- assume_unreachable();
- }
- /// \endcond
- ////////////////////////////////////////////////////////////////////////////////
- /**
- * Try to cast the `Poly` object to the requested type. If the `Poly` stores an
- * object of that type, return a reference to the object; otherwise, throw an
- * exception.
- * \tparam T The (unqualified) type to which to cast the `Poly` object.
- * \tparam Poly The type of the `Poly` object.
- * \param that The `Poly` object to be cast.
- * \return A reference to the `T` object stored in or refered to by `that`.
- * \throw BadPolyAccess if `that` is empty.
- * \throw BadPolyCast if `that` does not store or refer to an object of type
- * `T`.
- */
- template <class T, class I>
- detail::AddCvrefOf<T, I>&& poly_cast(detail::PolyRoot<I>&& that) {
- return detail::PolyAccess::cast<T>(std::move(that));
- }
- /// \overload
- template <class T, class I>
- detail::AddCvrefOf<T, I>& poly_cast(detail::PolyRoot<I>& that) {
- return detail::PolyAccess::cast<T>(that);
- }
- /// \overload
- template <class T, class I>
- detail::AddCvrefOf<T, I> const& poly_cast(detail::PolyRoot<I> const& that) {
- return detail::PolyAccess::cast<T>(that);
- }
- /// \cond
- /// \overload
- template <class T, class I>
- [[noreturn]] detail::AddCvrefOf<T, I>&& poly_cast(detail::ArchetypeRoot<I>&&) {
- assume_unreachable();
- }
- /// \overload
- template <class T, class I>
- [[noreturn]] detail::AddCvrefOf<T, I>& poly_cast(detail::ArchetypeRoot<I>&) {
- assume_unreachable();
- }
- /// \overload
- template <class T, class I>
- [[noreturn]] detail::AddCvrefOf<T, I> const& poly_cast(
- detail::ArchetypeRoot<I> const&) {
- assume_unreachable();
- }
- /// \endcond
- /// \overload
- template <
- class T,
- class Poly,
- std::enable_if_t<detail::IsPoly<Poly>::value, int> = 0>
- constexpr auto poly_cast(Poly&& that)
- -> decltype(poly_cast<T>(std::declval<Poly>().get())) {
- return poly_cast<T>(static_cast<Poly&&>(that).get());
- }
- ////////////////////////////////////////////////////////////////////////////////
- /**
- * Returns a reference to the `std::type_info` object corresponding to the
- * object currently stored in `that`. If `that` is empty, returns
- * `typeid(void)`.
- */
- template <class I>
- std::type_info const& poly_type(detail::PolyRoot<I> const& that) noexcept {
- return detail::PolyAccess::type(that);
- }
- /// \cond
- /// \overload
- [[noreturn]] inline std::type_info const& poly_type(
- detail::ArchetypeBase const&) noexcept {
- assume_unreachable();
- }
- /// \endcond
- /// \overload
- template <class Poly, std::enable_if_t<detail::IsPoly<Poly>::value, int> = 0>
- constexpr auto poly_type(Poly const& that) noexcept
- -> decltype(poly_type(that.get())) {
- return poly_type(that.get());
- }
- ////////////////////////////////////////////////////////////////////////////////
- /**
- * Returns `true` if `that` is not currently storing an object; `false`,
- * otherwise.
- */
- template <class I>
- bool poly_empty(detail::PolyRoot<I> const& that) noexcept {
- return detail::State::eEmpty == detail::PolyAccess::vtable(that)->state_;
- }
- /// \overload
- template <class I>
- constexpr bool poly_empty(detail::PolyRoot<I&&> const&) noexcept {
- return false;
- }
- /// \overload
- template <class I>
- constexpr bool poly_empty(detail::PolyRoot<I&> const&) noexcept {
- return false;
- }
- /// \overload
- template <class I>
- constexpr bool poly_empty(Poly<I&&> const&) noexcept {
- return false;
- }
- /// \overload
- template <class I>
- constexpr bool poly_empty(Poly<I&> const&) noexcept {
- return false;
- }
- /// \cond
- [[noreturn]] inline bool poly_empty(detail::ArchetypeBase const&) noexcept {
- assume_unreachable();
- }
- /// \endcond
- ////////////////////////////////////////////////////////////////////////////////
- /**
- * Given a `Poly<I&>`, return a `Poly<I&&>`. Otherwise, when `I` is not a
- * reference type, returns a `Poly<I>&&` when given a `Poly<I>&`, like
- * `std::move`.
- */
- template <
- class I,
- std::enable_if_t<detail::Not<std::is_reference<I>>::value, int> = 0>
- constexpr Poly<I>&& poly_move(detail::PolyRoot<I>& that) noexcept {
- return static_cast<Poly<I>&&>(static_cast<Poly<I>&>(that));
- }
- /// \overload
- template <
- class I,
- std::enable_if_t<detail::Not<std::is_const<I>>::value, int> = 0>
- Poly<I&&> poly_move(detail::PolyRoot<I&> const& that) noexcept {
- return detail::PolyAccess::move(that);
- }
- /// \overload
- template <class I>
- Poly<I const&> poly_move(detail::PolyRoot<I const&> const& that) noexcept {
- return detail::PolyAccess::move(that);
- }
- /// \cond
- /// \overload
- [[noreturn]] inline detail::ArchetypeBase poly_move(
- detail::ArchetypeBase const&) noexcept {
- assume_unreachable();
- }
- /// \endcond
- /// \overload
- template <class Poly, std::enable_if_t<detail::IsPoly<Poly>::value, int> = 0>
- constexpr auto poly_move(Poly& that) noexcept
- -> decltype(poly_move(that.get())) {
- return poly_move(that.get());
- }
- /// \cond
- namespace detail {
- /**
- * The implementation for `Poly` for when the interface type is not
- * reference-like qualified, as in `Poly<SemiRegular>`.
- */
- template <class I>
- struct PolyVal : PolyImpl<I> {
- private:
- friend PolyAccess;
- struct NoneSuch {};
- using Copyable = std::is_copy_constructible<PolyImpl<I>>;
- using PolyOrNonesuch = If<Copyable::value, PolyVal, NoneSuch>;
- using PolyRoot<I>::vptr_;
- PolyRoot<I>& _polyRoot_() noexcept {
- return *this;
- }
- PolyRoot<I> const& _polyRoot_() const noexcept {
- return *this;
- }
- Data* _data_() noexcept {
- return PolyAccess::data(*this);
- }
- Data const* _data_() const noexcept {
- return PolyAccess::data(*this);
- }
- public:
- /**
- * Default constructor.
- * \post `poly_empty(*this) == true`
- */
- PolyVal() = default;
- /**
- * Move constructor.
- * \post `poly_empty(that) == true`
- */
- PolyVal(PolyVal&& that) noexcept;
- /**
- * A copy constructor if `I` is copyable; otherwise, a useless constructor
- * from a private, incomplete type.
- */
- /* implicit */ PolyVal(PolyOrNonesuch const& that);
- ~PolyVal();
- /**
- * Inherit any constructors defined by any of the interfaces.
- */
- using PolyImpl<I>::PolyImpl;
- /**
- * Copy assignment, destroys the object currently held (if any) and makes
- * `*this` equal to `that` by stealing its guts.
- */
- Poly<I>& operator=(PolyVal that) noexcept;
- /**
- * Construct a Poly<I> from a concrete type that satisfies the I concept
- */
- template <class T, std::enable_if_t<ModelsInterface<T, I>::value, int> = 0>
- /* implicit */ PolyVal(T&& t);
- /**
- * Construct a `Poly` from a compatible `Poly`. "Compatible" here means: the
- * other interface extends this one either directly or indirectly.
- */
- template <class I2, std::enable_if_t<ValueCompatible<I, I2>::value, int> = 0>
- /* implicit */ PolyVal(Poly<I2> that);
- /**
- * Assign to this `Poly<I>` from a concrete type that satisfies the `I`
- * concept.
- */
- template <class T, std::enable_if_t<ModelsInterface<T, I>::value, int> = 0>
- Poly<I>& operator=(T&& t);
- /**
- * Assign a compatible `Poly` to `*this`. "Compatible" here means: the
- * other interface extends this one either directly or indirectly.
- */
- template <class I2, std::enable_if_t<ValueCompatible<I, I2>::value, int> = 0>
- Poly<I>& operator=(Poly<I2> that);
- /**
- * Swaps the values of two `Poly` objects.
- */
- void swap(Poly<I>& that) noexcept;
- };
- ////////////////////////////////////////////////////////////////////////////////
- /**
- * The implementation of `Poly` for when the interface type is
- * reference-quelified, like `Poly<SemuRegular &>`.
- */
- template <class I>
- struct PolyRef : private PolyImpl<I> {
- private:
- friend PolyAccess;
- AddCvrefOf<PolyRoot<I>, I>& _polyRoot_() const noexcept;
- Data* _data_() noexcept {
- return PolyAccess::data(*this);
- }
- Data const* _data_() const noexcept {
- return PolyAccess::data(*this);
- }
- static constexpr RefType refType() noexcept;
- protected:
- template <class That, class I2>
- PolyRef(That&& that, Type<I2>);
- public:
- /**
- * Copy constructor
- * \post `&poly_cast<T>(*this) == &poly_cast<T>(that)`, where `T` is the
- * type of the object held by `that`.
- */
- PolyRef(PolyRef const& that) noexcept;
- /**
- * Copy assignment
- * \post `&poly_cast<T>(*this) == &poly_cast<T>(that)`, where `T` is the
- * type of the object held by `that`.
- */
- Poly<I>& operator=(PolyRef const& that) noexcept;
- /**
- * Construct a `Poly<I>` from a concrete type that satisfies concept `I`.
- * \post `!poly_empty(*this)`
- */
- template <class T, std::enable_if_t<ModelsInterface<T, I>::value, int> = 0>
- /* implicit */ PolyRef(T&& t) noexcept;
- /**
- * Construct a `Poly<I>` from a compatible `Poly<I2>`.
- */
- template <
- class I2,
- std::enable_if_t<ReferenceCompatible<I, I2, I2&&>::value, int> = 0>
- /* implicit */ PolyRef(Poly<I2>&& that) noexcept(
- std::is_reference<I2>::value);
- template <
- class I2,
- std::enable_if_t<ReferenceCompatible<I, I2, I2&>::value, int> = 0>
- /* implicit */ PolyRef(Poly<I2>& that) noexcept(std::is_reference<I2>::value)
- : PolyRef{that, Type<I2>{}} {}
- template <
- class I2,
- std::enable_if_t<ReferenceCompatible<I, I2, I2 const&>::value, int> = 0>
- /* implicit */ PolyRef(Poly<I2> const& that) noexcept(
- std::is_reference<I2>::value)
- : PolyRef{that, Type<I2>{}} {}
- /**
- * Assign to a `Poly<I>` from a concrete type that satisfies concept `I`.
- * \post `!poly_empty(*this)`
- */
- template <class T, std::enable_if_t<ModelsInterface<T, I>::value, int> = 0>
- Poly<I>& operator=(T&& t) noexcept;
- /**
- * Assign to `*this` from another compatible `Poly`.
- */
- template <
- class I2,
- std::enable_if_t<ReferenceCompatible<I, I2, I2&&>::value, int> = 0>
- Poly<I>& operator=(Poly<I2>&& that) noexcept(std::is_reference<I2>::value);
- /**
- * \overload
- */
- template <
- class I2,
- std::enable_if_t<ReferenceCompatible<I, I2, I2&>::value, int> = 0>
- Poly<I>& operator=(Poly<I2>& that) noexcept(std::is_reference<I2>::value);
- /**
- * \overload
- */
- template <
- class I2,
- std::enable_if_t<ReferenceCompatible<I, I2, I2 const&>::value, int> = 0>
- Poly<I>& operator=(Poly<I2> const& that) noexcept(
- std::is_reference<I2>::value);
- /**
- * Swap which object this `Poly` references ("shallow" swap).
- */
- void swap(Poly<I>& that) noexcept;
- /**
- * Get a reference to the interface, with correct `const`-ness applied.
- */
- AddCvrefOf<PolyImpl<I>, I>& get() const noexcept;
- /**
- * Get a reference to the interface, with correct `const`-ness applied.
- */
- AddCvrefOf<PolyImpl<I>, I>& operator*() const noexcept {
- return get();
- }
- /**
- * Get a pointer to the interface, with correct `const`-ness applied.
- */
- auto operator-> () const noexcept {
- return &get();
- }
- };
- template <class I>
- using PolyValOrRef = If<std::is_reference<I>::value, PolyRef<I>, PolyVal<I>>;
- } // namespace detail
- /// \endcond
- /**
- * `Poly` is a class template that makes it relatively easy to define a
- * type-erasing polymorphic object wrapper.
- *
- * \par Type-erasure
- *
- * \par
- * `std::function` is one example of a type-erasing polymorphic object wrapper;
- * `folly::exception_wrapper` is another. Type-erasure is often used as an
- * alternative to dynamic polymorphism via inheritance-based virtual dispatch.
- * The distinguishing characteristic of type-erasing wrappers are:
- * \li **Duck typing:** Types do not need to inherit from an abstract base
- * class in order to be assignable to a type-erasing wrapper; they merely
- * need to satisfy a particular interface.
- * \li **Value semantics:** Type-erasing wrappers are objects that can be
- * passed around _by value_. This is in contrast to abstract base classes
- * which must be passed by reference or by pointer or else suffer from
- * _slicing_, which causes them to lose their polymorphic behaviors.
- * Reference semantics make it difficult to reason locally about code.
- * \li **Automatic memory management:** When dealing with inheritance-based
- * dynamic polymorphism, it is often necessary to allocate and manage
- * objects on the heap. This leads to a proliferation of `shared_ptr`s and
- * `unique_ptr`s in APIs, complicating their point-of-use. APIs that take
- * type-erasing wrappers, on the other hand, can often store small objects
- * in-situ, with no dynamic allocation. The memory management, if any, is
- * handled for you, and leads to cleaner APIs: consumers of your API don't
- * need to pass `shared_ptr<AbstractBase>`; they can simply pass any object
- * that satisfies the interface you require. (`std::function` is a
- * particularly compelling example of this benefit. Far worse would be an
- * inheritance-based callable solution like
- * `shared_ptr<ICallable<void(int)>>`. )
- *
- * \par Example: Defining a type-erasing function wrapper with `folly::Poly`
- *
- * \par
- * Defining a polymorphic wrapper with `Poly` is a matter of defining two
- * things:
- * \li An *interface*, consisting of public member functions, and
- * \li A *mapping* from a concrete type to a set of member function bindings.
- *
- * Below is a (heavily commented) example of a simple implementation of a
- * `std::function`-like polymorphic wrapper. Its interface has only a simgle
- * member function: `operator()`
- *
- * // An interface for a callable object of a particular signature, Fun
- * // (most interfaces don't need to be templates, FWIW).
- * template <class Fun>
- * struct IFunction;
- *
- * template <class R, class... As>
- * struct IFunction<R(As...)> {
- * // An interface is defined as a nested class template called
- * // Interface that takes a single template parameter, Base, from
- * // which it inherits.
- * template <class Base>
- * struct Interface : Base {
- * // The Interface has public member functions. These become the
- * // public interface of the resulting Poly instantiation.
- * // (Implementation note: Poly<IFunction<Sig>> will publicly
- * // inherit from this struct, which is what gives it the right
- * // member functions.)
- * R operator()(As... as) const {
- * // The definition of each member function in your interface will
- * // always consist of a single line dispatching to
- * // folly::poly_call<N>. The "N" corresponds to the N-th member
- * // function in the list of member function bindings, Members,
- * // defined below. The first argument will always be *this, and the
- * // rest of the arguments should simply forward (if necessary) the
- * // member function's arguments.
- * return static_cast<R>(
- * folly::poly_call<0>(*this, std::forward<As>(as)...));
- * }
- * };
- *
- * // The "Members" alias template is a comma-separated list of bound
- * // member functions for a given concrete type "T". The
- * // "FOLLY_POLY_MEMBERS" macro accepts a comma-separated list, and the
- * // (optional) "FOLLY_POLY_MEMBER" macro lets you disambiguate overloads
- * // by explicitly specifying the function signature the target member
- * // function should have. In this case, we require "T" to have a
- * // function call operator with the signature `R(As...) const`.
- * //
- * // If you are using a C++17-compatible compiler, you can do away with
- * // the macros and write this as:
- * //
- * // template <class T>
- * // using Members = folly::PolyMembers<
- * // folly::sig<R(As...) const>(&T::operator())>;
- * //
- * // And since `folly::sig` is only needed for disambiguation in case of
- * // overloads, if you are not concerned about objects with overloaded
- * // function call operators, it could be further simplified to:
- * //
- * // template <class T>
- * // using Members = folly::PolyMembers<&T::operator()>;
- * //
- * template <class T>
- * using Members = FOLLY_POLY_MEMBERS(
- * FOLLY_POLY_MEMBER(R(As...) const, &T::operator()));
- * };
- *
- * // Now that we have defined the interface, we can pass it to Poly to
- * // create our type-erasing wrapper:
- * template <class Fun>
- * using Function = Poly<IFunction<Fun>>;
- *
- * \par
- * Given the above definition of `Function`, users can now initialize instances
- * of (say) `Function<int(int, int)>` with function objects like
- * `std::plus<int>` and `std::multiplies<int>`, as below:
- *
- * Function<int(int, int)> fun = std::plus<int>{};
- * assert(5 == fun(2, 3));
- * fun = std::multiplies<int>{};
- * assert(6 = fun(2, 3));
- *
- * \par Defining an interface with C++17
- *
- * \par
- * With C++17, defining an interface to be used with `Poly` is fairly
- * straightforward. As in the `Function` example above, there is a struct with
- * a nested `Interface` class template and a nested `Members` alias template.
- * No macros are needed with C++17.
- * \par
- * Imagine we were defining something like a Java-style iterator. If we are
- * using a C++17 compiler, our interface would look something like this:
- *
- * template <class Value>
- * struct IJavaIterator {
- * template <class Base>
- * struct Interface : Base {
- * bool Done() const { return folly::poly_call<0>(*this); }
- * Value Current() const { return folly::poly_call<1>(*this); }
- * void Next() { folly::poly_call<2>(*this); }
- * };
- * // NOTE: This works in C++17 only:
- * template <class T>
- * using Members = folly::PolyMembers<&T::Done, &T::Current, &T::Next>;
- * };
- *
- * template <class Value>
- * using JavaIterator = Poly<IJavaIterator>;
- *
- * \par
- * Given the above definition, `JavaIterator<int>` can be used to hold instances
- * of any type that has `Done`, `Current`, and `Next` member functions with the
- * correct (or compatible) signatures.
- *
- * \par
- * The presence of overloaded member functions complicates this picture. Often,
- * property members are faked in C++ with `const` and non-`const` member
- * function overloads, like in the interface specified below:
- *
- * struct IIntProperty {
- * template <class Base>
- * struct Interface : Base {
- * int Value() const { return folly::poly_call<0>(*this); }
- * void Value(int i) { folly::poly_call<1>(*this, i); }
- * };
- * // NOTE: This works in C++17 only:
- * template <class T>
- * using Members = folly::PolyMembers<
- * folly::sig<int() const>(&T::Value),
- * folly::sig<void(int)>(&T::Value)>;
- * };
- *
- * using IntProperty = Poly<IIntProperty>;
- *
- * \par
- * Now, any object that has `Value` members of compatible signatures can be
- * assigned to instances of `IntProperty` object. Note how `folly::sig` is used
- * to disambiguate the overloads of `&T::Value`.
- *
- * \par Defining an interface with C++14
- *
- * \par
- * In C++14, the nice syntax above doesn't work, so we have to resort to macros.
- * The two examples above would look like this:
- *
- * template <class Value>
- * struct IJavaIterator {
- * template <class Base>
- * struct Interface : Base {
- * bool Done() const { return folly::poly_call<0>(*this); }
- * Value Current() const { return folly::poly_call<1>(*this); }
- * void Next() { folly::poly_call<2>(*this); }
- * };
- * // NOTE: This works in C++14 and C++17:
- * template <class T>
- * using Members = FOLLY_POLY_MEMBERS(&T::Done, &T::Current, &T::Next);
- * };
- *
- * template <class Value>
- * using JavaIterator = Poly<IJavaIterator>;
- *
- * \par
- * and
- *
- * struct IIntProperty {
- * template <class Base>
- * struct Interface : Base {
- * int Value() const { return folly::poly_call<0>(*this); }
- * void Value(int i) { return folly::poly_call<1>(*this, i); }
- * };
- * // NOTE: This works in C++14 and C++17:
- * template <class T>
- * using Members = FOLLY_POLY_MEMBERS(
- * FOLLY_POLY_MEMBER(int() const, &T::Value),
- * FOLLY_POLY_MEMBER(void(int), &T::Value));
- * };
- *
- * using IntProperty = Poly<IIntProperty>;
- *
- * \par Extending interfaces
- *
- * \par
- * One typical advantage of inheritance-based solutions to runtime polymorphism
- * is that one polymorphic interface could extend another through inheritance.
- * The same can be accomplished with type-erasing polymorphic wrappers. In
- * the `Poly` library, you can use `folly::PolyExtends` to say that one
- * interface extends another.
- *
- * struct IFoo {
- * template <class Base>
- * struct Interface : Base {
- * void Foo() const { return folly::poly_call<0>(*this); }
- * };
- * template <class T>
- * using Members = FOLLY_POLY_MEMBERS(&T::Foo);
- * };
- *
- * // The IFooBar interface extends the IFoo interface
- * struct IFooBar : PolyExtends<IFoo> {
- * template <class Base>
- * struct Interface : Base {
- * void Bar() const { return folly::poly_call<0>(*this); }
- * };
- * template <class T>
- * using Members = FOLLY_POLY_MEMBERS(&T::Bar);
- * };
- *
- * using FooBar = Poly<IFooBar>;
- *
- * \par
- * Given the above defintion, instances of type `FooBar` have both `Foo()` and
- * `Bar()` member functions.
- *
- * \par
- * The sensible conversions exist between a wrapped derived type and a wrapped
- * base type. For instance, assuming `IDerived` extends `IBase` with
- * `PolyExtends`:
- *
- * Poly<IDerived> derived = ...;
- * Poly<IBase> base = derived; // This conversion is OK.
- *
- * \par
- * As you would expect, there is no conversion in the other direction, and at
- * present there is no `Poly` equivalent to `dynamic_cast`.
- *
- * \par Type-erasing polymorphic reference wrappers
- *
- * \par
- * Sometimes you don't need to own a copy of an object; a reference will do. For
- * that you can use `Poly` to capture a _reference_ to an object satisfying an
- * interface rather than the whole object itself. The syntax is intuitive.
- *
- * int i = 42;
- * // Capture a mutable reference to an object of any IRegular type:
- * Poly<IRegular &> intRef = i;
- * assert(42 == folly::poly_cast<int>(intRef));
- * // Assert that we captured the address of "i":
- * assert(&i == &folly::poly_cast<int>(intRef));
- *
- * \par
- * A reference-like `Poly` has a different interface than a value-like `Poly`.
- * Rather than calling member functions with the `obj.fun()` syntax, you would
- * use the `obj->fun()` syntax. This is for the sake of `const`-correctness.
- * For example, consider the code below:
- *
- * struct IFoo {
- * template <class Base>
- * struct Interface {
- * void Foo() { folly::poly_call<0>(*this); }
- * };
- * template <class T>
- * using Members = folly::PolyMembers<&T::Foo>;
- * };
- *
- * struct SomeFoo {
- * void Foo() { std::printf("SomeFoo::Foo\n"); }
- * };
- *
- * SomeFoo foo;
- * Poly<IFoo &> const anyFoo = foo;
- * anyFoo->Foo(); // prints "SomeFoo::Foo"
- *
- * \par
- * Notice in the above code that the `Foo` member function is non-`const`.
- * Notice also that the `anyFoo` object is `const`. However, since it has
- * captured a non-`const` reference to the `foo` object, it should still be
- * possible to dispatch to the non-`const` `Foo` member function. When
- * instantiated with a reference type, `Poly` has an overloaded `operator->`
- * member that returns a pointer to the `IFoo` interface with the correct
- * `const`-ness, which makes this work.
- *
- * \par
- * The same mechanism also prevents users from calling non-`const` member
- * functions on `Poly` objects that have captured `const` references, which
- * would violate `const`-correctness.
- *
- * \par
- * Sensible conversions exist between non-reference and reference `Poly`s. For
- * instance:
- *
- * Poly<IRegular> value = 42;
- * Poly<IRegular &> mutable_ref = value;
- * Poly<IRegular const &> const_ref = mutable_ref;
- *
- * assert(&poly_cast<int>(value) == &poly_cast<int>(mutable_ref));
- * assert(&poly_cast<int>(value) == &poly_cast<int>(const_ref));
- *
- * \par Non-member functions (C++17)
- *
- * \par
- * If you wanted to write the interface `ILogicallyNegatable`, which captures
- * all types that can be negated with unary `operator!`, you could do it
- * as we've shown above, by binding `&T::operator!` in the nested `Members`
- * alias template, but that has the problem that it won't work for types that
- * have defined unary `operator!` as a free function. To handle this case,
- * the `Poly` library lets you use a free function instead of a member function
- * when creating a binding.
- *
- * \par
- * With C++17 you may use a lambda to create a binding, as shown in the example
- * below:
- *
- * struct ILogicallyNegatable {
- * template <class Base>
- * struct Interface : Base {
- * bool operator!() const { return folly::poly_call<0>(*this); }
- * };
- * template <class T>
- * using Members = folly::PolyMembers<
- * +[](T const& t) -> decltype(!t) { return !t; }>;
- * };
- *
- * \par
- * This requires some explanation. The unary `operator+` in front of the lambda
- * is necessary! It causes the lambda to decay to a C-style function pointer,
- * which is one of the types that `folly::PolyMembers` accepts. The `decltype`
- * in the lambda return type is also necessary. Through the magic of SFINAE, it
- * will cause `Poly<ILogicallyNegatable>` to reject any types that don't support
- * unary `operator!`.
- *
- * \par
- * If you are using a free function to create a binding, the first parameter is
- * implicitly the `this` parameter. It will receive the type-erased object.
- *
- * \par Non-member functions (C++14)
- *
- * \par
- * If you are using a C++14 compiler, the defintion of `ILogicallyNegatable`
- * above will fail because lambdas are not `constexpr`. We can get the same
- * effect by writing the lambda as a named free function, as show below:
- *
- * struct ILogicallyNegatable {
- * template <class Base>
- * struct Interface : Base {
- * bool operator!() const { return folly::poly_call<0>(*this); }
- * };
- *
- * template <class T>
- * static auto negate(T const& t) -> decltype(!t) { return !t; }
- *
- * template <class T>
- * using Members = FOLLY_POLY_MEMBERS(&negate<T>);
- * };
- *
- * \par
- * As with the example that uses the lambda in the preceding section, the first
- * parameter is implicitly the `this` parameter. It will receive the type-erased
- * object.
- *
- * \par Multi-dispatch
- *
- * \par
- * What if you want to create an `IAddable` interface for things that can be
- * added? Adding requires _two_ objects, both of which are type-erased. This
- * interface requires dispatching on both objects, doing the addition only
- * if the types are the same. For this we make use of the `PolySelf` template
- * alias to define an interface that takes more than one object of the the
- * erased type.
- *
- * struct IAddable {
- * template <class Base>
- * struct Interface : Base {
- * friend PolySelf<Base, Decay>
- * operator+(PolySelf<Base> const& a, PolySelf<Base> const& b) {
- * return folly::poly_call<0, IAddable>(a, b);
- * }
- * };
- *
- * template <class T>
- * using Members = folly::PolyMembers<
- * +[](T const& a, T const& b) -> decltype(a + b) { return a + b; }>;
- * };
- *
- * \par
- * Given the above defintion of `IAddable` we would be able to do the following:
- *
- * Poly<IAddable> a = 2, b = 3;
- * Poly<IAddable> c = a + b;
- * assert(poly_cast<int>(c) == 5);
- *
- * \par
- * If `a` and `b` stored objects of different types, a `BadPolyCast` exception
- * would be thrown.
- *
- * \par Move-only types
- *
- * \par
- * If you want to store move-only types, then your interface should extend the
- * `IMoveOnly` interface.
- *
- * \par Implementation notes
- * \par
- * `Poly` will store "small" objects in an internal buffer, avoiding the cost of
- * of dynamic allocations. At present, this size is not configurable; it is
- * pegged at the size of two `double`s.
- *
- * \par
- * `Poly` objects are always nothrow movable. If you store an object in one that
- * has a potentially throwing move contructor, the object will be stored on the
- * heap, even if it could fit in the internal storage of the `Poly` object.
- * (So be sure to give your objects nothrow move constructors!)
- *
- * \par
- * `Poly` implements type-erasure in a manner very similar to how the compiler
- * accomplishes virtual dispatch. Every `Poly` object contains a pointer to a
- * table of function pointers. Member function calls involve a double-
- * indirection: once through the v-pointer, and other indirect function call
- * through the function pointer.
- */
- template <class I>
- struct Poly final : detail::PolyValOrRef<I> {
- friend detail::PolyAccess;
- Poly() = default;
- using detail::PolyValOrRef<I>::PolyValOrRef;
- using detail::PolyValOrRef<I>::operator=;
- };
- /**
- * Swap two `Poly<I>` instances.
- */
- template <class I>
- void swap(Poly<I>& left, Poly<I>& right) noexcept {
- left.swap(right);
- }
- /**
- * Pseudo-function template handy for disambiguating function overloads.
- *
- * For example, given:
- * struct S {
- * int property() const;
- * void property(int);
- * };
- *
- * You can get a member function pointer to the first overload with:
- * folly::sig<int()const>(&S::property);
- *
- * This is arguably a nicer syntax that using the built-in `static_cast`:
- * static_cast<int (S::*)() const>(&S::property);
- *
- * `sig` is also more permissive than `static_cast` about `const`. For instance,
- * the following also works:
- * folly::sig<int()>(&S::property);
- *
- * The above is permitted
- */
- template <class Sig>
- FOLLY_INLINE_CONSTEXPR detail::Sig<Sig> const sig = {};
- } // namespace folly
- #include <folly/Poly-inl.h>
- #undef FOLLY_INLINE_CONSTEXPR
|