v8-util.h 19.5 KB
Newer Older
1
// Copyright 2014 the V8 project authors. All rights reserved.
2 3
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
4 5 6 7

#ifndef V8_UTIL_H_
#define V8_UTIL_H_

8
#include "v8.h"  // NOLINT(build/include)
9
#include <map>
10
#include <vector>
11 12 13 14

/**
 * Support for Persistent containers.
 *
15
 * C++11 embedders can use STL containers with Global values,
16 17 18 19 20 21 22
 * but pre-C++11 does not support the required move semantic and hence
 * may want these container classes.
 */
namespace v8 {

typedef uintptr_t PersistentContainerValue;
static const uintptr_t kPersistentContainerNotFound = 0;
23 24
enum PersistentContainerCallbackType {
  kNotWeak,
25 26 27 28
  // These correspond to v8::WeakCallbackType
  kWeakWithParameter,
  kWeakWithInternalFields,
  kWeak = kWeakWithParameter  // For backwards compatibility.  Deprecate.
29
};
30

31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79

/**
 * A default trait implemenation for PersistentValueMap which uses std::map
 * as a backing map.
 *
 * Users will have to implement their own weak callbacks & dispose traits.
 */
template<typename K, typename V>
class StdMapTraits {
 public:
  // STL map & related:
  typedef std::map<K, PersistentContainerValue> Impl;
  typedef typename Impl::iterator Iterator;

  static bool Empty(Impl* impl) { return impl->empty(); }
  static size_t Size(Impl* impl) { return impl->size(); }
  static void Swap(Impl& a, Impl& b) { std::swap(a, b); }  // NOLINT
  static Iterator Begin(Impl* impl) { return impl->begin(); }
  static Iterator End(Impl* impl) { return impl->end(); }
  static K Key(Iterator it) { return it->first; }
  static PersistentContainerValue Value(Iterator it) { return it->second; }
  static PersistentContainerValue Set(Impl* impl, K key,
      PersistentContainerValue value) {
    std::pair<Iterator, bool> res = impl->insert(std::make_pair(key, value));
    PersistentContainerValue old_value = kPersistentContainerNotFound;
    if (!res.second) {
      old_value = res.first->second;
      res.first->second = value;
    }
    return old_value;
  }
  static PersistentContainerValue Get(Impl* impl, K key) {
    Iterator it = impl->find(key);
    if (it == impl->end()) return kPersistentContainerNotFound;
    return it->second;
  }
  static PersistentContainerValue Remove(Impl* impl, K key) {
    Iterator it = impl->find(key);
    if (it == impl->end()) return kPersistentContainerNotFound;
    PersistentContainerValue value = it->second;
    impl->erase(it);
    return value;
  }
};


/**
 * A default trait implementation for PersistentValueMap, which inherits
 * a std:map backing map from StdMapTraits and holds non-weak persistent
80
 * objects and has no special Dispose handling.
81
 *
82 83
 * You should not derive from this class, since MapType depends on the
 * surrounding class, and hence a subclass cannot simply inherit the methods.
84 85
 */
template<typename K, typename V>
86
class DefaultPersistentValueMapTraits : public StdMapTraits<K, V> {
87 88
 public:
  // Weak callback & friends:
89 90 91
  static const PersistentContainerCallbackType kCallbackType = kNotWeak;
  typedef PersistentValueMap<K, V, DefaultPersistentValueMapTraits<K, V> >
      MapType;
92
  typedef void WeakCallbackDataType;
93

94
  static WeakCallbackDataType* WeakCallbackParameter(
95 96 97
      MapType* map, const K& key, Local<V> value) {
    return NULL;
  }
98 99
  static MapType* MapFromWeakCallbackInfo(
      const WeakCallbackInfo<WeakCallbackDataType>& data) {
100 101
    return NULL;
  }
102 103
  static K KeyFromWeakCallbackInfo(
      const WeakCallbackInfo<WeakCallbackDataType>& data) {
104 105 106
    return K();
  }
  static void DisposeCallbackData(WeakCallbackDataType* data) { }
107
  static void Dispose(Isolate* isolate, Global<V> value, K key) {}
108 109 110
};


111
template <typename K, typename V>
112
class DefaultGlobalMapTraits : public StdMapTraits<K, V> {
113 114 115 116 117 118 119
 private:
  template <typename T>
  struct RemovePointer;

