handles.h 8.98 KB
Newer Older
1
// Copyright 2011 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_HANDLES_H_
#define V8_HANDLES_H_

8
#include "src/objects.h"
9

10 11
namespace v8 {
namespace internal {
12

13 14 15
// A Handle can be converted into a MaybeHandle. Converting a MaybeHandle
// into a Handle requires checking that it does not point to NULL.  This
// ensures NULL checks before use.
16
// Do not use MaybeHandle as argument type.
17

18 19 20
template<typename T>
class MaybeHandle {
 public:
21
  INLINE(MaybeHandle()) : location_(NULL) { }
22 23 24 25 26

  // Constructor for handling automatic up casting from Handle.
  // Ex. Handle<JSArray> can be passed when MaybeHandle<Object> is expected.
  template <class S> MaybeHandle(Handle<S> handle) {
#ifdef DEBUG
27 28
    T* a = NULL;
    S* b = NULL;
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46
    a = b;  // Fake assignment to enforce type checks.
    USE(a);
#endif
    this->location_ = reinterpret_cast<T**>(handle.location());
  }

  // Constructor for handling automatic up casting.
  // Ex. MaybeHandle<JSArray> can be passed when Handle<Object> is expected.
  template <class S> MaybeHandle(MaybeHandle<S> maybe_handle) {
#ifdef DEBUG
    T* a = NULL;
    S* b = NULL;
    a = b;  // Fake assignment to enforce type checks.
    USE(a);
#endif
    location_ = reinterpret_cast<T**>(maybe_handle.location_);
  }

47 48
  INLINE(void Assert() const) { DCHECK(location_ != NULL); }
  INLINE(void Check() const) { CHECK(location_ != NULL); }
49

50
  INLINE(Handle<T> ToHandleChecked()) const {
51
    Check();
52 53 54
    return Handle<T>(location_);
  }

55
  // Convert to a Handle with a type that can be upcasted to.
56
  template <class S>
57
  V8_INLINE bool ToHandle(Handle<S>* out) const {
58 59 60 61 62 63 64 65 66
    if (location_ == NULL) {
      *out = Handle<T>::null();
      return false;
    } else {
      *out = Handle<T>(location_);
      return true;
    }
  }

67 68
  bool is_null() const { return location_ == NULL; }

69 70 71 72 73 74 75 76 77 78
  template <typename S>
  bool operator==(MaybeHandle<S> that) const {
    return this->location_ == that.location_;
  }
  template <typename S>
  bool operator!=(MaybeHandle<S> that) const {
    return !(*this == that);
  }


79 80 81 82 83 84
 protected:
  T** location_;

  // MaybeHandles of different classes are allowed to access each
  // other's location_.
  template<class S> friend class MaybeHandle;
85 86
  template <typename S>
  friend size_t hash_value(MaybeHandle<S>);
87 88
};

89 90 91 92 93 94
template <typename S>
inline size_t hash_value(MaybeHandle<S> maybe_handle) {
  return bit_cast<size_t>(maybe_handle.location_);
}


95 96 97
// ----------------------------------------------------------------------------
// A Handle provides a reference to an object that survives relocation by
// the garbage collector.
98
// Handles are only valid within a HandleScope.
99
// When a handle is created for an object a cell is allocated in the heap.
100 101 102

template<typename T>
class Handle {
103
 public:
104 105 106
  INLINE(explicit Handle(T** location)) { location_ = location; }
  INLINE(explicit Handle(T* obj));
  INLINE(Handle(T* obj, Isolate* isolate));
107

108 109
  // TODO(yangguo): Values that contain empty handles should be declared as
  // MaybeHandle to force validation before being used as handles.
110
  INLINE(Handle()) : location_(NULL) { }
111 112 113

  // Constructor for handling automatic up casting.
  // Ex. Handle<JSFunction> can be passed when Handle<Object> is expected.
114 115 116 117
  template <class S> Handle(Handle<S> handle) {
#ifdef DEBUG
    T* a = NULL;
    S* b = NULL;
118 119
    a = b;  // Fake assignment to enforce type checks.
    USE(a);
120 121
#endif
    location_ = reinterpret_cast<T**>(handle.location_);
122 123
  }

124 125 126 127
  INLINE(T* operator->() const) { return operator*(); }

  // Check if this handle refers to the exact same object as the other handle.
  INLINE(bool is_identical_to(const Handle<T> other) const);
128 129

  // Provides the C++ dereference operator.
130
  INLINE(T* operator*() const);
131 132

  // Returns the address to where the raw pointer is stored.
133
  INLINE(T** location() const);
134

135 136 137
  template <class S> static Handle<T> cast(Handle<S> that) {
    T::cast(*reinterpret_cast<T**>(that.location_));
    return Handle<T>(reinterpret_cast<T**>(that.location_));
138 139
  }

140 141
  // TODO(yangguo): Values that contain empty handles should be declared as
  // MaybeHandle to force validation before being used as handles.
142
  static Handle<T> null() { return Handle<T>(); }
143
  bool is_null() const { return location_ == NULL; }
144 145 146

  // Closes the given scope, but lets this handle escape. See
  // implementation in api.h.
147
  inline Handle<T> EscapeFrom(v8::EscapableHandleScope* scope);
148

149 150 151 152 153 154
#ifdef DEBUG
  enum DereferenceCheckMode { INCLUDE_DEFERRED_CHECK, NO_DEFERRED_CHECK };

