cannam@148: // Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
cannam@148: // Licensed under the MIT License:
cannam@148: //
cannam@148: // Permission is hereby granted, free of charge, to any person obtaining a copy
cannam@148: // of this software and associated documentation files (the "Software"), to deal
cannam@148: // in the Software without restriction, including without limitation the rights
cannam@148: // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
cannam@148: // copies of the Software, and to permit persons to whom the Software is
cannam@148: // furnished to do so, subject to the following conditions:
cannam@148: //
cannam@148: // The above copyright notice and this permission notice shall be included in
cannam@148: // all copies or substantial portions of the Software.
cannam@148: //
cannam@148: // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
cannam@148: // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
cannam@148: // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
cannam@148: // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
cannam@148: // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
cannam@148: // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
cannam@148: // THE SOFTWARE.
cannam@148: 
cannam@148: #ifndef KJ_MEMORY_H_
cannam@148: #define KJ_MEMORY_H_
cannam@148: 
cannam@148: #if defined(__GNUC__) && !KJ_HEADER_WARNINGS
cannam@148: #pragma GCC system_header
cannam@148: #endif
cannam@148: 
cannam@148: #include "common.h"
cannam@148: 
cannam@148: namespace kj {
cannam@148: 
cannam@148: // =======================================================================================
cannam@148: // Disposer -- Implementation details.
cannam@148: 
cannam@148: class Disposer {
cannam@148:   // Abstract interface for a thing that "disposes" of objects, where "disposing" usually means
cannam@148:   // calling the destructor followed by freeing the underlying memory.  `Own<T>` encapsulates an
cannam@148:   // object pointer with corresponding Disposer.
cannam@148:   //
cannam@148:   // Few developers will ever touch this interface.  It is primarily useful for those implementing
cannam@148:   // custom memory allocators.
cannam@148: 
cannam@148: protected:
cannam@148:   // Do not declare a destructor, as doing so will force a global initializer for each HeapDisposer
cannam@148:   // instance.  Eww!
cannam@148: 
cannam@148:   virtual void disposeImpl(void* pointer) const = 0;
cannam@148:   // Disposes of the object, given a pointer to the beginning of the object.  If the object is
cannam@148:   // polymorphic, this pointer is determined by dynamic_cast<void*>().  For non-polymorphic types,
cannam@148:   // Own<T> does not allow any casting, so the pointer exactly matches the original one given to
cannam@148:   // Own<T>.
cannam@148: 
cannam@148: public:
cannam@148: 
cannam@148:   template <typename T>
cannam@148:   void dispose(T* object) const;
cannam@148:   // Helper wrapper around disposeImpl().
cannam@148:   //
cannam@148:   // If T is polymorphic, calls `disposeImpl(dynamic_cast<void*>(object))`, otherwise calls
cannam@148:   // `disposeImpl(implicitCast<void*>(object))`.
cannam@148:   //
cannam@148:   // Callers must not call dispose() on the same pointer twice, even if the first call throws
cannam@148:   // an exception.
cannam@148: 
cannam@148: private:
cannam@148:   template <typename T, bool polymorphic = __is_polymorphic(T)>
cannam@148:   struct Dispose_;
cannam@148: };
cannam@148: 
cannam@148: template <typename T>
cannam@148: class DestructorOnlyDisposer: public Disposer {
cannam@148:   // A disposer that merely calls the type's destructor and nothing else.
cannam@148: 
cannam@148: public:
cannam@148:   static const DestructorOnlyDisposer instance;
cannam@148: 
cannam@148:   void disposeImpl(void* pointer) const override {
cannam@148:     reinterpret_cast<T*>(pointer)->~T();
cannam@148:   }
cannam@148: };
cannam@148: 
cannam@148: template <typename T>
cannam@148: const DestructorOnlyDisposer<T> DestructorOnlyDisposer<T>::instance = DestructorOnlyDisposer<T>();
cannam@148: 
cannam@148: class NullDisposer: public Disposer {
cannam@148:   // A disposer that does nothing.
cannam@148: 
cannam@148: public:
cannam@148:   static const NullDisposer instance;
cannam@148: 
cannam@148:   void disposeImpl(void* pointer) const override {}
cannam@148: };
cannam@148: 
cannam@148: // =======================================================================================
cannam@148: // Own<T> -- An owned pointer.
cannam@148: 
cannam@148: template <typename T>
cannam@148: class Own {
cannam@148:   // A transferrable title to a T.  When an Own<T> goes out of scope, the object's Disposer is
cannam@148:   // called to dispose of it.  An Own<T> can be efficiently passed by move, without relocating the
cannam@148:   // underlying object; this transfers ownership.
cannam@148:   //
cannam@148:   // This is much like std::unique_ptr, except:
cannam@148:   // - You cannot release().  An owned object is not necessarily allocated with new (see next
cannam@148:   //   point), so it would be hard to use release() correctly.
cannam@148:   // - The deleter is made polymorphic by virtual call rather than by template.  This is much
cannam@148:   //   more powerful -- it allows the use of custom allocators, freelists, etc.  This could
cannam@148:   //   _almost_ be accomplished with unique_ptr by forcing everyone to use something like
cannam@148:   //   std::unique_ptr<T, kj::Deleter>, except that things get hairy in the presence of multiple
cannam@148:   //   inheritance and upcasting, and anyway if you force everyone to use a custom deleter
cannam@148:   //   then you've lost any benefit to interoperating with the "standard" unique_ptr.
cannam@148: 
cannam@148: public:
cannam@148:   KJ_DISALLOW_COPY(Own);
cannam@148:   inline Own(): disposer(nullptr), ptr(nullptr) {}
cannam@148:   inline Own(Own&& other) noexcept
cannam@148:       : disposer(other.disposer), ptr(other.ptr) { other.ptr = nullptr; }
cannam@148:   inline Own(Own<RemoveConstOrDisable<T>>&& other) noexcept
cannam@148:       : disposer(other.disposer), ptr(other.ptr) { other.ptr = nullptr; }
cannam@148:   template <typename U, typename = EnableIf<canConvert<U*, T*>()>>
cannam@148:   inline Own(Own<U>&& other) noexcept
cannam@148:       : disposer(other.disposer), ptr(other.ptr) {
cannam@148:     static_assert(__is_polymorphic(T),
cannam@148:         "Casting owned pointers requires that the target type is polymorphic.");
cannam@148:     other.ptr = nullptr;
cannam@148:   }
cannam@148:   inline Own(T* ptr, const Disposer& disposer) noexcept: disposer(&disposer), ptr(ptr) {}
cannam@148: 
cannam@148:   ~Own() noexcept(false) { dispose(); }
cannam@148: 
cannam@148:   inline Own& operator=(Own&& other) {
cannam@148:     // Move-assingnment operator.
cannam@148: 
cannam@148:     // Careful, this might own `other`.  Therefore we have to transfer the pointers first, then
cannam@148:     // dispose.
cannam@148:     const Disposer* disposerCopy = disposer;
cannam@148:     T* ptrCopy = ptr;
cannam@148:     disposer = other.disposer;
cannam@148:     ptr = other.ptr;
cannam@148:     other.ptr = nullptr;
cannam@148:     if (ptrCopy != nullptr) {
cannam@148:       disposerCopy->dispose(const_cast<RemoveConst<T>*>(ptrCopy));
cannam@148:     }
cannam@148:     return *this;
cannam@148:   }
cannam@148: 
cannam@148:   inline Own& operator=(decltype(nullptr)) {
cannam@148:     dispose();
cannam@148:     return *this;
cannam@148:   }
cannam@148: 
cannam@148:   template <typename U>
cannam@148:   Own<U> downcast() {
cannam@148:     // Downcast the pointer to Own<U>, destroying the original pointer.  If this pointer does not
cannam@148:     // actually point at an instance of U, the results are undefined (throws an exception in debug
cannam@148:     // mode if RTTI is enabled, otherwise you're on your own).
cannam@148: 
cannam@148:     Own<U> result;
cannam@148:     if (ptr != nullptr) {
cannam@148:       result.ptr = &kj::downcast<U>(*ptr);
cannam@148:       result.disposer = disposer;
cannam@148:       ptr = nullptr;
cannam@148:     }
cannam@148:     return result;
cannam@148:   }
cannam@148: 
cannam@148: #define NULLCHECK KJ_IREQUIRE(ptr != nullptr, "null Own<> dereference")
cannam@148:   inline T* operator->() { NULLCHECK; return ptr; }
cannam@148:   inline const T* operator->() const { NULLCHECK; return ptr; }
cannam@148:   inline T& operator*() { NULLCHECK; return *ptr; }
cannam@148:   inline const T& operator*() const { NULLCHECK; return *ptr; }
cannam@148: #undef NULLCHECK
cannam@148:   inline T* get() { return ptr; }
cannam@148:   inline const T* get() const { return ptr; }
cannam@148:   inline operator T*() { return ptr; }
cannam@148:   inline operator const T*() const { return ptr; }
cannam@148: 
cannam@148: private:
cannam@148:   const Disposer* disposer;  // Only valid if ptr != nullptr.
cannam@148:   T* ptr;
cannam@148: 
cannam@148:   inline explicit Own(decltype(nullptr)): disposer(nullptr), ptr(nullptr) {}
cannam@148: 
cannam@148:   inline bool operator==(decltype(nullptr)) { return ptr == nullptr; }
cannam@148:   inline bool operator!=(decltype(nullptr)) { return ptr != nullptr; }
cannam@148:   // Only called by Maybe<Own<T>>.
cannam@148: 
cannam@148:   inline void dispose() {
cannam@148:     // Make sure that if an exception is thrown, we are left with a null ptr, so we won't possibly
cannam@148:     // dispose again.
cannam@148:     T* ptrCopy = ptr;
cannam@148:     if (ptrCopy != nullptr) {
cannam@148:       ptr = nullptr;
cannam@148:       disposer->dispose(const_cast<RemoveConst<T>*>(ptrCopy));
cannam@148:     }
cannam@148:   }
cannam@148: 
cannam@148:   template <typename U>
cannam@148:   friend class Own;
cannam@148:   friend class Maybe<Own<T>>;
cannam@148: };
cannam@148: 
cannam@148: namespace _ {  // private
cannam@148: 
cannam@148: template <typename T>
cannam@148: class OwnOwn {
cannam@148: public:
cannam@148:   inline OwnOwn(Own<T>&& value) noexcept: value(kj::mv(value)) {}
cannam@148: 
cannam@148:   inline Own<T>& operator*() & { return value; }
cannam@148:   inline const Own<T>& operator*() const & { return value; }
cannam@148:   inline Own<T>&& operator*() && { return kj::mv(value); }
cannam@148:   inline const Own<T>&& operator*() const && { return kj::mv(value); }
cannam@148:   inline Own<T>* operator->() { return &value; }
cannam@148:   inline const Own<T>* operator->() const { return &value; }
cannam@148:   inline operator Own<T>*() { return value ? &value : nullptr; }
cannam@148:   inline operator const Own<T>*() const { return value ? &value : nullptr; }
cannam@148: 
cannam@148: private:
cannam@148:   Own<T> value;
cannam@148: };
cannam@148: 
cannam@148: template <typename T>
cannam@148: OwnOwn<T> readMaybe(Maybe<Own<T>>&& maybe) { return OwnOwn<T>(kj::mv(maybe.ptr)); }
cannam@148: template <typename T>
cannam@148: Own<T>* readMaybe(Maybe<Own<T>>& maybe) { return maybe.ptr ? &maybe.ptr : nullptr; }
cannam@148: template <typename T>
cannam@148: const Own<T>* readMaybe(const Maybe<Own<T>>& maybe) { return maybe.ptr ? &maybe.ptr : nullptr; }
cannam@148: 
cannam@148: }  // namespace _ (private)
cannam@148: 
cannam@148: template <typename T>
cannam@148: class Maybe<Own<T>> {
cannam@148: public:
cannam@148:   inline Maybe(): ptr(nullptr) {}
cannam@148:   inline Maybe(Own<T>&& t) noexcept: ptr(kj::mv(t)) {}
cannam@148:   inline Maybe(Maybe&& other) noexcept: ptr(kj::mv(other.ptr)) {}
cannam@148: 
cannam@148:   template <typename U>
cannam@148:   inline Maybe(Maybe<Own<U>>&& other): ptr(mv(other.ptr)) {}
cannam@148:   template <typename U>
cannam@148:   inline Maybe(Own<U>&& other): ptr(mv(other)) {}
cannam@148: 
cannam@148:   inline Maybe(decltype(nullptr)) noexcept: ptr(nullptr) {}
cannam@148: 
cannam@148:   inline operator Maybe<T&>() { return ptr.get(); }
cannam@148:   inline operator Maybe<const T&>() const { return ptr.get(); }
cannam@148: 
cannam@148:   inline Maybe& operator=(Maybe&& other) { ptr = kj::mv(other.ptr); return *this; }
cannam@148: 
cannam@148:   inline bool operator==(decltype(nullptr)) const { return ptr == nullptr; }
cannam@148:   inline bool operator!=(decltype(nullptr)) const { return ptr != nullptr; }
cannam@148: 
cannam@148:   Own<T>& orDefault(Own<T>& defaultValue) {
cannam@148:     if (ptr == nullptr) {
cannam@148:       return defaultValue;
cannam@148:     } else {
cannam@148:       return ptr;
cannam@148:     }
cannam@148:   }
cannam@148:   const Own<T>& orDefault(const Own<T>& defaultValue) const {
cannam@148:     if (ptr == nullptr) {
cannam@148:       return defaultValue;
cannam@148:     } else {
cannam@148:       return ptr;
cannam@148:     }
cannam@148:   }
cannam@148: 
cannam@148:   template <typename Func>
cannam@148:   auto map(Func&& f) & -> Maybe<decltype(f(instance<Own<T>&>()))> {
cannam@148:     if (ptr == nullptr) {
cannam@148:       return nullptr;
cannam@148:     } else {
cannam@148:       return f(ptr);
cannam@148:     }
cannam@148:   }
cannam@148: 
cannam@148:   template <typename Func>
cannam@148:   auto map(Func&& f) const & -> Maybe<decltype(f(instance<const Own<T>&>()))> {
cannam@148:     if (ptr == nullptr) {
cannam@148:       return nullptr;
cannam@148:     } else {
cannam@148:       return f(ptr);
cannam@148:     }
cannam@148:   }
cannam@148: 
cannam@148:   template <typename Func>
cannam@148:   auto map(Func&& f) && -> Maybe<decltype(f(instance<Own<T>&&>()))> {
cannam@148:     if (ptr == nullptr) {
cannam@148:       return nullptr;
cannam@148:     } else {
cannam@148:       return f(kj::mv(ptr));
cannam@148:     }
cannam@148:   }
cannam@148: 
cannam@148:   template <typename Func>
cannam@148:   auto map(Func&& f) const && -> Maybe<decltype(f(instance<const Own<T>&&>()))> {
cannam@148:     if (ptr == nullptr) {
cannam@148:       return nullptr;
cannam@148:     } else {
cannam@148:       return f(kj::mv(ptr));
cannam@148:     }
cannam@148:   }
cannam@148: 
cannam@148: private:
cannam@148:   Own<T> ptr;
cannam@148: 
cannam@148:   template <typename U>
cannam@148:   friend class Maybe;
cannam@148:   template <typename U>
cannam@148:   friend _::OwnOwn<U> _::readMaybe(Maybe<Own<U>>&& maybe);
cannam@148:   template <typename U>
cannam@148:   friend Own<U>* _::readMaybe(Maybe<Own<U>>& maybe);
cannam@148:   template <typename U>
cannam@148:   friend const Own<U>* _::readMaybe(const Maybe<Own<U>>& maybe);
cannam@148: };
cannam@148: 
cannam@148: namespace _ {  // private
cannam@148: 
cannam@148: template <typename T>
cannam@148: class HeapDisposer final: public Disposer {
cannam@148: public:
cannam@148:   virtual void disposeImpl(void* pointer) const override { delete reinterpret_cast<T*>(pointer); }
cannam@148: 
cannam@148:   static const HeapDisposer instance;
cannam@148: };
cannam@148: 
cannam@148: template <typename T>
cannam@148: const HeapDisposer<T> HeapDisposer<T>::instance = HeapDisposer<T>();
cannam@148: 
cannam@148: }  // namespace _ (private)
cannam@148: 
cannam@148: template <typename T, typename... Params>
cannam@148: Own<T> heap(Params&&... params) {
cannam@148:   // heap<T>(...) allocates a T on the heap, forwarding the parameters to its constructor.  The
cannam@148:   // exact heap implementation is unspecified -- for now it is operator new, but you should not
cannam@148:   // assume this.  (Since we know the object size at delete time, we could actually implement an
cannam@148:   // allocator that is more efficient than operator new.)
cannam@148: 
cannam@148:   return Own<T>(new T(kj::fwd<Params>(params)...), _::HeapDisposer<T>::instance);
cannam@148: }
cannam@148: 
cannam@148: template <typename T>
cannam@148: Own<Decay<T>> heap(T&& orig) {
cannam@148:   // Allocate a copy (or move) of the argument on the heap.
cannam@148:   //
cannam@148:   // The purpose of this overload is to allow you to omit the template parameter as there is only
cannam@148:   // one argument and the purpose is to copy it.
cannam@148: 
cannam@148:   typedef Decay<T> T2;
cannam@148:   return Own<T2>(new T2(kj::fwd<T>(orig)), _::HeapDisposer<T2>::instance);
cannam@148: }
cannam@148: 
cannam@148: // =======================================================================================
cannam@148: // SpaceFor<T> -- assists in manual allocation
cannam@148: 
cannam@148: template <typename T>
cannam@148: class SpaceFor {
cannam@148:   // A class which has the same size and alignment as T but does not call its constructor or
cannam@148:   // destructor automatically.  Instead, call construct() to construct a T in the space, which
cannam@148:   // returns an Own<T> which will take care of calling T's destructor later.
cannam@148: 
cannam@148: public:
cannam@148:   inline SpaceFor() {}
cannam@148:   inline ~SpaceFor() {}
cannam@148: 
cannam@148:   template <typename... Params>
cannam@148:   Own<T> construct(Params&&... params) {
cannam@148:     ctor(value, kj::fwd<Params>(params)...);
cannam@148:     return Own<T>(&value, DestructorOnlyDisposer<T>::instance);
cannam@148:   }
cannam@148: 
cannam@148: private:
cannam@148:   union {
cannam@148:     T value;
cannam@148:   };
cannam@148: };
cannam@148: 
cannam@148: // =======================================================================================
cannam@148: // Inline implementation details
cannam@148: 
cannam@148: template <typename T>
cannam@148: struct Disposer::Dispose_<T, true> {
cannam@148:   static void dispose(T* object, const Disposer& disposer) {
cannam@148:     // Note that dynamic_cast<void*> does not require RTTI to be enabled, because the offset to
cannam@148:     // the top of the object is in the vtable -- as it obviously needs to be to correctly implement
cannam@148:     // operator delete.
cannam@148:     disposer.disposeImpl(dynamic_cast<void*>(object));
cannam@148:   }
cannam@148: };
cannam@148: template <typename T>
cannam@148: struct Disposer::Dispose_<T, false> {
cannam@148:   static void dispose(T* object, const Disposer& disposer) {
cannam@148:     disposer.disposeImpl(static_cast<void*>(object));
cannam@148:   }
cannam@148: };
cannam@148: 
cannam@148: template <typename T>
cannam@148: void Disposer::dispose(T* object) const {
cannam@148:   Dispose_<T>::dispose(object, *this);
cannam@148: }
cannam@148: 
cannam@148: }  // namespace kj
cannam@148: 
cannam@148: #endif  // KJ_MEMORY_H_