util/custom_allocator.hpp

   1 /*
   2  * Copyright (c) 2020 Arm Limited.
   3  *
   4  * SPDX-License-Identifier: MIT
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a copy
   7  * of this software and associated documentation files (the "Software"), to
   8  * deal in the Software without restriction, including without limitation the
   9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  10  * sell copies of the Software, and to permit persons to whom the Software is
  11  * furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included in all
  14  * copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  22  * SOFTWARE.
  23  */
  24
  25 #include <new>
  26 #include <vector>
  27 #include <string>
  28 #include <cassert>
  29
  30 #include <vulkan/vulkan.h>
  31
  32 #pragma once
  33
  34 namespace util
  35 {
  36
  37 /**
  38  * @brief Minimalistic wrapper of VkAllocationCallbacks.
  39  */
  40 class allocator
  41 {
  42 public:
  43    /**
  44     * @brief Construct a new wrapper for the given VK callbacks and scope.
  45     * @param callbacks Pointer to allocation callbacks. If this is @c nullptr, then default
  46     *   allocation callbacks are used. These can be accessed through #m_callbacks.
  47     * @param scope The scope to use for this allocator.
  48     */
  49    allocator(const VkAllocationCallbacks *callbacks, VkSystemAllocationScope scope);
  50
  51    /**
  52     * @brief Get a pointer to the allocation callbacks provided while constructing this object.
  53     * @return a copy of the #VkAllocationCallback argument provided in the allocator constructor
  54     *   or @c nullptr if this argument was provided as @c nullptr.
  55     * @note The #m_callbacks member is always populated with callable pointers for pfnAllocation,
  56     *   pfnReallocation and pfnFree.
  57     */
  58    const VkAllocationCallbacks *get_original_callbacks() const;
  59
  60    /**
  61     * @brief Helper method to allocate and construct objects with a custom allocator.
  62     * @param num_objects Number of objects to create.
  63     * @return Pointer to the newly created objects or @c nullptr if allocation failed.
  64     */
  65    template <typename T, typename... arg_types>
  66    T *create(size_t num_objects, arg_types &&... args) const noexcept;
  67
  68    /**
  69     * @brief Helper method to destroy and deallocate objects constructed with allocator::create().
  70     * @param num_objects Number of objects to destroy.
  71     */
  72    template <typename T>
  73    void destroy(size_t num_objects, T *obj) const noexcept;
  74
  75    VkAllocationCallbacks m_callbacks;
  76    VkSystemAllocationScope m_scope;
  77 };
  78
  79 /**
  80  * @brief Implementation of an allocator that can be used with STL containers.
  81  */
  82 template <typename T>
  83 class custom_allocator
  84 {
  85 public:
  86    using value_type = T;
  87    using pointer = T *;
  88
  89    custom_allocator(const allocator &alloc)
  90       : m_alloc(alloc)
  91    {
  92    }
  93
  94    template <typename U>
  95    custom_allocator(const custom_allocator<U> &other)
  96       : m_alloc(other.get_data())
  97    {
  98    }
  99
 100    const allocator &get_data() const
 101    {
 102       return m_alloc;
 103    }
 104
 105    pointer allocate(size_t n) const
 106    {
 107       size_t size = n * sizeof(T);
 108       auto &cb = m_alloc.m_callbacks;
 109       void *ret = cb.pfnAllocation(cb.pUserData, size, alignof(T), m_alloc.m_scope);
 110       if (ret == nullptr)
 111          throw std::bad_alloc();
 112       return reinterpret_cast<pointer>(ret);
 113    }
 114
 115    pointer allocate(size_t n, void *ptr) const
 116    {
 117       size_t size = n * sizeof(T);
 118       auto &cb = m_alloc.m_callbacks;
 119       void *ret = cb.pfnReallocation(cb.pUserData, ptr, size, alignof(T), m_alloc.m_scope);
 120       if (ret == nullptr)
 121          throw std::bad_alloc();
 122       return reinterpret_cast<pointer>(ret);
 123    }
 124
 125    void deallocate(void *ptr, size_t) const noexcept
 126    {
 127       m_alloc.m_callbacks.pfnFree(m_alloc.m_callbacks.pUserData, ptr);
 128    }
 129
 130 private:
 131    const allocator m_alloc;
 132 };
 133
 134 template <typename T, typename U>
 135 bool operator==(const custom_allocator<T> &, const custom_allocator<U> &)
 136 {
 137    return true;
 138 }
 139
 140 template <typename T, typename U>
 141 bool operator!=(const custom_allocator<T> &, const custom_allocator<U> &)
 142 {
 143    return false;
 144 }
 145
 146 template <typename T, typename... arg_types>
 147 T *allocator::create(size_t num_objects, arg_types &&... args) const noexcept
 148 {
 149    if (num_objects < 1)
 150    {
 151       return nullptr;
 152    }
 153
 154    custom_allocator<T> allocator(*this);
 155    T *ptr;
 156    try
 157    {
 158       ptr = allocator.allocate(num_objects);
 159    }
 160    catch (...)
 161    {
 162       return nullptr;
 163    }
 164
 165    size_t objects_constructed = 0;
 166    try
 167    {
 168       while (objects_constructed < num_objects)
 169       {
 170          T *next_object = &ptr[objects_constructed];
 171          new (next_object) T(std::forward<arg_types>(args)...);
 172          objects_constructed++;
 173       }
 174    }
 175    catch (...)
 176    {
 177       /* We catch all exceptions thrown while constructing the object, not just
 178        * std::bad_alloc.
 179        */
 180       while (objects_constructed > 0)
 181       {
 182          objects_constructed--;
 183          ptr[objects_constructed].~T();
 184       }
 185       allocator.deallocate(ptr, num_objects);
 186       return nullptr;
 187    }
 188    return ptr;
 189 }
 190
 191 template <typename T>
 192 void allocator::destroy(size_t num_objects, T *objects) const noexcept
 193 {
 194    assert((objects == nullptr) == (num_objects == 0));
 195    if (num_objects == 0)
 196    {
 197       return;
 198    }
 199
 200    custom_allocator<T> allocator(*this);
 201    for (size_t i = 0; i < num_objects; i++)
 202    {
 203       objects[i].~T();
 204    }
 205    allocator.deallocate(objects, num_objects);
 206 }
 207
 208 template <typename T>
 209 void destroy_custom(T *obj)
 210 {
 211    T::destroy(obj);
 212 }
 213
 214 /**
 215  * @brief Vector using a Vulkan custom allocator to allocate its elements.
 216  * @note The vector must be passed a custom_allocator during construction and it takes a copy
 217  *   of it, meaning that the user is free to destroy the custom_allocator after constructing the
 218  *   vector.
 219  */
 220 template <typename T>
 221 class vector : public std::vector<T, custom_allocator<T>>
 222 {
 223 public:
 224    using base = std::vector<T, custom_allocator<T>>;
 225    using base::base;
 226
 227    /* Delete all methods that can cause allocation failure, i.e. can throw std::bad_alloc.
 228     *
 229     * Rationale: we want to force users to use our corresponding try_... method instead:
 230     * this makes the API slightly more annoying to use, but hopefully safer as it encourages
 231     * users to check for allocation failures, which is important for Vulkan.
 232     *
 233     * Note: deleting each of these methods (below) deletes all its overloads from the base class,
 234     *   to be precise: the deleted method covers the methods (all overloads) in the base class.
 235     * Note: clear() is already noexcept since C++11.
 236     */
 237    void insert() = delete;
 238    void emplace() = delete;
 239    void emplace_back() = delete;
 240    void push_back() = delete;
 241    void resize() = delete;
 242    void reserve() = delete;
 243
 244    /* Note pop_back(), erase(), clear() do not throw std::bad_alloc exceptions. */
 245
 246    /* @brief Like std::vector::push_back, but non throwing.
 247     * @return @c false iff the operation could not be performed due to an allocation failure.
 248     */
 249    template <typename... arg_types>
 250    bool try_push_back(arg_types &&... args) noexcept
 251    {
 252       try
 253       {
 254          base::push_back(std::forward<arg_types>(args)...);
 255          return true;
 256       }
 257       catch (const std::bad_alloc &e)
 258       {
 259          return false;
 260       }
 261    }
 262
 263    /* @brief push back multiple elements at once
 264     * @return @c false iff the operation could not be performed due to an allocation failure.
 265     */
 266    bool try_push_back_many(const T *begin, const T *end) noexcept
 267    {
 268       for (const T *it = begin; it != end; ++it)
 269       {
 270          if (!try_push_back(*it))
 271          {
 272             return false;
 273          }
 274       }
 275       return true;
 276    }
 277
 278    /* @brief Like std::vector::resize, but non throwing.
 279     * @return @c false iff the operation could not be performed due to an allocation failure.
 280     */
 281    template <typename... arg_types>
 282    bool try_resize(arg_types &&... args) noexcept
 283    {
 284       try
 285       {
 286          base::resize(std::forward<arg_types>(args)...);
 287          return true;
 288       }
 289       catch (const std::bad_alloc &e)
 290       {
 291          return false;
 292       }
 293    }
 294 };
 295
 296 } /* namespace util */