OLD | NEW |
1 // Copyright 2012 the V8 project authors. All rights reserved. | 1 // Copyright 2012 the V8 project authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 /** \mainpage V8 API Reference Guide | 5 /** \mainpage V8 API Reference Guide |
6 * | 6 * |
7 * V8 is Google's open source JavaScript engine. | 7 * V8 is Google's open source JavaScript engine. |
8 * | 8 * |
9 * This set of documents provides reference material generated from the | 9 * This set of documents provides reference material generated from the |
10 * V8 header file, include/v8.h. | 10 * V8 header file, include/v8.h. |
(...skipping 359 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
370 V8_INLINE bool IsEmpty() { return index_ == kInitialValue; } | 370 V8_INLINE bool IsEmpty() { return index_ == kInitialValue; } |
371 template<class S> V8_INLINE void Set(Isolate* isolate, Local<S> handle); | 371 template<class S> V8_INLINE void Set(Isolate* isolate, Local<S> handle); |
372 | 372 |
373 private: | 373 private: |
374 static const int kInitialValue = -1; | 374 static const int kInitialValue = -1; |
375 int index_; | 375 int index_; |
376 }; | 376 }; |
377 | 377 |
378 | 378 |
379 static const int kInternalFieldsInWeakCallback = 2; | 379 static const int kInternalFieldsInWeakCallback = 2; |
380 | 380 static const int kEmbedderFieldsInWeakCallback = 2; |
381 | 381 |
382 template <typename T> | 382 template <typename T> |
383 class WeakCallbackInfo { | 383 class WeakCallbackInfo { |
384 public: | 384 public: |
385 typedef void (*Callback)(const WeakCallbackInfo<T>& data); | 385 typedef void (*Callback)(const WeakCallbackInfo<T>& data); |
386 | 386 |
387 WeakCallbackInfo(Isolate* isolate, T* parameter, | 387 WeakCallbackInfo(Isolate* isolate, T* parameter, |
388 void* internal_fields[kInternalFieldsInWeakCallback], | 388 void* embedder_fields[kEmbedderFieldsInWeakCallback], |
389 Callback* callback) | 389 Callback* callback) |
390 : isolate_(isolate), parameter_(parameter), callback_(callback) { | 390 : isolate_(isolate), parameter_(parameter), callback_(callback) { |
391 for (int i = 0; i < kInternalFieldsInWeakCallback; ++i) { | 391 for (int i = 0; i < kEmbedderFieldsInWeakCallback; ++i) { |
392 internal_fields_[i] = internal_fields[i]; | 392 embedder_fields_[i] = embedder_fields[i]; |
393 } | 393 } |
394 } | 394 } |
395 | 395 |
396 V8_INLINE Isolate* GetIsolate() const { return isolate_; } | 396 V8_INLINE Isolate* GetIsolate() const { return isolate_; } |
397 V8_INLINE T* GetParameter() const { return parameter_; } | 397 V8_INLINE T* GetParameter() const { return parameter_; } |
398 V8_INLINE void* GetInternalField(int index) const; | 398 V8_INLINE void* GetInternalField(int index) const; |
399 | 399 |
400 V8_INLINE V8_DEPRECATED("use indexed version", | 400 V8_INLINE V8_DEPRECATED("use indexed version", |
401 void* GetInternalField1() const) { | 401 void* GetInternalField1() const) { |
402 return internal_fields_[0]; | 402 return embedder_fields_[0]; |
403 } | 403 } |
404 V8_INLINE V8_DEPRECATED("use indexed version", | 404 V8_INLINE V8_DEPRECATED("use indexed version", |
405 void* GetInternalField2() const) { | 405 void* GetInternalField2() const) { |
406 return internal_fields_[1]; | 406 return embedder_fields_[1]; |
407 } | 407 } |
408 | 408 |
409 V8_DEPRECATED("Not realiable once SetSecondPassCallback() was used.", | 409 V8_DEPRECATED("Not realiable once SetSecondPassCallback() was used.", |
410 bool IsFirstPass() const) { | 410 bool IsFirstPass() const) { |
411 return callback_ != nullptr; | 411 return callback_ != nullptr; |
412 } | 412 } |
413 | 413 |
414 // When first called, the embedder MUST Reset() the Global which triggered the | 414 // When first called, the embedder MUST Reset() the Global which triggered the |
415 // callback. The Global itself is unusable for anything else. No v8 other api | 415 // callback. The Global itself is unusable for anything else. No v8 other api |
416 // calls may be called in the first callback. Should additional work be | 416 // calls may be called in the first callback. Should additional work be |
417 // required, the embedder must set a second pass callback, which will be | 417 // required, the embedder must set a second pass callback, which will be |
418 // called after all the initial callbacks are processed. | 418 // called after all the initial callbacks are processed. |
419 // Calling SetSecondPassCallback on the second pass will immediately crash. | 419 // Calling SetSecondPassCallback on the second pass will immediately crash. |
420 void SetSecondPassCallback(Callback callback) const { *callback_ = callback; } | 420 void SetSecondPassCallback(Callback callback) const { *callback_ = callback; } |
421 | 421 |
422 private: | 422 private: |
423 Isolate* isolate_; | 423 Isolate* isolate_; |
424 T* parameter_; | 424 T* parameter_; |
425 Callback* callback_; | 425 Callback* callback_; |
426 void* internal_fields_[kInternalFieldsInWeakCallback]; | 426 void* embedder_fields_[kEmbedderFieldsInWeakCallback]; |
427 }; | 427 }; |
428 | 428 |
429 | 429 |
430 // kParameter will pass a void* parameter back to the callback, kInternalFields | 430 // kParameter will pass a void* parameter back to the callback, kInternalFields |
431 // will pass the first two internal fields back to the callback, kFinalizer | 431 // will pass the first two internal fields back to the callback, kFinalizer |
432 // will pass a void* parameter back, but is invoked before the object is | 432 // will pass a void* parameter back, but is invoked before the object is |
433 // actually collected, so it can be resurrected. In the last case, it is not | 433 // actually collected, so it can be resurrected. In the last case, it is not |
434 // possible to request a second pass callback. | 434 // possible to request a second pass callback. |
435 enum class WeakCallbackType { kParameter, kInternalFields, kFinalizer }; | 435 enum class WeakCallbackType { kParameter, kInternalFields, kFinalizer }; |
436 | 436 |
(...skipping 3635 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4072 * The embedder should make sure to hold a strong reference to the | 4072 * The embedder should make sure to hold a strong reference to the |
4073 * ArrayBuffer while accessing this pointer. | 4073 * ArrayBuffer while accessing this pointer. |
4074 * | 4074 * |
4075 * The memory block is guaranteed to be allocated with |Allocator::Allocate|. | 4075 * The memory block is guaranteed to be allocated with |Allocator::Allocate|. |
4076 */ | 4076 */ |
4077 Contents GetContents(); | 4077 Contents GetContents(); |
4078 | 4078 |
4079 V8_INLINE static ArrayBuffer* Cast(Value* obj); | 4079 V8_INLINE static ArrayBuffer* Cast(Value* obj); |
4080 | 4080 |
4081 static const int kInternalFieldCount = V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT; | 4081 static const int kInternalFieldCount = V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT; |
| 4082 static const int kEmbedderFieldCount = V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT; |
4082 | 4083 |
4083 private: | 4084 private: |
4084 ArrayBuffer(); | 4085 ArrayBuffer(); |
4085 static void CheckCast(Value* obj); | 4086 static void CheckCast(Value* obj); |
4086 }; | 4087 }; |
4087 | 4088 |
4088 | 4089 |
4089 #ifndef V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT | 4090 #ifndef V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT |
4090 // The number of required internal fields can be defined by embedder. | 4091 // The number of required internal fields can be defined by embedder. |
4091 #define V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT 2 | 4092 #define V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT 2 |
(...skipping 33 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4125 /** | 4126 /** |
4126 * Returns true if ArrayBufferView's backing ArrayBuffer has already been | 4127 * Returns true if ArrayBufferView's backing ArrayBuffer has already been |
4127 * allocated. | 4128 * allocated. |
4128 */ | 4129 */ |
4129 bool HasBuffer() const; | 4130 bool HasBuffer() const; |
4130 | 4131 |
4131 V8_INLINE static ArrayBufferView* Cast(Value* obj); | 4132 V8_INLINE static ArrayBufferView* Cast(Value* obj); |
4132 | 4133 |
4133 static const int kInternalFieldCount = | 4134 static const int kInternalFieldCount = |
4134 V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT; | 4135 V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT; |
| 4136 static const int kEmbedderFieldCount = |
| 4137 V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT; |
4135 | 4138 |
4136 private: | 4139 private: |
4137 ArrayBufferView(); | 4140 ArrayBufferView(); |
4138 static void CheckCast(Value* obj); | 4141 static void CheckCast(Value* obj); |
4139 }; | 4142 }; |
4140 | 4143 |
4141 | 4144 |
4142 /** | 4145 /** |
4143 * A base class for an instance of TypedArray series of constructors | 4146 * A base class for an instance of TypedArray series of constructors |
4144 * (ES6 draft 15.13.6). | 4147 * (ES6 draft 15.13.6). |
(...skipping 2082 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6227 ForceCompletionAction force_completion; | 6230 ForceCompletionAction force_completion; |
6228 }; | 6231 }; |
6229 | 6232 |
6230 /** | 6233 /** |
6231 * Called by v8 to register internal fields of found wrappers. | 6234 * Called by v8 to register internal fields of found wrappers. |
6232 * | 6235 * |
6233 * The embedder is expected to store them somewhere and trace reachable | 6236 * The embedder is expected to store them somewhere and trace reachable |
6234 * wrappers from them when called through |AdvanceTracing|. | 6237 * wrappers from them when called through |AdvanceTracing|. |
6235 */ | 6238 */ |
6236 virtual void RegisterV8References( | 6239 virtual void RegisterV8References( |
6237 const std::vector<std::pair<void*, void*> >& internal_fields) = 0; | 6240 const std::vector<std::pair<void*, void*> >& embedder_fields) = 0; |
6238 | 6241 |
6239 /** | 6242 /** |
6240 * Called at the beginning of a GC cycle. | 6243 * Called at the beginning of a GC cycle. |
6241 */ | 6244 */ |
6242 virtual void TracePrologue() = 0; | 6245 virtual void TracePrologue() = 0; |
6243 | 6246 |
6244 /** | 6247 /** |
6245 * Called to to make a tracing step in the embedder. | 6248 * Called to to make a tracing step in the embedder. |
6246 * | 6249 * |
6247 * The embedder is expected to trace its heap starting from wrappers reported | 6250 * The embedder is expected to trace its heap starting from wrappers reported |
(...skipping 42 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6290 */ | 6293 */ |
6291 struct SerializeInternalFieldsCallback { | 6294 struct SerializeInternalFieldsCallback { |
6292 typedef StartupData (*CallbackFunction)(Local<Object> holder, int index, | 6295 typedef StartupData (*CallbackFunction)(Local<Object> holder, int index, |
6293 void* data); | 6296 void* data); |
6294 SerializeInternalFieldsCallback(CallbackFunction function = nullptr, | 6297 SerializeInternalFieldsCallback(CallbackFunction function = nullptr, |
6295 void* data_arg = nullptr) | 6298 void* data_arg = nullptr) |
6296 : callback(function), data(data_arg) {} | 6299 : callback(function), data(data_arg) {} |
6297 CallbackFunction callback; | 6300 CallbackFunction callback; |
6298 void* data; | 6301 void* data; |
6299 }; | 6302 }; |
| 6303 // Note that these fields are called "internal fields" in the API and called |
| 6304 // "embedder fields" within V8. |
| 6305 typedef SerializeInternalFieldsCallback SerializeEmbedderFieldsCallback; |
6300 | 6306 |
6301 /** | 6307 /** |
6302 * Callback and supporting data used to implement embedder logic to deserialize | 6308 * Callback and supporting data used to implement embedder logic to deserialize |
6303 * internal fields. | 6309 * internal fields. |
6304 */ | 6310 */ |
6305 struct DeserializeInternalFieldsCallback { | 6311 struct DeserializeInternalFieldsCallback { |
6306 typedef void (*CallbackFunction)(Local<Object> holder, int index, | 6312 typedef void (*CallbackFunction)(Local<Object> holder, int index, |
6307 StartupData payload, void* data); | 6313 StartupData payload, void* data); |
6308 DeserializeInternalFieldsCallback(CallbackFunction function = nullptr, | 6314 DeserializeInternalFieldsCallback(CallbackFunction function = nullptr, |
6309 void* data_arg = nullptr) | 6315 void* data_arg = nullptr) |
6310 : callback(function), data(data_arg) {} | 6316 : callback(function), data(data_arg) {} |
6311 void (*callback)(Local<Object> holder, int index, StartupData payload, | 6317 void (*callback)(Local<Object> holder, int index, StartupData payload, |
6312 void* data); | 6318 void* data); |
6313 void* data; | 6319 void* data; |
6314 }; | 6320 }; |
| 6321 typedef DeserializeInternalFieldsCallback DeserializeEmbedderFieldsCallback; |
6315 | 6322 |
6316 /** | 6323 /** |
6317 * Isolate represents an isolated instance of the V8 engine. V8 isolates have | 6324 * Isolate represents an isolated instance of the V8 engine. V8 isolates have |
6318 * completely separate states. Objects from one isolate must not be used in | 6325 * completely separate states. Objects from one isolate must not be used in |
6319 * other isolates. The embedder can create multiple isolates and use them in | 6326 * other isolates. The embedder can create multiple isolates and use them in |
6320 * parallel in multiple threads. An isolate can be entered by at most one | 6327 * parallel in multiple threads. An isolate can be entered by at most one |
6321 * thread at any given time. The Locker/Unlocker API must be used to | 6328 * thread at any given time. The Locker/Unlocker API must be used to |
6322 * synchronize. | 6329 * synchronize. |
6323 */ | 6330 */ |
6324 class V8_EXPORT Isolate { | 6331 class V8_EXPORT Isolate { |
(...skipping 1732 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
8057 /** | 8064 /** |
8058 * Create a new context from a (non-default) context snapshot. There | 8065 * Create a new context from a (non-default) context snapshot. There |
8059 * is no way to provide a global object template since we do not create | 8066 * is no way to provide a global object template since we do not create |
8060 * a new global object from template, but we can reuse a global object. | 8067 * a new global object from template, but we can reuse a global object. |
8061 * | 8068 * |
8062 * \param isolate See v8::Context::New. | 8069 * \param isolate See v8::Context::New. |
8063 * | 8070 * |
8064 * \param context_snapshot_index The index of the context snapshot to | 8071 * \param context_snapshot_index The index of the context snapshot to |
8065 * deserialize from. Use v8::Context::New for the default snapshot. | 8072 * deserialize from. Use v8::Context::New for the default snapshot. |
8066 * | 8073 * |
8067 * \param internal_fields_deserializer Optional callback to deserialize | 8074 * \param embedder_fields_deserializer Optional callback to deserialize |
8068 * internal fields. It should match the SerializeInternalFieldCallback used | 8075 * internal fields. It should match the SerializeInternalFieldCallback used |
8069 * to serialize. | 8076 * to serialize. |
8070 * | 8077 * |
8071 * \param extensions See v8::Context::New. | 8078 * \param extensions See v8::Context::New. |
8072 * | 8079 * |
8073 * \param global_object See v8::Context::New. | 8080 * \param global_object See v8::Context::New. |
8074 */ | 8081 */ |
8075 | 8082 |
8076 static MaybeLocal<Context> FromSnapshot( | 8083 static MaybeLocal<Context> FromSnapshot( |
8077 Isolate* isolate, size_t context_snapshot_index, | 8084 Isolate* isolate, size_t context_snapshot_index, |
8078 DeserializeInternalFieldsCallback internal_fields_deserializer = | 8085 DeserializeInternalFieldsCallback embedder_fields_deserializer = |
8079 DeserializeInternalFieldsCallback(), | 8086 DeserializeInternalFieldsCallback(), |
8080 ExtensionConfiguration* extensions = nullptr, | 8087 ExtensionConfiguration* extensions = nullptr, |
8081 MaybeLocal<Value> global_object = MaybeLocal<Value>()); | 8088 MaybeLocal<Value> global_object = MaybeLocal<Value>()); |
8082 | 8089 |
8083 /** | 8090 /** |
8084 * Returns an global object that isn't backed by an actual context. | 8091 * Returns an global object that isn't backed by an actual context. |
8085 * | 8092 * |
8086 * The global template needs to have access checks with handlers installed. | 8093 * The global template needs to have access checks with handlers installed. |
8087 * If an existing global object is passed in, the global object is detached | 8094 * If an existing global object is passed in, the global object is detached |
8088 * from its context. | 8095 * from its context. |
(...skipping 558 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
8647 template <class T> | 8654 template <class T> |
8648 Local<T> MaybeLocal<T>::ToLocalChecked() { | 8655 Local<T> MaybeLocal<T>::ToLocalChecked() { |
8649 if (V8_UNLIKELY(val_ == nullptr)) V8::ToLocalEmpty(); | 8656 if (V8_UNLIKELY(val_ == nullptr)) V8::ToLocalEmpty(); |
8650 return Local<T>(val_); | 8657 return Local<T>(val_); |
8651 } | 8658 } |
8652 | 8659 |
8653 | 8660 |
8654 template <class T> | 8661 template <class T> |
8655 void* WeakCallbackInfo<T>::GetInternalField(int index) const { | 8662 void* WeakCallbackInfo<T>::GetInternalField(int index) const { |
8656 #ifdef V8_ENABLE_CHECKS | 8663 #ifdef V8_ENABLE_CHECKS |
8657 if (index < 0 || index >= kInternalFieldsInWeakCallback) { | 8664 if (index < 0 || index >= kEmbedderFieldsInWeakCallback) { |
8658 V8::InternalFieldOutOfBounds(index); | 8665 V8::InternalFieldOutOfBounds(index); |
8659 } | 8666 } |
8660 #endif | 8667 #endif |
8661 return internal_fields_[index]; | 8668 return embedder_fields_[index]; |
8662 } | 8669 } |
8663 | 8670 |
8664 | 8671 |
8665 template <class T> | 8672 template <class T> |
8666 T* PersistentBase<T>::New(Isolate* isolate, T* that) { | 8673 T* PersistentBase<T>::New(Isolate* isolate, T* that) { |
8667 if (that == NULL) return NULL; | 8674 if (that == NULL) return NULL; |
8668 internal::Object** p = reinterpret_cast<internal::Object**>(that); | 8675 internal::Object** p = reinterpret_cast<internal::Object**>(that); |
8669 return reinterpret_cast<T*>( | 8676 return reinterpret_cast<T*>( |
8670 V8::GlobalizeReference(reinterpret_cast<internal::Isolate*>(isolate), | 8677 V8::GlobalizeReference(reinterpret_cast<internal::Isolate*>(isolate), |
8671 p)); | 8678 p)); |
(...skipping 1159 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
9831 */ | 9838 */ |
9832 | 9839 |
9833 | 9840 |
9834 } // namespace v8 | 9841 } // namespace v8 |
9835 | 9842 |
9836 | 9843 |
9837 #undef TYPE_CHECK | 9844 #undef TYPE_CHECK |
9838 | 9845 |
9839 | 9846 |
9840 #endif // INCLUDE_V8_H_ | 9847 #endif // INCLUDE_V8_H_ |
OLD | NEW |