  bool IsDereferenceAllowed(DereferenceCheckMode mode) const;
#endif  // DEBUG

155
 private:
156 157
  T** location_;

158 159
  // Handles of different classes are allowed to access each other's location_.
  template<class S> friend class Handle;
160 161 162
};


163 164
// Convenience wrapper.
template<class T>
165 166
inline Handle<T> handle(T* t, Isolate* isolate) {
  return Handle<T>(t, isolate);
167 168 169
}


170
// Convenience wrapper.
171
template<class T>
172
inline Handle<T> handle(T* t) {
173
  return Handle<T>(t, t->GetIsolate());
174 175 176
}


177 178 179 180
class DeferredHandles;
class HandleScopeImplementer;


181 182 183 184 185 186 187 188 189 190 191 192
// A stack-allocated class that governs a number of local handles.
// After a handle scope has been created, all local handles will be
// allocated within that handle scope until either the handle scope is
// deleted or another handle scope is created.  If there is already a
// handle scope and a new one is created, all allocations will take
// place in the new handle scope until it is deleted.  After that,
// new handles will again be allocated in the original handle scope.
//
// After the handle scope of a local handle has been deleted the
// garbage collector will no longer track the object stored in the
// handle and may deallocate it.  The behavior of accessing a handle
// for which the handle scope has been deleted is undefined.
193
class HandleScope {
194
 public:
195 196 197
  explicit inline HandleScope(Isolate* isolate);

  inline ~HandleScope();
198 199

  // Counts the number of allocated handles.
200
  static int NumberOfHandles(Isolate* isolate);
201 202

  // Creates a new handle with the given value.
203
  template <typename T>
204
  static inline T** CreateHandle(Isolate* isolate, T* value);
205

206
  // Deallocates any extensions used by the current scope.
207
  static void DeleteExtensions(Isolate* isolate);
208

209 210 211
  static Address current_next_address(Isolate* isolate);
  static Address current_limit_address(Isolate* isolate);
  static Address current_level_address(Isolate* isolate);
212

213 214 215 216 217
  // Closes the HandleScope (invalidating all handles
  // created in the scope of the HandleScope) and returns
  // a Handle backed by the parent scope holding the
  // value of the argument handle.
  template <typename T>
218
  Handle<T> CloseAndEscape(Handle<T> handle_value);
219

220
  Isolate* isolate() { return isolate_; }
221

222
  // Limit for number of handles with --check-handle-count. This is
223 224 225 226
  // large enough to compile natives and pass unit tests with some
  // slack for future changes to natives.
  static const int kCheckHandleThreshold = 30 * 1024;

227
 private:
228
  // Prevent heap allocation or illegal handle scopes.
229 230 231 232 233 234 235 236
  HandleScope(const HandleScope&);
  void operator=(const HandleScope&);
  void* operator new(size_t size);
  void operator delete(void* size_t);

  Isolate* isolate_;
  Object** prev_next_;
  Object** prev_limit_;
237

238
  // Close the handle scope resetting limits to a previous state.
239 240 241
  static inline void CloseScope(Isolate* isolate,
                                Object** prev_next,
                                Object** prev_limit);
242

243
  // Extend the handle scope making room for more handles.
244
  static internal::Object** Extend(Isolate* isolate);
245

246
#ifdef ENABLE_HANDLE_ZAPPING
247
  // Zaps the handles in the half-open interval [start, end).
248
  static void ZapRange(Object** start, Object** end);
249
#endif
250

251 252 253 254
  friend class v8::HandleScope;
  friend class v8::internal::DeferredHandles;
  friend class v8::internal::HandleScopeImplementer;
  friend class v8::internal::Isolate;
255
};
256 257


258 259 260
class DeferredHandles;


261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283
class DeferredHandleScope {
 public:
  explicit DeferredHandleScope(Isolate* isolate);
  // The DeferredHandles object returned stores the Handles created
  // since the creation of this DeferredHandleScope.  The Handles are
  // alive as long as the DeferredHandles object is alive.
  DeferredHandles* Detach();
  ~DeferredHandleScope();

 private:
  Object** prev_limit_;
  Object** prev_next_;
  HandleScopeImplementer* impl_;

#ifdef DEBUG
  bool handles_detached_;
  int prev_level_;
#endif

  friend class HandleScopeImplementer;
};


284 285
// Seal off the current HandleScope so that new handles can only be created
// if a new HandleScope is entered.
286
class SealHandleScope BASE_EMBEDDED {
287 288
 public:
#ifndef DEBUG
289 290
  explicit SealHandleScope(Isolate* isolate) {}
  ~SealHandleScope() {}
291
#else
292 293
  explicit inline SealHandleScope(Isolate* isolate);
  inline ~SealHandleScope();
294
 private:
295
  Isolate* isolate_;
296
  Object** limit_;
297
  int level_;
298
#endif
299 300
};

301 302 303 304 305 306
struct HandleScopeData {
  internal::Object** next;
  internal::Object** limit;
  int level;

  void Initialize() {
307
    next = limit = NULL;
308 309 310 311
    level = 0;
  }
};

312
} }  // namespace v8::internal
313 314

#endif  // V8_HANDLES_H_