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 * Pointer type of ObjectType. 36 */ 37 typedef ObjectType* pointer; 38 39 /** 40 * Construct a UniquePtr instance that does not own any object. 41 */ 42 UniquePtr(); 43 44 /** 45 * Constructs a UniquePtr instance that owns the given object, and will free 46 * its memory when the UniquePtr is destructed. 47 * 48 * @param object Pointer to an object allocated via memoryAlloc. It is not 49 * valid for this object's memory to come from any other source, 50 * including the stack, or static allocation on the heap. 51 */ 52 UniquePtr(ObjectType *object); 53 54 /** 55 * Constructs a new UniquePtr via moving the Object from another UniquePtr. 56 * 57 * @param other UniquePtr instance to move into this object 58 */ 59 UniquePtr(UniquePtr<ObjectType>&& other); 60 61 /** 62 * Constructs a new UniquePtr via moving the Object from another UniquePtr. 63 * This constructor allows conversion (ie: upcast) to another type if 64 * possible. 65 * 66 * @param other UniquePtr instance to move and convert into this object. 67 */ 68 template<typename OtherObjectType> 69 UniquePtr(UniquePtr<OtherObjectType>&& other); 70 71 /** 72 * Deconstructs the object (if necessary) and releases associated memory. 73 */ 74 ~UniquePtr(); 75 76 /** 77 * Determines if this UniquePtr owns an object, or references null. 78 * 79 * @return true if get() returns nullptr 80 */ 81 bool isNull() const; 82 83 /** 84 * @return A pointer to the underlying object, or nullptr if this object is 85 * not currently valid. 86 */ 87 ObjectType *get() const; 88 89 /** 90 * Releases ownership of the underlying object, so it will not be freed when 91 * this object is destructed. After this function returns, get() will return 92 * nullptr. 93 * 94 * @return A pointer to the underlying object (i.e. what get() would return 95 * prior to this function call) 96 */ 97 ObjectType *release(); 98 99 /** 100 * Replaces the object owned by the UniquePtr by an object pointed by a given 101 * pointer. Also calls the destructor and releases the associated memory of 102 * the previously owned object. Invoking this method on the object managed by 103 * the UniquePtr, obtained via get(), is illegal. 104 * 105 * @param object the object to replace the ownership of the UniquePtr 106 */ 107 void reset(ObjectType *object); 108 109 /** 110 * Destroys the object owned by the UniquePtr. Also calls the destructor and 111 * releases the associated memory of the previously owned object. 112 */ 113 void reset(); 114 115 /** 116 * @return A pointer to the underlying object. 117 */ 118 ObjectType *operator->() const; 119 120 /** 121 * @return A reference to the underlying object. 122 */ 123 ObjectType& operator*() const; 124 125 /** 126 * @param index The index of an object in the underlying array object. 127 * @return A reference to the underlying object at an index. 128 */ 129 ObjectType& operator[](size_t index) const; 130 131 /** 132 * Move assignment operator. Ownership of this object is transferred and the 133 * other object is left in an invalid state. 134 * 135 * @param other The other object being moved. 136 * @return A reference to the newly moved object. 137 */ 138 UniquePtr<ObjectType>& operator=(UniquePtr<ObjectType>&& other); 139 140 /** 141 * Two unique_ptr compare equal (==) if their stored pointers compare equal, 142 * and not equal (!=) otherwise. 143 * 144 * @param other The other object being compared. 145 * @return true if the other's pointer is same as the underlying pointer, 146 * otherwise false. 147 */ 148 bool operator==(const UniquePtr<ObjectType> &other) const; 149 150 /** 151 * Two unique_ptr compare equal (==) if their stored pointers compare equal, 152 * and not equal (!=) otherwise. 153 * 154 * @param other The other object being compared. 155 * @return true if the other's pointer is different than the underlying 156 * pointer, otherwise false. 157 */ 158 bool operator!=(const UniquePtr<ObjectType> &other) const; 159 160 private: 161 // Befriend this class to itself to allow the templated conversion constructor 162 // permission to access mObject below. 163 template<typename OtherObjectType> 164 friend class UniquePtr; 165 166 //! A pointer to the underlying storage for this object. 167 ObjectType *mObject; 168 }; 169 170 /** 171 * Allocates and constructs a new object of type ObjectType on the heap, and 172 * returns a UniquePtr that owns the object. This function is similar to 173 * std::make_unique. 174 * 175 * @param args The arguments to pass to the object's constructor. 176 */ 177 template<typename ObjectType, typename... Args> 178 UniquePtr<ObjectType> MakeUnique(Args&&... args); 179 180 /** 181 * Just like MakeUnique(), except it zeros out any allocated memory. Intended to 182 * be used for creating objects that have trivial constructors (e.g. C structs) 183 * but should start with a known state. 184 */ 185 template<typename ObjectType> 186 UniquePtr<ObjectType> MakeUniqueZeroFill(); 187 188 } // namespace chre 189 190 #include "chre/util/unique_ptr_impl.h" 191 192 #endif // CHRE_UTIL_UNIQUE_PTR_H_ 193