 public:
  // Weak callback & friends:
  static const PersistentContainerCallbackType kCallbackType = kNotWeak;
dcarney's avatar
dcarney committed
120 121
  typedef GlobalValueMap<K, V, DefaultGlobalMapTraits<K, V> > MapType;
  typedef void WeakCallbackDataType;
122

dcarney's avatar
dcarney committed
123
  static WeakCallbackDataType* WeakCallbackParameter(MapType* map, const K& key,
124 125
                                                     Local<V> value) {
    return nullptr;
126
  }
127
  static MapType* MapFromWeakCallbackInfo(
dcarney's avatar
dcarney committed
128
      const WeakCallbackInfo<WeakCallbackDataType>& data) {
129
    return nullptr;
130
  }
131
  static K KeyFromWeakCallbackInfo(
dcarney's avatar
dcarney committed
132
      const WeakCallbackInfo<WeakCallbackDataType>& data) {
133 134
    return K();
  }
dcarney's avatar
dcarney committed
135
  static void DisposeCallbackData(WeakCallbackDataType* data) {}
136 137
  static void OnWeakCallback(
      const WeakCallbackInfo<WeakCallbackDataType>& data) {}
138
  static void Dispose(Isolate* isolate, Global<V> value, K key) {}
139
  // This is a second pass callback, so SetSecondPassCallback cannot be called.
dcarney's avatar
dcarney committed
140
  static void DisposeWeak(const WeakCallbackInfo<WeakCallbackDataType>& data) {}
141 142 143 144 145 146 147 148 149

 private:
  template <typename T>
  struct RemovePointer<T*> {
    typedef T Type;
  };
};


150
/**
151 152
 * A map wrapper that allows using Global as a mapped value.
 * C++11 embedders don't need this class, as they can use Global
153 154 155 156 157 158 159
 * directly in std containers.
 *
 * The map relies on a backing map, whose type and accessors are described
 * by the Traits class. The backing map will handle values of type
 * PersistentContainerValue, with all conversion into and out of V8
 * handles being transparently handled by this class.
 */
160 161
template <typename K, typename V, typename Traits>
class PersistentValueMapBase {
162
 public:
163
  Isolate* GetIsolate() { return isolate_; }
164 165 166 167

  /**
   * Return size of the map.
   */
168
  size_t Size() { return Traits::Size(&impl_); }
169

170 171 172
  /**
   * Return whether the map holds weak persistents.
   */
173
  bool IsWeak() { return Traits::kCallbackType != kNotWeak; }
174

175 176 177
  /**
   * Get value stored in map.
   */
178
  Local<V> Get(const K& key) {
179 180 181 182 183 184
    return Local<V>::New(isolate_, FromVal(Traits::Get(&impl_, key)));
  }

  /**
   * Check whether a value is contained in the map.
   */
185
  bool Contains(const K& key) {
186
    return Traits::Get(&impl_, key) != kPersistentContainerNotFound;
187 188 189 190 191 192
  }

  /**
   * Get value stored in map and set it in returnValue.
   * Return true if a value was found.
   */
193
  bool SetReturnValue(const K& key,
194
      ReturnValue<Value> returnValue) {
195
    return SetReturnValueFromVal(&returnValue, Traits::Get(&impl_, key));
196
  }
197 198 199 200

