1 /* ------------------------------------------------------------------ 2 * Copyright (C) 1998-2009 PacketVideo 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 13 * express or implied. 14 * See the License for the specific language governing permissions 15 * and limitations under the License. 16 * ------------------------------------------------------------------- 17 */ 18 // -*- c++ -*- 19 // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 20 21 // O S C L _ E X C L U S I V E _ P T R 22 23 // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 24 25 /*! \addtogroup osclbase OSCL Base 26 * 27 * @{ 28 */ 29 30 31 32 /** 33 * @file oscl_exclusive_ptr.h 34 * @brief This file defines the OsclExclusivePtr template class. This class is 35 * used to avoid any potential memory leaks that may arise while returning 36 * from methods in case of error. 37 * 38 */ 39 40 #ifndef OSCL_EXCLUSIVE_PTR_H_INCLUDED 41 #define OSCL_EXCLUSIVE_PTR_H_INCLUDED 42 43 #ifndef OSCL_DEFALLOC_H_INCLUDED 44 #include "oscl_defalloc.h" 45 #endif 46 47 #ifndef OSCL_BASE_H_INCLUDED 48 #include "oscl_base.h" 49 #endif 50 51 /** 52 * @brief The OsclExclusivePtr class is a template class that defines a pointer 53 * like object intended to be assigned an address obtanined (directly or 54 * or indirectly) by new. When the OsclExclusivePtr expires, its destructor 55 * uses delete to free the memory. 56 * 57 * The purpose of this class is to provide a way to prevent accidental memory 58 * leaks in a class or a method, due to "not remembering to delete" variables 59 * allocated on the heap. Thus if you assign an address returned by new to an 60 * OsclExclusivePtr object, you don't have to remember to free the memory later, 61 * it will be freed automatically when the object goes out of scope. 62 * The OsclExclusivePtr is an example of a smart pointer, an object that acts like 63 * a pointer, but with additional features. The class is defined so that it acts 64 * like a regular pointer in most respects 65 * 66 */ 67 68 template<class T> class OsclExclusivePtr 69 { 70 protected: 71 T* _Ptr; 72 73 public: 74 75 /** 76 * @brief Default constructor 77 * Initializes the pointer and takes ownership. 78 */ _Ptr(inPtr)79 explicit OsclExclusivePtr(T* inPtr = 0) : _Ptr(inPtr) {}; 80 81 /** 82 * @brief Copy constructor 83 * 84 * Initializes the pointer and takes ownership from another OsclExclusivePtr. 85 * Note that the other class does NOT own the pointer any longer, and 86 * hence it is NOT its responsibility to free it. 87 */ OsclExclusivePtr(OsclExclusivePtr<T> & _Y)88 OsclExclusivePtr(OsclExclusivePtr<T>& _Y): _Ptr(_Y.release()) {}; 89 90 91 /** 92 * @brief Assignment operator from an another OsclExclusivePtr 93 * 94 * @param _Y The value parameter should be another OsclExclusivePtr 95 * @returns Returns a reference to this OsclExclusivePtr instance with 96 * pointer initialized. 97 * @pre The input class should be non-null and should point to 98 * a valid pointer. 99 * 100 * This assignment operator initializes the class to the contents 101 * of the OsclExclusivePtr given as the input parameter. The ownership 102 * of the pointer is transferred. 103 */ 104 OsclExclusivePtr<T>& operator=(OsclExclusivePtr<T>& _Y) 105 { 106 if (this != &_Y) 107 { 108 if (_Ptr != _Y.get()) 109 { 110 delete _Ptr; 111 } 112 _Ptr = _Y.release(); 113 } 114 return (*this); 115 } 116 117 /** 118 * @brief Destructor 119 * 120 * The pointer is deleted in case this class still has ownership 121 */ ~OsclExclusivePtr()122 virtual ~OsclExclusivePtr() 123 { 124 if (_Ptr) 125 delete _Ptr; 126 } 127 128 /** 129 * @brief The indirection operator (*) accesses a value indirectly, 130 * through a pointer 131 * 132 * This operator ensures that the OsclExclusivePtr can be used like the 133 * regular pointer that it was initialized with. 134 */ 135 T& operator*() const 136 { 137 return (*get()); 138 } 139 140 /** 141 * @brief The indirection operator (->) accesses a value indirectly, 142 * through a pointer 143 * 144 * This operator ensures that the OsclExclusivePtr can be used like the 145 * regular pointer that it was initialized with. 146 */ 147 T *operator->() const 148 { 149 return (get()); 150 } 151 152 /** 153 * @brief get() method returns the pointer, currently owned by the class. 154 * 155 */ get()156 T *get() const 157 { 158 return (_Ptr); 159 } 160 161 /** 162 * @brief release() method releases ownership of the pointer, currently owned 163 * by the class. It returns the pointer as well. 164 * 165 */ release()166 T *release() 167 { 168 T *tmp = _Ptr; 169 _Ptr = NULL; 170 return (tmp); 171 } 172 173 /** 174 * @brief set() method sets ownership to the pointer, passed. 175 * This method is needed when the class is created with a default 176 * constructor. Returns false in case the class is non-empty. 177 * 178 */ set(T * ptr)179 bool set(T* ptr) 180 { 181 if ((_Ptr == NULL)) 182 { 183 _Ptr = ptr; 184 return true; 185 } 186 return false; 187 } 188 189 }; 190 191 /** 192 * @brief The OsclExclusiveArrayPtr class is a template class that defines an array pointer 193 * like object intended to be assigned an address obtanined (directly or 194 * or indirectly) by new. When the OsclExclusiveArrayPtr expires, its destructor 195 * uses delete to free the memory. 196 * 197 * The purpose of this class is to provide a way to prevent accidental memory 198 * leaks in a class or a method, due to "not remembering to delete" variables 199 * allocated on the heap. Thus if you assign an address returned by new to an 200 * OsclExclusivePtr object, you don't have to remember to free the memory later, 201 * it will be freed automatically when the object goes out of scope. 202 * The OsclExclusivePtr is an example of a smart pointer, an object that acts like 203 * a pointer, but with additional features. The class is defined so that it acts 204 * like a regular pointer in most respects 205 * 206 */ 207 template<class T> class OsclExclusiveArrayPtr 208 { 209 protected: 210 T* _Ptr; 211 212 public: 213 214 /** 215 * @brief Default constructor 216 * Initializes the pointer and takes ownership. 217 */ _Ptr(inPtr)218 explicit OsclExclusiveArrayPtr(T* inPtr = 0) : _Ptr(inPtr) {}; 219 220 /** 221 * @brief Copy constructor 222 * 223 * Initializes the pointer and takes ownership from another OsclExclusiveArrayPtr. 224 * Note that the other class does NOT own the pointer any longer, and 225 * hence it is NOT its responsibility to free it. 226 */ OsclExclusiveArrayPtr(OsclExclusiveArrayPtr<T> & _Y)227 OsclExclusiveArrayPtr(OsclExclusiveArrayPtr<T>& _Y): _Ptr(_Y.release()) {}; 228 229 230 /** 231 * @brief Assignment operator from an another OsclExclusiveArrayPtr 232 * 233 * @param _Y The value parameter should be another OsclExclusiveArrayPtr 234 * @returns Returns a reference to this OsclExclusiveArrayPtr instance with 235 * pointer initialized. 236 * @pre The input class should be non-null and should point to 237 * a valid pointer. 238 * 239 * This assignment operator initializes the class to the contents 240 * of the OsclExclusiveArrayPtr given as the input parameter. The ownership 241 * of the pointer is transferred. 242 */ 243 OsclExclusiveArrayPtr<T>& operator=(OsclExclusiveArrayPtr<T>& _Y) 244 { 245 if (this != &_Y) 246 { 247 if (_Ptr != _Y.get()) 248 { 249 delete [] _Ptr; 250 } 251 _Ptr = _Y.release(); 252 } 253 return (*this); 254 } 255 256 /** 257 * @brief Destructor 258 * 259 * The pointer is deleted in case this class still has ownership 260 */ ~OsclExclusiveArrayPtr()261 virtual ~OsclExclusiveArrayPtr() 262 { 263 if (_Ptr) 264 delete [] _Ptr; 265 } 266 267 /** 268 * @brief The indirection operator (*) accesses a value indirectly, 269 * through a pointer 270 * 271 * This operator ensures that the OsclExclusiveArrayPtr can be used like the 272 * regular pointer that it was initialized with. 273 */ 274 T& operator*() const 275 { 276 return (*get()); 277 } 278 279 /** 280 * @brief The indirection operator (->) accesses a value indirectly, 281 * through a pointer 282 * 283 * This operator ensures that the OsclExclusiveArrayPtr can be used like the 284 * regular pointer that it was initialized with. 285 */ 286 T *operator->() const 287 { 288 return (get()); 289 } 290 291 /** 292 * @brief get() method returns the pointer, currently owned by the class. 293 * 294 */ get()295 T *get() const 296 { 297 return (_Ptr); 298 } 299 300 /** 301 * @brief release() method releases ownership of the pointer, currently owned 302 * by the class. It returns the pointer as well. 303 * 304 */ release()305 T *release() 306 { 307 T *tmp = _Ptr; 308 _Ptr = NULL; 309 return (tmp); 310 } 311 312 /** 313 * @brief set() method sets ownership to the pointer, passed. 314 * This method is needed when the class is created with a default 315 * constructor. Returns false in case the class is non-empty. 316 * 317 */ set(T * ptr)318 bool set(T* ptr) 319 { 320 if ((_Ptr == NULL)) 321 { 322 _Ptr = ptr; 323 return true; 324 } 325 return false; 326 } 327 328 }; 329 330 331 /** 332 * @brief The OsclExclusivePtrA class is a template class that defines any pointer 333 * like object intended to be assigned an address obtanined (directly or 334 * or indirectly) through Alloc. When the OsclExclusivePtrA expires, Alloc 335 * is used to free the memory. 336 * 337 * The purpose of this class is to provide a way to prevent accidental memory 338 * leaks in a class or a method, due to "not remembering to delete" variables 339 * allocated on the heap. Thus if you assign an address returned by new to an 340 * OsclExclusivePtr object, you don't have to remember to free the memory later, 341 * it will be freed automatically when the object goes out of scope. 342 * The OsclExclusivePtr is an example of a smart pointer, an object that acts like 343 * a pointer, but with additional features. The class is defined so that it acts 344 * like a regular pointer in most respects 345 * 346 */ 347 template<class T, class Alloc> class OsclExclusivePtrA 348 { 349 protected: 350 T* _Ptr; 351 352 public: 353 354 /** 355 * @brief Default constructor 356 * Initializes the pointer and takes ownership. 357 */ _Ptr(inPtr)358 explicit OsclExclusivePtrA(T* inPtr = 0) : _Ptr(inPtr) {}; 359 360 /** 361 * @brief Copy constructor 362 * 363 * Initializes the pointer and takes ownership from another OsclExclusiveArrayPtr. 364 * Note that the other class does NOT own the pointer any longer, and 365 * hence it is NOT its responsibility to free it. 366 */ OsclExclusivePtrA(OsclExclusivePtrA<T,Alloc> & _Y)367 OsclExclusivePtrA(OsclExclusivePtrA<T, Alloc>& _Y): _Ptr(_Y.release()) {}; 368 369 370 /** 371 * @brief Assignment operator from an another OsclExclusiveArrayPtr 372 * 373 * @param _Y The value parameter should be another OsclExclusiveArrayPtr 374 * @returns Returns a reference to this OsclExclusiveArrayPtr instance with 375 * pointer initialized. 376 * @pre The input class should be non-null and should point to 377 * a valid pointer. 378 * 379 * This assignment operator initializes the class to the contents 380 * of the OsclExclusiveArrayPtr given as the input parameter. The ownership 381 * of the pointer is transferred. 382 */ 383 OsclExclusivePtrA<T, Alloc>& operator=(OsclExclusivePtrA<T, Alloc>& _Y) 384 { 385 if (this != &_Y) 386 { 387 if (_Ptr != _Y.get()) 388 { 389 defAlloc.deallocate(_Ptr); 390 } 391 _Ptr = _Y.release(); 392 } 393 return (*this); 394 } 395 396 /** 397 * @brief Destructor 398 * 399 * The pointer is deleted in case this class still has ownership 400 */ ~OsclExclusivePtrA()401 virtual ~OsclExclusivePtrA() 402 { 403 defAlloc.deallocate(_Ptr); 404 } 405 406 /** 407 * @brief The indirection operator (*) accesses a value indirectly, 408 * through a pointer 409 * 410 * This operator ensures that the OsclExclusiveArrayPtr can be used like the 411 * regular pointer that it was initialized with. 412 */ 413 T& operator*() const 414 { 415 return (*get()); 416 } 417 418 /** 419 * @brief The indirection operator (->) accesses a value indirectly, 420 * through a pointer 421 * 422 * This operator ensures that the OsclExclusiveArrayPtr can be used like the 423 * regular pointer that it was initialized with. 424 */ 425 T *operator->() const 426 { 427 return (get()); 428 } 429 430 /** 431 * @brief get() method returns the pointer, currently owned by the class. 432 * 433 */ get()434 T *get() const 435 { 436 return (_Ptr); 437 } 438 439 /** 440 * @brief release() method releases ownership of the pointer, currently owned 441 * by the class. It returns the pointer as well. 442 * 443 */ release()444 T *release() 445 { 446 T *tmp = _Ptr; 447 _Ptr = NULL; 448 return (tmp); 449 } 450 451 /** 452 * @brief set() method sets ownership to the pointer, passed. 453 * This method is needed when the class is created with a default 454 * constructor. Returns false in case the class is non-empty. 455 * 456 */ set(T * ptr)457 bool set(T* ptr) 458 { 459 if ((_Ptr == NULL)) 460 { 461 _Ptr = ptr; 462 return true; 463 } 464 return false; 465 } 466 467 private: 468 Oscl_TAlloc<T, Alloc> defAlloc; 469 }; 470 471 /*! @} */ 472 473 474 #endif //OSCL_EXCLUSIVE_PTR_H_INCLUDED 475 476