js/public/GCVector.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: set ts=8 sts=2 et sw=2 tw=80:
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef js_GCVector_h
   8 #define js_GCVector_h
   9
  10 #include "mozilla/Vector.h"
  11
  12 #include "js/GCPolicyAPI.h"
  13 #include "js/RootingAPI.h"
  14 #include "js/TracingAPI.h"
  15 #include "js/Vector.h"
  16
  17 namespace JS {
  18
  19 // A GCVector is a Vector with an additional trace method that knows how
  20 // to visit all of the items stored in the Vector. For vectors that contain GC
  21 // things, this is usually more convenient than manually iterating and marking
  22 // the contents.
  23 //
  24 // Most types of GC pointers as keys and values can be traced with no extra
  25 // infrastructure. For structs and non-gc-pointer members, ensure that there is
  26 // a specialization of GCPolicy<T> with an appropriate trace method available
  27 // to handle the custom type. Generic helpers can be found in
  28 // js/public/TracingAPI.h.
  29 //
  30 // Note that although this Vector's trace will deal correctly with moved items,
  31 // it does not itself know when to barrier or trace items. To function properly
  32 // it must either be used with Rooted, or barriered and traced manually.
  33 template <typename T, size_t MinInlineCapacity = 0,
  34           typename AllocPolicy = js::TempAllocPolicy>
  35 class GCVector {
  36   mozilla::Vector<T, MinInlineCapacity, AllocPolicy> vector;
  37
  38  public:
  39   using ElementType = T;
  40
  41   explicit GCVector(AllocPolicy alloc = AllocPolicy())
  42       : vector(std::move(alloc)) {}
  43
  44   GCVector(GCVector&& vec) : vector(std::move(vec.vector)) {}
  45
  46   GCVector& operator=(GCVector&& vec) {
  47     vector = std::move(vec.vector);
  48     return *this;
  49   }
  50
  51   size_t length() const { return vector.length(); }
  52   bool empty() const { return vector.empty(); }
  53   size_t capacity() const { return vector.capacity(); }
  54
  55   T* begin() { return vector.begin(); }
  56   const T* begin() const { return vector.begin(); }
  57
  58   T* end() { return vector.end(); }
  59   const T* end() const { return vector.end(); }
  60
  61   T& operator[](size_t i) { return vector[i]; }
  62   const T& operator[](size_t i) const { return vector[i]; }
  63
  64   T& back() { return vector.back(); }
  65   const T& back() const { return vector.back(); }
  66
  67   bool initCapacity(size_t cap) { return vector.initCapacity(cap); }
  68   MOZ_MUST_USE bool reserve(size_t req) { return vector.reserve(req); }
  69   void shrinkBy(size_t amount) { return vector.shrinkBy(amount); }
  70   MOZ_MUST_USE bool growBy(size_t amount) { return vector.growBy(amount); }
  71   MOZ_MUST_USE bool resize(size_t newLen) { return vector.resize(newLen); }
  72
  73   void clear() { return vector.clear(); }
  74   void clearAndFree() { return vector.clearAndFree(); }
  75
  76   template <typename U>
  77   bool append(U&& item) {
  78     return vector.append(std::forward<U>(item));
  79   }
  80
  81   template <typename... Args>
  82   MOZ_MUST_USE bool emplaceBack(Args&&... args) {
  83     return vector.emplaceBack(std::forward<Args>(args)...);
  84   }
  85
  86   template <typename U>
  87   void infallibleAppend(U&& aU) {
  88     return vector.infallibleAppend(std::forward<U>(aU));
  89   }
  90   void infallibleAppendN(const T& aT, size_t aN) {
  91     return vector.infallibleAppendN(aT, aN);
  92   }
  93   template <typename U>
  94   void infallibleAppend(const U* aBegin, const U* aEnd) {
  95     return vector.infallibleAppend(aBegin, aEnd);
  96   }
  97   template <typename U>
  98   void infallibleAppend(const U* aBegin, size_t aLength) {
  99     return vector.infallibleAppend(aBegin, aLength);
 100   }
 101
 102   template <typename U>
 103   MOZ_MUST_USE bool appendAll(const U& aU) {
 104     return vector.append(aU.begin(), aU.end());
 105   }
 106
 107   MOZ_MUST_USE bool appendN(const T& val, size_t count) {
 108     return vector.appendN(val, count);
 109   }
 110
 111   template <typename U>
 112   MOZ_MUST_USE bool append(const U* aBegin, const U* aEnd) {
 113     return vector.append(aBegin, aEnd);
 114   }
 115   template <typename U>
 116   MOZ_MUST_USE bool append(const U* aBegin, size_t aLength) {
 117     return vector.append(aBegin, aLength);
 118   }
 119
 120   void popBack() { return vector.popBack(); }
 121   T popCopy() { return vector.popCopy(); }
 122
 123   size_t sizeOfExcludingThis(mozilla::MallocSizeOf mallocSizeOf) const {
 124     return vector.sizeOfExcludingThis(mallocSizeOf);
 125   }
 126
 127   size_t sizeOfIncludingThis(mozilla::MallocSizeOf mallocSizeOf) const {
 128     return vector.sizeOfIncludingThis(mallocSizeOf);
 129   }
 130
 131   static void trace(GCVector* vec, JSTracer* trc) { vec->trace(trc); }
 132
 133   void trace(JSTracer* trc) {
 134     for (auto& elem : vector) {
 135       GCPolicy<T>::trace(trc, &elem, "vector element");
 136     }
 137   }
 138
 139   bool needsSweep() const { return !this->empty(); }
 140
 141   void sweep() {
 142     uint32_t src, dst = 0;
 143     for (src = 0; src < length(); src++) {
 144       if (!GCPolicy<T>::needsSweep(&vector[src])) {
 145         if (dst != src) {
 146           vector[dst] = vector[src].unbarrieredGet();
 147         }
 148         dst++;
 149       }
 150     }
 151
 152     if (dst != length()) {
 153       vector.shrinkTo(dst);
 154     }
 155   }
 156 };
 157
 158 // AllocPolicy is optional. It has a default value declared in TypeDecls.h
 159 template <typename T, typename AllocPolicy>
 160 class MOZ_STACK_CLASS StackGCVector : public GCVector<T, 8, AllocPolicy> {
 161  public:
 162   using Base = GCVector<T, 8, AllocPolicy>;
 163
 164  private:
 165   // Inherit constructor from GCVector.
 166   using Base::Base;
 167 };
 168
 169 }  // namespace JS
 170
 171 namespace js {
 172
 173 template <typename Wrapper, typename T, size_t Capacity, typename AllocPolicy>
 174 class WrappedPtrOperations<JS::GCVector<T, Capacity, AllocPolicy>, Wrapper> {
 175   using Vec = JS::GCVector<T, Capacity, AllocPolicy>;
 176   const Vec& vec() const { return static_cast<const Wrapper*>(this)->get(); }
 177
 178  public:
 179   const AllocPolicy& allocPolicy() const { return vec().allocPolicy(); }
 180   size_t length() const { return vec().length(); }
 181   bool empty() const { return vec().empty(); }
 182   size_t capacity() const { return vec().capacity(); }
 183   const T* begin() const { return vec().begin(); }
 184   const T* end() const { return vec().end(); }
 185   const T& back() const { return vec().back(); }
 186
 187   JS::Handle<T> operator[](size_t aIndex) const {
 188     return JS::Handle<T>::fromMarkedLocation(&vec().operator[](aIndex));
 189   }
 190 };
 191
 192 template <typename Wrapper, typename T, size_t Capacity, typename AllocPolicy>
 193 class MutableWrappedPtrOperations<JS::GCVector<T, Capacity, AllocPolicy>,
 194                                   Wrapper>
 195     : public WrappedPtrOperations<JS::GCVector<T, Capacity, AllocPolicy>,
 196                                   Wrapper> {
 197   using Vec = JS::GCVector<T, Capacity, AllocPolicy>;
 198   const Vec& vec() const { return static_cast<const Wrapper*>(this)->get(); }
 199   Vec& vec() { return static_cast<Wrapper*>(this)->get(); }
 200
 201  public:
 202   const AllocPolicy& allocPolicy() const { return vec().allocPolicy(); }
 203   AllocPolicy& allocPolicy() { return vec().allocPolicy(); }
 204   const T* begin() const { return vec().begin(); }
 205   T* begin() { return vec().begin(); }
 206   const T* end() const { return vec().end(); }
 207   T* end() { return vec().end(); }
 208   const T& back() const { return vec().back(); }
 209   T& back() { return vec().back(); }
 210
 211   JS::Handle<T> operator[](size_t aIndex) const {
 212     return JS::Handle<T>::fromMarkedLocation(&vec().operator[](aIndex));
 213   }
 214   JS::MutableHandle<T> operator[](size_t aIndex) {
 215     return JS::MutableHandle<T>::fromMarkedLocation(&vec().operator[](aIndex));
 216   }
 217
 218   MOZ_MUST_USE bool initCapacity(size_t aRequest) {
 219     return vec().initCapacity(aRequest);
 220   }
 221   MOZ_MUST_USE bool reserve(size_t aRequest) { return vec().reserve(aRequest); }
 222   void shrinkBy(size_t aIncr) { vec().shrinkBy(aIncr); }
 223   MOZ_MUST_USE bool growBy(size_t aIncr) { return vec().growBy(aIncr); }
 224   MOZ_MUST_USE bool resize(size_t aNewLength) {
 225     return vec().resize(aNewLength);
 226   }
 227   MOZ_MUST_USE bool growByUninitialized(size_t aIncr) {
 228     return vec().growByUninitialized(aIncr);
 229   }
 230   void infallibleGrowByUninitialized(size_t aIncr) {
 231     vec().infallibleGrowByUninitialized(aIncr);
 232   }
 233   MOZ_MUST_USE bool resizeUninitialized(size_t aNewLength) {
 234     return vec().resizeUninitialized(aNewLength);
 235   }
 236   void clear() { vec().clear(); }
 237   void clearAndFree() { vec().clearAndFree(); }
 238   template <typename U>
 239   MOZ_MUST_USE bool append(U&& aU) {
 240     return vec().append(std::forward<U>(aU));
 241   }
 242   template <typename... Args>
 243   MOZ_MUST_USE bool emplaceBack(Args&&... aArgs) {
 244     return vec().emplaceBack(std::forward<Args>(aArgs)...);
 245   }
 246   template <typename U>
 247   MOZ_MUST_USE bool appendAll(const U& aU) {
 248     return vec().appendAll(aU);
 249   }
 250   MOZ_MUST_USE bool appendN(const T& aT, size_t aN) {
 251     return vec().appendN(aT, aN);
 252   }
 253   template <typename U>
 254   MOZ_MUST_USE bool append(const U* aBegin, const U* aEnd) {
 255     return vec().append(aBegin, aEnd);
 256   }
 257   template <typename U>
 258   MOZ_MUST_USE bool append(const U* aBegin, size_t aLength) {
 259     return vec().append(aBegin, aLength);
 260   }
 261   template <typename U>
 262   void infallibleAppend(U&& aU) {
 263     vec().infallibleAppend(std::forward<U>(aU));
 264   }
 265   void infallibleAppendN(const T& aT, size_t aN) {
 266     vec().infallibleAppendN(aT, aN);
 267   }
 268   template <typename U>
 269   void infallibleAppend(const U* aBegin, const U* aEnd) {
 270     vec().infallibleAppend(aBegin, aEnd);
 271   }
 272   template <typename U>
 273   void infallibleAppend(const U* aBegin, size_t aLength) {
 274     vec().infallibleAppend(aBegin, aLength);
 275   }
 276   void popBack() { vec().popBack(); }
 277   T popCopy() { return vec().popCopy(); }
 278   template <typename U>
 279   T* insert(T* aP, U&& aVal) {
 280     return vec().insert(aP, std::forward<U>(aVal));
 281   }
 282   void erase(T* aT) { vec().erase(aT); }
 283   void erase(T* aBegin, T* aEnd) { vec().erase(aBegin, aEnd); }
 284 };
 285
 286 template <typename Wrapper, typename T, typename AllocPolicy>
 287 class WrappedPtrOperations<JS::StackGCVector<T, AllocPolicy>, Wrapper>
 288     : public WrappedPtrOperations<
 289           typename JS::StackGCVector<T, AllocPolicy>::Base, Wrapper> {};
 290
 291 template <typename Wrapper, typename T, typename AllocPolicy>
 292 class MutableWrappedPtrOperations<JS::StackGCVector<T, AllocPolicy>, Wrapper>
 293     : public MutableWrappedPtrOperations<
 294           typename JS::StackGCVector<T, AllocPolicy>::Base, Wrapper> {};
 295
 296 }  // namespace js
 297
 298 namespace JS {
 299
 300 // An automatically rooted GCVector for stack use.
 301 template <typename T>
 302 class RootedVector : public Rooted<StackGCVector<T>> {
 303   using Vec = StackGCVector<T>;
 304   using Base = Rooted<Vec>;
 305
 306  public:
 307   explicit RootedVector(JSContext* cx) : Base(cx, Vec(cx)) {}
 308 };
 309
 310 // For use in rust code, an analog to RootedVector that doesn't require
 311 // instances to be destroyed in LIFO order.
 312 template <typename T>
 313 class PersistentRootedVector : public PersistentRooted<StackGCVector<T>> {
 314   using Vec = StackGCVector<T>;
 315   using Base = PersistentRooted<Vec>;
 316
 317  public:
 318   explicit PersistentRootedVector(JSContext* cx) : Base(cx, Vec(cx)) {}
 319 };
 320
 321 }  // namespace JS
 322
 323 #endif  // js_GCVector_h