  /**
   * Call Isolate::SetReference with the given parent and the map value.
   */
201
  void SetReference(const K& key,
202
      const Persistent<Object>& parent) {
203 204 205 206 207
    GetIsolate()->SetReference(
      reinterpret_cast<internal::Object**>(parent.val_),
      reinterpret_cast<internal::Object**>(FromVal(Traits::Get(&impl_, key))));
  }

208
  /**
209 210
   * Call V8::RegisterExternallyReferencedObject with the map value for given
   * key.
211
   */
212
  void RegisterExternallyReferencedObject(K& key) {
213
    DCHECK(Contains(key));
214 215 216
    V8::RegisterExternallyReferencedObject(
        reinterpret_cast<internal::Object**>(FromVal(Traits::Get(&impl_, key))),
        reinterpret_cast<internal::Isolate*>(GetIsolate()));
217 218
  }

219 220 221
  /**
   * Return value for key and remove it from the map.
   */
222
  Global<V> Remove(const K& key) {
223 224 225 226 227 228 229
    return Release(Traits::Remove(&impl_, key)).Pass();
  }

  /**
  * Traverses the map repeatedly,
  * in case side effects of disposal cause insertions.
  **/
230 231 232 233 234 235 236 237
  void Clear() {
    typedef typename Traits::Iterator It;
    HandleScope handle_scope(isolate_);
    // TODO(dcarney): figure out if this swap and loop is necessary.
    while (!Traits::Empty(&impl_)) {
      typename Traits::Impl impl;
      Traits::Swap(impl_, impl);
      for (It i = Traits::Begin(&impl); i != Traits::End(&impl); ++i) {
238 239
        Traits::Dispose(isolate_, Release(Traits::Value(i)).Pass(),
                        Traits::Key(i));
240 241 242
      }
    }
  }
243

244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261
  /**
   * Helper class for GetReference/SetWithReference. Do not use outside
   * that context.
   */
  class PersistentValueReference {
   public:
    PersistentValueReference() : value_(kPersistentContainerNotFound) { }
    PersistentValueReference(const PersistentValueReference& other)
        : value_(other.value_) { }

    Local<V> NewLocal(Isolate* isolate) const {
      return Local<V>::New(isolate, FromVal(value_));
    }
    bool IsEmpty() const {
      return value_ == kPersistentContainerNotFound;
    }
    template<typename T>
    bool SetReturnValue(ReturnValue<T> returnValue) {
262
      return SetReturnValueFromVal(&returnValue, value_);
263 264 265 266 267 268 269 270 271
    }
    void Reset() {
      value_ = kPersistentContainerNotFound;
    }
    void operator=(const PersistentValueReference& other) {
      value_ = other.value_;
    }

   private:
272 273
    friend class PersistentValueMapBase;
    friend class PersistentValueMap<K, V, Traits>;
274
    friend class GlobalValueMap<K, V, Traits>;
275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295

    explicit PersistentValueReference(PersistentContainerValue value)
        : value_(value) { }

    void operator=(PersistentContainerValue value) {
      value_ = value;
    }

    PersistentContainerValue value_;
  };

  /**
   * Get a reference to a map value. This enables fast, repeated access
   * to a value stored in the map while the map remains unchanged.
   *
   * Careful: This is potentially unsafe, so please use with care.
   * The value will become invalid if the value for this key changes
   * in the underlying map, as a result of Set or Remove for the same
   * key; as a result of the weak callback for the same key; or as a
   * result of calling Clear() or destruction of the map.
   */
296
  PersistentValueReference GetReference(const K& key) {
297 298 299
    return PersistentValueReference(Traits::Get(&impl_, key));
  }

300 301 302 303 304 305 306 307 308 309 310 311
 protected:
  explicit PersistentValueMapBase(Isolate* isolate) : isolate_(isolate) {}

  ~PersistentValueMapBase() { Clear(); }

  Isolate* isolate() { return isolate_; }
  typename Traits::Impl* impl() { return &impl_; }

