llvm/ADT/PagedVector.h

0001 //===- llvm/ADT/PagedVector.h - 'Lazily allocated' vectors --*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 // This file defines the PagedVector class.
0010 //
0011 //===----------------------------------------------------------------------===//
0012 #ifndef LLVM_ADT_PAGEDVECTOR_H
0013 #define LLVM_ADT_PAGEDVECTOR_H
0014
0015 #include "llvm/ADT/PointerIntPair.h"
0016 #include "llvm/ADT/SmallVector.h"
0017 #include "llvm/ADT/iterator_range.h"
0018 #include "llvm/Support/Allocator.h"
0019 #include <cassert>
0020 #include <vector>
0021
0022 namespace llvm {
0023 /// A vector that allocates memory in pages.
0024 ///
0025 /// Order is kept, but memory is allocated only when one element of the page is
0026 /// accessed. This introduces a level of indirection, but it is useful when you
0027 /// have a sparsely initialised vector where the full size is allocated upfront.
0028 ///
0029 /// As a side effect the elements are initialised later than in a normal vector.
0030 /// On the first access to one of the elements of a given page, all the elements
0031 /// of the page are initialised. This also means that the elements of the page
0032 /// are initialised beyond the size of the vector.
0033 ///
0034 /// Similarly on destruction the elements are destroyed only when the page is
0035 /// not needed anymore, delaying invoking the destructor of the elements.
0036 ///
0037 /// Notice that this has iterators only on materialized elements. This
0038 /// is deliberately done under the assumption you would dereference the elements
0039 /// while iterating, therefore materialising them and losing the gains in terms
0040 /// of memory usage this container provides. If you have such a use case, you
0041 /// probably want to use a normal std::vector or a llvm::SmallVector.
0042 template <typename T, size_t PageSize = 1024 / sizeof(T)> class PagedVector {
0043   static_assert(PageSize > 1, "PageSize must be greater than 0. Most likely "
0044                               "you want it to be greater than 16.");
0045   /// The actual number of elements in the vector which can be accessed.
0046   size_t Size = 0;
0047
0048   /// The position of the initial element of the page in the Data vector.
0049   /// Pages are allocated contiguously in the Data vector.
0050   mutable SmallVector<T *, 0> PageToDataPtrs;
0051   /// Actual page data. All the page elements are allocated on the
0052   /// first access of any of the elements of the page. Elements are default
0053   /// constructed and elements of the page are stored contiguously.
0054   PointerIntPair<BumpPtrAllocator *, 1, bool> Allocator;
0055
0056 public:
0057   using value_type = T;
0058
0059   /// Default constructor. We build our own allocator and mark it as such with
0060   /// `true` in the second pair element.
0061   PagedVector() : Allocator(new BumpPtrAllocator, true) {}
0062   explicit PagedVector(BumpPtrAllocator *A) : Allocator(A, false) {
0063     assert(A && "Allocator cannot be nullptr");
0064   }
0065
0066   ~PagedVector() {
0067     clear();
0068     // If we own the allocator, delete it.
0069     if (Allocator.getInt())
0070       delete Allocator.getPointer();
0071   }
0072
0073   // Forbid copy and move as we do not need them for the current use case.
0074   PagedVector(const PagedVector &) = delete;
0075   PagedVector(PagedVector &&) = delete;
0076   PagedVector &operator=(const PagedVector &) = delete;
0077   PagedVector &operator=(PagedVector &&) = delete;
0078
0079   /// Look up an element at position `Index`.
0080   /// If the associated page is not filled, it will be filled with default
0081   /// constructed elements.
0082   T &operator[](size_t Index) const {
0083     assert(Index < Size);
0084     assert(Index / PageSize < PageToDataPtrs.size());
0085     T *&PagePtr = PageToDataPtrs[Index / PageSize];
0086     // If the page was not yet allocated, allocate it.
0087     if (LLVM_UNLIKELY(!PagePtr)) {
0088       PagePtr = Allocator.getPointer()->template Allocate<T>(PageSize);
0089       // We need to invoke the default constructor on all the elements of the
0090       // page.
0091       std::uninitialized_value_construct_n(PagePtr, PageSize);
0092     }
0093     // Dereference the element in the page.
0094     return PagePtr[Index % PageSize];
0095   }
0096
0097   /// Return the capacity of the vector. I.e. the maximum size it can be
0098   /// expanded to with the resize method without allocating more pages.
0099   [[nodiscard]] size_t capacity() const {
0100     return PageToDataPtrs.size() * PageSize;
0101   }
0102
0103   /// Return the size of the vector.
0104   [[nodiscard]] size_t size() const { return Size; }
0105
0106   /// Resize the vector. Notice that the constructor of the elements will not
0107   /// be invoked until an element of a given page is accessed, at which point
0108   /// all the elements of the page will be constructed.
0109   ///
0110   /// If the new size is smaller than the current size, the elements of the
0111   /// pages that are not needed anymore will be destroyed, however, elements of
0112   /// the last page will not be destroyed.
0113   ///
0114   /// For these reason the usage of this vector is discouraged if you rely
0115   /// on the construction / destructor of the elements to be invoked.
0116   void resize(size_t NewSize) {
0117     if (NewSize == 0) {
0118       clear();
0119       return;
0120     }
0121     // Handle shrink case: destroy the elements in the pages that are not
0122     // needed any more and deallocate the pages.
0123     //
0124     // On the other hand, we do not destroy the extra elements in the last page,
0125     // because we might need them later and the logic is simpler if we do not
0126     // destroy them. This means that elements are only destroyed when the
0127     // page they belong to is destroyed. This is similar to what happens on
0128     // access of the elements of a page, where all the elements of the page are
0129     // constructed not only the one effectively needed.
0130     size_t NewLastPage = (NewSize - 1) / PageSize;
0131     if (NewSize < Size) {
0132       for (size_t I = NewLastPage + 1, N = PageToDataPtrs.size(); I < N; ++I) {
0133         T *Page = PageToDataPtrs[I];
0134         if (!Page)
0135           continue;
0136         // We need to invoke the destructor on all the elements of the page.
0137         std::destroy_n(Page, PageSize);
0138         Allocator.getPointer()->Deallocate(Page);
0139       }
0140     }
0141
0142     Size = NewSize;
0143     PageToDataPtrs.resize(NewLastPage + 1);
0144   }
0145
0146   [[nodiscard]] bool empty() const { return Size == 0; }
0147
0148   /// Clear the vector, i.e. clear the allocated pages, the whole page
0149   /// lookup index and reset the size.
0150   void clear() {
0151     Size = 0;
0152     for (T *Page : PageToDataPtrs) {
0153       if (Page == nullptr)
0154         continue;
0155       std::destroy_n(Page, PageSize);
0156       // If we do not own the allocator, deallocate the pages one by one.
0157       if (!Allocator.getInt())
0158         Allocator.getPointer()->Deallocate(Page);
0159     }
0160     // If we own the allocator, simply reset it.
0161     if (Allocator.getInt())
0162       Allocator.getPointer()->Reset();
0163     PageToDataPtrs.clear();
0164   }
0165
0166   /// Iterator on all the elements of the vector
0167   /// which have actually being constructed.
0168   class MaterializedIterator {
0169     const PagedVector *PV;
0170     size_t ElementIdx;
0171
0172   public:
0173     using iterator_category = std::forward_iterator_tag;
0174     using value_type = T;
0175     using difference_type = std::ptrdiff_t;
0176     using pointer = T *;
0177     using reference = T &;
0178
0179     MaterializedIterator(PagedVector const *PV, size_t ElementIdx)
0180         : PV(PV), ElementIdx(ElementIdx) {}
0181
0182     /// Pre-increment operator.
0183     ///
0184     /// When incrementing the iterator, we skip the elements which have not
0185     /// been materialized yet.
0186     MaterializedIterator &operator++() {
0187       ++ElementIdx;
0188       if (ElementIdx % PageSize == 0) {
0189         while (ElementIdx < PV->Size &&
0190                !PV->PageToDataPtrs[ElementIdx / PageSize])
0191           ElementIdx += PageSize;
0192         if (ElementIdx > PV->Size)
0193           ElementIdx = PV->Size;
0194       }
0195
0196       return *this;
0197     }
0198
0199     MaterializedIterator operator++(int) {
0200       MaterializedIterator Copy = *this;
0201       ++*this;
0202       return Copy;
0203     }
0204
0205     T const &operator*() const {
0206       assert(ElementIdx < PV->Size);
0207       assert(PV->PageToDataPtrs[ElementIdx / PageSize]);
0208       T *PagePtr = PV->PageToDataPtrs[ElementIdx / PageSize];
0209       return PagePtr[ElementIdx % PageSize];
0210     }
0211
0212     /// Equality operator.
0213     friend bool operator==(const MaterializedIterator &LHS,
0214                            const MaterializedIterator &RHS) {
0215       return LHS.equals(RHS);
0216     }
0217
0218     [[nodiscard]] size_t getIndex() const { return ElementIdx; }
0219
0220     friend bool operator!=(const MaterializedIterator &LHS,
0221                            const MaterializedIterator &RHS) {
0222       return !(LHS == RHS);
0223     }
0224
0225   private:
0226     void verify() const {
0227       assert(
0228           ElementIdx == PV->Size ||
0229           (ElementIdx < PV->Size && PV->PageToDataPtrs[ElementIdx / PageSize]));
0230     }
0231
0232     bool equals(const MaterializedIterator &Other) const {
0233       assert(PV == Other.PV);
0234       verify();
0235       Other.verify();
0236       return ElementIdx == Other.ElementIdx;
0237     }
0238   };
0239
0240   /// Iterators over the materialized elements of the vector.
0241   ///
0242   /// This includes all the elements belonging to allocated pages,
0243   /// even if they have not been accessed yet. It's enough to access
0244   /// one element of a page to materialize all the elements of the page.
0245   MaterializedIterator materialized_begin() const {
0246     // Look for the first valid page.
0247     for (size_t ElementIdx = 0; ElementIdx < Size; ElementIdx += PageSize)
0248       if (PageToDataPtrs[ElementIdx / PageSize])
0249         return MaterializedIterator(this, ElementIdx);
0250
0251     return MaterializedIterator(this, Size);
0252   }
0253
0254   MaterializedIterator materialized_end() const {
0255     return MaterializedIterator(this, Size);
0256   }
0257
0258   [[nodiscard]] llvm::iterator_range<MaterializedIterator>
0259   materialized() const {
0260     return {materialized_begin(), materialized_end()};
0261   }
0262 };
0263 } // namespace llvm
0264 #endif // LLVM_ADT_PAGEDVECTOR_H