1 /* 2 * Copyright (C) 2016 The Android Open Source Project 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 #ifndef CHRE_UTIL_UNIQUE_PTR_H_ 18 #define CHRE_UTIL_UNIQUE_PTR_H_ 19 20 #include <cstddef> 21 22 #include "chre/util/non_copyable.h" 23 24 namespace chre { 25 26 /** 27 * Wraps a pointer to a dynamically allocated object and manages the underlying 28 * memory. The goal is to be similar to std::unique_ptr, but we do not support 29 * custom deleters - deletion is always done via memoryFree(). 30 */ 31 template<typename ObjectType> 32 class UniquePtr : public NonCopyable { 33 public: 34 /** 35 * Construct a UniquePtr instance that does not own any object. 36 */ 37 UniquePtr(); 38 39 /** 40 * Constructs a UniquePtr instance that owns the given object, and will free 41 * its memory when the UniquePtr is destructed. 42 * 43 * @param object Pointer to an object allocated via memoryAlloc. It is not 44 * valid for this object's memory to come from any other source, 45 * including the stack, or static allocation on the heap. 46 */ 47 UniquePtr(ObjectType *object); 48 49 /** 50 * Constructs a new UniquePtr via moving the Object from another UniquePtr. 51 * 52 * @param other UniquePtr instance to move into this object 53 */ 54 UniquePtr(UniquePtr<ObjectType>&& other); 55 56 /** 57 * Constructs a new UniquePtr via moving the Object from another UniquePtr. 58 * This constructor allows conversion (ie: upcast) to another type if 59 * possible. 60 * 61 * @param other UniquePtr instance to move and convert into this object. 62 */ 63 template<typename OtherObjectType> 64 UniquePtr(UniquePtr<OtherObjectType>&& other); 65 66 /** 67 * Deconstructs the object (if necessary) and releases associated memory. 68 */ 69 ~UniquePtr(); 70 71 /** 72 * Determines if this UniquePtr owns an object, or references null. 73 * 74 * @return true if get() returns nullptr 75 */ 76 bool isNull() const; 77 78 /** 79 * @return A pointer to the underlying object, or nullptr if this object is 80 * not currently valid. 81 */ 82 ObjectType *get() const; 83 84 /** 85 * Releases ownership of the underlying object, so it will not be freed when 86 * this object is destructed. After this function returns, get() will return 87 * nullptr. 88 * 89 * @return A pointer to the underlying object (i.e. what get() would return 90 * prior to this function call) 91 */ 92 ObjectType *release(); 93 94 /** 95 * Replaces the object owned by the UniquePtr by an object pointed by a given 96 * pointer. Also calls the destructor and releases the associated memory of 97 * the previously owned object. Invoking this method on the object managed by 98 * the UniquePtr, obtained via get(), is illegal. 99 * 100 * @param object the object to replace the ownership of the UniquePtr 101 */ 102 void reset(ObjectType *object); 103 104 /** 105 * @return A pointer to the underlying object. 106 */ 107 ObjectType *operator->() const; 108 109 /** 110 * @return A reference to the underlying object. 111 */ 112 ObjectType& operator*() const; 113 114 /** 115 * @param index The index of an object in the underlying array object. 116 * @return A reference to the underlying object at an index. 117 */ 118 ObjectType& operator[](size_t index) const; 119 120 /** 121 * Move assignment operator. Ownership of this object is transferred and the 122 * other object is left in an invalid state. 123 * 124 * @param other The other object being moved. 125 * @return A reference to the newly moved object. 126 */ 127 UniquePtr<ObjectType>& operator=(UniquePtr<ObjectType>&& other); 128 129 private: 130 // Befriend this class to itself to allow the templated conversion constructor 131 // permission to access mObject below. 132 template<typename OtherObjectType> 133 friend class UniquePtr; 134 135 //! A pointer to the underlying storage for this object. 136 ObjectType *mObject; 137 }; 138 139 /** 140 * Allocates and constructs a new object of type ObjectType on the heap, and 141 * returns a UniquePtr that owns the object. This function is similar to 142 * std::make_unique. 143 * 144 * @param args The arguments to pass to the object's constructor. 145 */ 146 template<typename ObjectType, typename... Args> 147 UniquePtr<ObjectType> MakeUnique(Args&&... args); 148 149 /** 150 * Just like MakeUnique(), except it zeros out any allocated memory. Intended to 151 * be used for creating objects that have trivial constructors (e.g. C structs) 152 * but should start with a known state. 153 */ 154 template<typename ObjectType> 155 UniquePtr<ObjectType> MakeUniqueZeroFill(); 156 157 } // namespace chre 158 159 #include "chre/util/unique_ptr_impl.h" 160 161 #endif // CHRE_UTIL_UNIQUE_PTR_H_ 162