  static V* FromVal(PersistentContainerValue v) {
    return reinterpret_cast<V*>(v);
  }

312
  static PersistentContainerValue ClearAndLeak(Global<V>* persistent) {
313 314 315 316 317
    V* v = persistent->val_;
    persistent->val_ = 0;
    return reinterpret_cast<PersistentContainerValue>(v);
  }

318
  static PersistentContainerValue Leak(Global<V>* persistent) {
319 320 321
    return reinterpret_cast<PersistentContainerValue>(persistent->val_);
  }

322
  /**
323
   * Return a container value as Global and make sure the weak
324 325
   * callback is properly disposed of. All remove functionality should go
   * through this.
326
   */
327 328
  static Global<V> Release(PersistentContainerValue v) {
    Global<V> p;
329 330 331 332 333 334
    p.val_ = FromVal(v);
    if (Traits::kCallbackType != kNotWeak && p.IsWeak()) {
      Traits::DisposeCallbackData(
          p.template ClearWeak<typename Traits::WeakCallbackDataType>());
    }
    return p.Pass();
335 336
  }

dcarney's avatar
dcarney committed
337 338 339 340 341
  void RemoveWeak(const K& key) {
    Global<V> p;
    p.val_ = FromVal(Traits::Remove(&impl_, key));
    p.Reset();
  }
342

343
 private:
344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374
  PersistentValueMapBase(PersistentValueMapBase&);
  void operator=(PersistentValueMapBase&);

  static bool SetReturnValueFromVal(ReturnValue<Value>* returnValue,
                                    PersistentContainerValue value) {
    bool hasValue = value != kPersistentContainerNotFound;
    if (hasValue) {
      returnValue->SetInternal(
          *reinterpret_cast<internal::Object**>(FromVal(value)));
    }
    return hasValue;
  }

  Isolate* isolate_;
  typename Traits::Impl impl_;
};


template <typename K, typename V, typename Traits>
class PersistentValueMap : public PersistentValueMapBase<K, V, Traits> {
 public:
  explicit PersistentValueMap(Isolate* isolate)
      : PersistentValueMapBase<K, V, Traits>(isolate) {}

  typedef
      typename PersistentValueMapBase<K, V, Traits>::PersistentValueReference
          PersistentValueReference;

  /**
   * Put value into map. Depending on Traits::kIsWeak, the value will be held
   * by the map strongly or weakly.
375
   * Returns old value as Global.
376
   */
377 378
  Global<V> Set(const K& key, Local<V> value) {
    Global<V> persistent(this->isolate(), value);
379 380 381 382 383 384
    return SetUnique(key, &persistent);
  }

  /**
   * Put value into map, like Set(const K&, Local<V>).
   */
385
  Global<V> Set(const K& key, Global<V> value) {
386 387
    return SetUnique(key, &value);
  }
388 389 390 391 392

  /**
   * Put the value into the map, and set the 'weak' callback when demanded
   * by the Traits class.
   */
393
  Global<V> SetUnique(const K& key, Global<V>* persistent) {
394
    if (Traits::kCallbackType != kNotWeak) {
395
      Local<V> value(Local<V>::New(this->isolate(), *persistent));
396
      persistent->template SetWeak<typename Traits::WeakCallbackDataType>(
397
        Traits::WeakCallbackParameter(this, key, value), WeakCallback);
398 399
    }
    PersistentContainerValue old_value =
400 401 402 403 404 405 406 407
        Traits::Set(this->impl(), key, this->ClearAndLeak(persistent));
    return this->Release(old_value).Pass();
  }

