1 /* 2 * Copyright (c) 2021, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * This file includes definitions for `Heap::Allocatable`. 32 */ 33 34 #ifndef HEAP_ALLOCATABLE_HPP_ 35 #define HEAP_ALLOCATABLE_HPP_ 36 37 #include "openthread-core-config.h" 38 39 #include "common/code_utils.hpp" 40 #include "common/error.hpp" 41 #include "common/heap.hpp" 42 #include "common/new.hpp" 43 44 namespace ot { 45 namespace Heap { 46 47 /** 48 * Defines a `Heap::Allocatable` object. 49 * 50 * `Heap::Allocatable` provides methods to allocate and free instances of `Type` on heap. 51 * 52 * Users of this class should follow CRTP-style inheritance, i.e., the `Type` class itself should inherit from 53 * `Allocatable<Type>`. 54 * 55 * The `Type` class destructor is used when `Free()` is called. The destructor frees any heap allocated data members 56 * that are stored in a `Type` instance (e.g., `Heap::String`, `Heap::Data`, etc). 57 */ 58 template <class Type> class Allocatable 59 { 60 public: 61 /** 62 * Allocates a new instance of `Type` on heap and initializes it using `Type` constructor. 63 * 64 * The `Type` class MUST have a constructor `Type(Args...)` which is invoked upon allocation of new `Type` to 65 * initialize it. 66 * 67 * @param[in] aArgs A set of arguments to pass to the `Type` constructor of the allocated `Type` instance. 68 * 69 * @returns A pointer to the newly allocated instance or `nullptr` if it fails to allocate. 70 */ Allocate(Args &&...aArgs)71 template <typename... Args> static Type *Allocate(Args &&...aArgs) 72 { 73 void *buf = Heap::CAlloc(1, sizeof(Type)); 74 75 return (buf != nullptr) ? new (buf) Type(static_cast<Args &&>(aArgs)...) : nullptr; 76 } 77 78 /** 79 * Allocates a new instance of `Type` on heap and initializes it using `Type::Init()` method. 80 * 81 * The `Type` class MUST have a default constructor (with no arguments) which is invoked upon allocation of new 82 * `Type` instance. It MUST also provide an `Error Init(Args...)` method to initialize the instance. If any `Error` 83 * other than `kErrorNone` is returned the initialization is considered failed. 84 * 85 * @param[in] aArgs A set of arguments to initialize the allocated `Type` instance. 86 * 87 * @returns A pointer to the newly allocated instance or `nullptr` if it fails to allocate or initialize. 88 */ AllocateAndInit(Args &&...aArgs)89 template <typename... Args> static Type *AllocateAndInit(Args &&...aArgs) 90 { 91 void *buf = Heap::CAlloc(1, sizeof(Type)); 92 Type *object = nullptr; 93 94 VerifyOrExit(buf != nullptr); 95 96 object = new (buf) Type(); 97 98 if (object->Init(static_cast<Args &&>(aArgs)...) != kErrorNone) 99 { 100 object->Free(); 101 object = nullptr; 102 } 103 104 exit: 105 return object; 106 } 107 108 /** 109 * Frees the `Type` instance. 110 * 111 * The instance MUST be heap allocated using either `Allocate()` or `AllocateAndInit()`. 112 * 113 * The `Free()` method invokes the `Type` destructor before releasing the allocated heap buffer for the instance. 114 * This ensures that any heap allocated member variables in `Type` are freed before the `Type` instance itself is 115 * freed. 116 */ Free(void)117 void Free(void) 118 { 119 static_cast<Type *>(this)->~Type(); 120 Heap::Free(this); 121 } 122 123 protected: 124 Allocatable(void) = default; 125 }; 126 127 } // namespace Heap 128 } // namespace ot 129 130 #endif // HEAP_ALLOCATABLE_HPP_ 131