  /**
   * Put a value into the map and update the reference.
   * Restrictions of GetReference apply here as well.
   */
408 409
  Global<V> Set(const K& key, Global<V> value,
                PersistentValueReference* reference) {
410 411
    *reference = this->Leak(&value);
    return SetUnique(key, &value);
412 413
  }

414
 private:
415
  static void WeakCallback(
416
      const WeakCallbackInfo<typename Traits::WeakCallbackDataType>& data) {
417 418
    if (Traits::kCallbackType != kNotWeak) {
      PersistentValueMap<K, V, Traits>* persistentValueMap =
419 420
          Traits::MapFromWeakCallbackInfo(data);
      K key = Traits::KeyFromWeakCallbackInfo(data);
421 422
      Traits::Dispose(data.GetIsolate(),
                      persistentValueMap->Remove(key).Pass(), key);
423
      Traits::DisposeCallbackData(data.GetParameter());
424 425
    }
  }
426
};
427 428


429
template <typename K, typename V, typename Traits>
430
class GlobalValueMap : public PersistentValueMapBase<K, V, Traits> {
431
 public:
432
  explicit GlobalValueMap(Isolate* isolate)
433
      : PersistentValueMapBase<K, V, Traits>(isolate) {}
434

435 436 437 438 439 440 441
  typedef
      typename PersistentValueMapBase<K, V, Traits>::PersistentValueReference
          PersistentValueReference;

  /**
   * Put value into map. Depending on Traits::kIsWeak, the value will be held
   * by the map strongly or weakly.
442
   * Returns old value as Global.
443
   */
444 445
  Global<V> Set(const K& key, Local<V> value) {
    Global<V> persistent(this->isolate(), value);
446
    return SetUnique(key, &persistent);
447 448
  }

449 450 451
  /**
   * Put value into map, like Set(const K&, Local<V>).
   */
452
  Global<V> Set(const K& key, Global<V> value) {
453
    return SetUnique(key, &value);
454 455
  }

456
  /**
457 458
   * Put the value into the map, and set the 'weak' callback when demanded
   * by the Traits class.
459
   */
460
  Global<V> SetUnique(const K& key, Global<V>* persistent) {
461
    if (Traits::kCallbackType != kNotWeak) {
462 463 464 465
      WeakCallbackType callback_type =
          Traits::kCallbackType == kWeakWithInternalFields
              ? WeakCallbackType::kInternalFields
              : WeakCallbackType::kParameter;
466
      Local<V> value(Local<V>::New(this->isolate(), *persistent));
467
      persistent->template SetWeak<typename Traits::WeakCallbackDataType>(
468
          Traits::WeakCallbackParameter(this, key, value), OnWeakCallback,
469
          callback_type);
470
    }
471 472 473
    PersistentContainerValue old_value =
        Traits::Set(this->impl(), key, this->ClearAndLeak(persistent));
    return this->Release(old_value).Pass();
474 475
  }

476 477 478 479
  /**
   * Put a value into the map and update the reference.
   * Restrictions of GetReference apply here as well.
   */
480 481
  Global<V> Set(const K& key, Global<V> value,
                PersistentValueReference* reference) {
482 483 484 485 486
    *reference = this->Leak(&value);
    return SetUnique(key, &value);
  }

 private:
487
  static void OnWeakCallback(
488
      const WeakCallbackInfo<typename Traits::WeakCallbackDataType>& data) {
489
    if (Traits::kCallbackType != kNotWeak) {
490
      auto map = Traits::MapFromWeakCallbackInfo(data);
491
      K key = Traits::KeyFromWeakCallbackInfo(data);
492
      map->RemoveWeak(key);
493
      Traits::OnWeakCallback(data);
494
      data.SetSecondPassCallback(SecondWeakCallback);
495 496
    }
  }
497 498 499 500 501

  static void SecondWeakCallback(
      const WeakCallbackInfo<typename Traits::WeakCallbackDataType>& data) {
    Traits::DisposeWeak(data);
  }
502 503
};

504 505

/**
506
 * A map that uses Global as value and std::map as the backing
507 508 509
 * implementation. Persistents are held non-weak.
 *
 * C++11 embedders don't need this class, as they can use
510
 * Global directly in std containers.
511 512 513 514 515 516 517 518 519
 */
template<typename K, typename V,
    typename Traits = DefaultPersistentValueMapTraits<K, V> >
class StdPersistentValueMap : public PersistentValueMap<K, V, Traits> {
 public:
  explicit StdPersistentValueMap(Isolate* isolate)
      : PersistentValueMap<K, V, Traits>(isolate) {}
};

520

dcarney's avatar
dcarney committed
521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536
/**
 * A map that uses Global as value and std::map as the backing
 * implementation. Globals are held non-weak.
 *
 * C++11 embedders don't need this class, as they can use
 * Global directly in std containers.
 */
template <typename K, typename V,
          typename Traits = DefaultGlobalMapTraits<K, V> >
class StdGlobalValueMap : public GlobalValueMap<K, V, Traits> {
 public:
  explicit StdGlobalValueMap(Isolate* isolate)
      : GlobalValueMap<K, V, Traits>(isolate) {}
};


537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562
class DefaultPersistentValueVectorTraits {
 public:
  typedef std::vector<PersistentContainerValue> Impl;

  static void Append(Impl* impl, PersistentContainerValue value) {
    impl->push_back(value);
  }
  static bool IsEmpty(const Impl* impl) {
    return impl->empty();
  }
  static size_t Size(const Impl* impl) {
    return impl->size();
  }
  static PersistentContainerValue Get(const Impl* impl, size_t i) {
    return (i < impl->size()) ? impl->at(i) : kPersistentContainerNotFound;
  }
  static void ReserveCapacity(Impl* impl, size_t capacity) {
    impl->reserve(capacity);
  }
  static void Clear(Impl* impl) {
    impl->clear();
  }
};


/**
563 564
 * A vector wrapper that safely stores Global values.
 * C++11 embedders don't need this class, as they can use Global
565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584
 * directly in std containers.
 *
 * This class relies on a backing vector implementation, whose type and methods
 * are described by the Traits class. The backing map will handle values of type
 * PersistentContainerValue, with all conversion into and out of V8
 * handles being transparently handled by this class.
 */
template<typename V, typename Traits = DefaultPersistentValueVectorTraits>
class PersistentValueVector {
 public:
  explicit PersistentValueVector(Isolate* isolate) : isolate_(isolate) { }

  ~PersistentValueVector() {
    Clear();
  }

  /**
   * Append a value to the vector.
   */
  void Append(Local<V> value) {
585
    Global<V> persistent(isolate_, value);
586 587 588 589 590 591
    Traits::Append(&impl_, ClearAndLeak(&persistent));
  }

  /**
   * Append a persistent's value to the vector.
   */
592
  void Append(Global<V> persistent) {
593
    Traits::Append(&impl_, ClearAndLeak(&persistent));
594
  }
595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622

  /**
   * Are there any values in the vector?
   */
  bool IsEmpty() const {
    return Traits::IsEmpty(&impl_);
  }

  /**
   * How many elements are in the vector?
   */
  size_t Size() const {
    return Traits::Size(&impl_);
  }

  /**
   * Retrieve the i-th value in the vector.
   */
  Local<V> Get(size_t index) const {
    return Local<V>::New(isolate_, FromVal(Traits::Get(&impl_, index)));
  }

  /**
   * Remove all elements from the vector.
   */
  void Clear() {
    size_t length = Traits::Size(&impl_);
    for (size_t i = 0; i < length; i++) {
623
      Global<V> p;
624 625 626 627 628 629 630 631 632 633 634 635 636 637
      p.val_ = FromVal(Traits::Get(&impl_, i));
    }
    Traits::Clear(&impl_);
  }

  /**
   * Reserve capacity in the vector.
   * (Efficiency gains depend on the backing implementation.)
   */
  void ReserveCapacity(size_t capacity) {
    Traits::ReserveCapacity(&impl_, capacity);
  }

 private:
638
  static PersistentContainerValue ClearAndLeak(Global<V>* persistent) {
639 640 641 642 643 644 645 646 647 648 649 650 651
    V* v = persistent->val_;
    persistent->val_ = 0;
    return reinterpret_cast<PersistentContainerValue>(v);
  }

  static V* FromVal(PersistentContainerValue v) {
    return reinterpret_cast<V*>(v);
  }

  Isolate* isolate_;
  typename Traits::Impl impl_;
};

652 653
}  // namespace v8

654
#endif  // V8_UTIL_H