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 450 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
461 | 461 |
462 | 462 |
463 // kParameter will pass a void* parameter back to the callback, kInternalFields | 463 // kParameter will pass a void* parameter back to the callback, kInternalFields |
464 // will pass the first two internal fields back to the callback, kFinalizer | 464 // will pass the first two internal fields back to the callback, kFinalizer |
465 // will pass a void* parameter back, but is invoked before the object is | 465 // will pass a void* parameter back, but is invoked before the object is |
466 // actually collected, so it can be resurrected. In the last case, it is not | 466 // actually collected, so it can be resurrected. In the last case, it is not |
467 // possible to request a second pass callback. | 467 // possible to request a second pass callback. |
468 enum class WeakCallbackType { kParameter, kInternalFields, kFinalizer }; | 468 enum class WeakCallbackType { kParameter, kInternalFields, kFinalizer }; |
469 | 469 |
470 /** | 470 /** |
| 471 * A reporter class that embedder will use to report reachable references found |
| 472 * by EmbedderHeapTracer. |
| 473 */ |
| 474 class V8_EXPORT EmbedderReachableReferenceReporter { |
| 475 public: |
| 476 virtual void ReportExternalReference(Value* object) = 0; |
| 477 virtual ~EmbedderReachableReferenceReporter() = default; |
| 478 }; |
| 479 |
| 480 /** |
471 * An object reference that is independent of any handle scope. Where | 481 * An object reference that is independent of any handle scope. Where |
472 * a Local handle only lives as long as the HandleScope in which it was | 482 * a Local handle only lives as long as the HandleScope in which it was |
473 * allocated, a PersistentBase handle remains valid until it is explicitly | 483 * allocated, a PersistentBase handle remains valid until it is explicitly |
474 * disposed. | 484 * disposed. |
475 * | 485 * |
476 * A persistent handle contains a reference to a storage cell within | 486 * A persistent handle contains a reference to a storage cell within |
477 * the v8 engine which holds an object value and which is updated by | 487 * the v8 engine which holds an object value and which is updated by |
478 * the garbage collector whenever the object is moved. A new storage | 488 * the garbage collector whenever the object is moved. A new storage |
479 * cell can be created using the constructor or PersistentBase::Reset and | 489 * cell can be created using the constructor or PersistentBase::Reset and |
480 * existing handles can be disposed using PersistentBase::Reset. | 490 * existing handles can be disposed using PersistentBase::Reset. |
(...skipping 76 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
557 */ | 567 */ |
558 V8_INLINE void SetWeak(); | 568 V8_INLINE void SetWeak(); |
559 | 569 |
560 template<typename P> | 570 template<typename P> |
561 V8_INLINE P* ClearWeak(); | 571 V8_INLINE P* ClearWeak(); |
562 | 572 |
563 // TODO(dcarney): remove this. | 573 // TODO(dcarney): remove this. |
564 V8_INLINE void ClearWeak() { ClearWeak<void>(); } | 574 V8_INLINE void ClearWeak() { ClearWeak<void>(); } |
565 | 575 |
566 /** | 576 /** |
| 577 * Deprecated. |
| 578 * TODO(hlopko): remove once migration to reporter is finished. |
| 579 */ |
| 580 V8_INLINE void RegisterExternalReference(Isolate* isolate) const {} |
| 581 |
| 582 /** |
567 * Allows the embedder to tell the v8 garbage collector that a certain object | 583 * Allows the embedder to tell the v8 garbage collector that a certain object |
568 * is alive. Only allowed when the embedder is asked to trace its heap by | 584 * is alive. Only allowed when the embedder is asked to trace its heap by |
569 * EmbedderHeapTracer. | 585 * EmbedderHeapTracer. |
570 */ | 586 */ |
571 V8_INLINE void RegisterExternalReference(Isolate* isolate) const; | 587 V8_INLINE void RegisterExternalReference( |
| 588 EmbedderReachableReferenceReporter* reporter) const; |
572 | 589 |
573 /** | 590 /** |
574 * Marks the reference to this object independent. Garbage collector is free | 591 * Marks the reference to this object independent. Garbage collector is free |
575 * to ignore any object groups containing this object. Weak callback for an | 592 * to ignore any object groups containing this object. Weak callback for an |
576 * independent handle should not assume that it will be preceded by a global | 593 * independent handle should not assume that it will be preceded by a global |
577 * GC prologue callback or followed by a global GC epilogue callback. | 594 * GC prologue callback or followed by a global GC epilogue callback. |
578 */ | 595 */ |
579 V8_INLINE void MarkIndependent(); | 596 V8_INLINE void MarkIndependent(); |
580 | 597 |
581 /** | 598 /** |
(...skipping 5485 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6067 * of higher latency due to garbage collection pauses. | 6084 * of higher latency due to garbage collection pauses. |
6068 * kCritical hints V8 to free memory as soon as possible. Garbage collection | 6085 * kCritical hints V8 to free memory as soon as possible. Garbage collection |
6069 * pauses at this level will be large. | 6086 * pauses at this level will be large. |
6070 */ | 6087 */ |
6071 enum class MemoryPressureLevel { kNone, kModerate, kCritical }; | 6088 enum class MemoryPressureLevel { kNone, kModerate, kCritical }; |
6072 | 6089 |
6073 /** | 6090 /** |
6074 * Interface for tracing through the embedder heap. During the v8 garbage | 6091 * Interface for tracing through the embedder heap. During the v8 garbage |
6075 * collection, v8 collects hidden fields of all potential wrappers, and at the | 6092 * collection, v8 collects hidden fields of all potential wrappers, and at the |
6076 * end of its marking phase iterates the collection and asks the embedder to | 6093 * end of its marking phase iterates the collection and asks the embedder to |
6077 * trace through its heap and call PersistentBase::RegisterExternalReference on | 6094 * trace through its heap and use reporter to report each js object reachable |
6078 * each js object reachable from any of the given wrappers. | 6095 * from any of the given wrappers. |
6079 * | 6096 * |
6080 * Before the first call to the TraceWrappersFrom function TracePrologue will be | 6097 * Before the first call to the TraceWrappersFrom function TracePrologue will be |
6081 * called. When the garbage collection cycle is finished, TraceEpilogue will be | 6098 * called. When the garbage collection cycle is finished, TraceEpilogue will be |
6082 * called. | 6099 * called. |
6083 */ | 6100 */ |
6084 class V8_EXPORT EmbedderHeapTracer { | 6101 class V8_EXPORT EmbedderHeapTracer { |
6085 public: | 6102 public: |
6086 enum ForceCompletionAction { FORCE_COMPLETION, DO_NOT_FORCE_COMPLETION }; | 6103 enum ForceCompletionAction { FORCE_COMPLETION, DO_NOT_FORCE_COMPLETION }; |
6087 | 6104 |
6088 struct AdvanceTracingActions { | 6105 struct AdvanceTracingActions { |
6089 explicit AdvanceTracingActions(ForceCompletionAction force_completion_) | 6106 explicit AdvanceTracingActions(ForceCompletionAction force_completion_) |
6090 : force_completion(force_completion_) {} | 6107 : force_completion(force_completion_) {} |
6091 | 6108 |
6092 ForceCompletionAction force_completion; | 6109 ForceCompletionAction force_completion; |
6093 }; | 6110 }; |
6094 | 6111 |
6095 /** | 6112 /** |
6096 * V8 will call this method with internal fields of found wrappers. The | 6113 * V8 will call this method with internal fields of found wrappers. The |
6097 * embedder is expected to store them in its marking deque and trace | 6114 * embedder is expected to store them in its marking deque and trace |
6098 * reachable wrappers from them when called through |AdvanceTracing|. | 6115 * reachable wrappers from them when called through |AdvanceTracing|. |
6099 */ | 6116 */ |
6100 virtual void RegisterV8References( | 6117 virtual void RegisterV8References( |
6101 const std::vector<std::pair<void*, void*> >& internal_fields) = 0; | 6118 const std::vector<std::pair<void*, void*> >& internal_fields) = 0; |
6102 | 6119 |
6103 /** | 6120 /** |
6104 * V8 will call this method at the beginning of a GC cycle. | 6121 * Deprecated. |
| 6122 * TODO(hlopko) Remove once the migration to reporter is finished. |
6105 */ | 6123 */ |
6106 virtual void TracePrologue() = 0; | 6124 virtual void TracePrologue() {} |
| 6125 |
| 6126 /** |
| 6127 * V8 will call this method at the beginning of a GC cycle. Embedder is |
| 6128 * expected to use EmbedderReachableReferenceReporter for reporting all |
| 6129 * reachable v8 objects. |
| 6130 */ |
| 6131 virtual void TracePrologue(EmbedderReachableReferenceReporter* reporter) {} |
6107 | 6132 |
6108 /** | 6133 /** |
6109 * Embedder is expected to trace its heap starting from wrappers reported by | 6134 * Embedder is expected to trace its heap starting from wrappers reported by |
6110 * RegisterV8References method, and call | 6135 * RegisterV8References method, and use reporter for all reachable wrappers. |
6111 * PersistentBase::RegisterExternalReference() on all reachable wrappers. | |
6112 * Embedder is expected to stop tracing by the given deadline. | 6136 * Embedder is expected to stop tracing by the given deadline. |
6113 * | 6137 * |
6114 * Returns true if there is still work to do. | 6138 * Returns true if there is still work to do. |
6115 */ | 6139 */ |
6116 virtual bool AdvanceTracing(double deadline_in_ms, | 6140 virtual bool AdvanceTracing(double deadline_in_ms, |
6117 AdvanceTracingActions actions) = 0; | 6141 AdvanceTracingActions actions) = 0; |
6118 | 6142 |
6119 /** | 6143 /** |
6120 * V8 will call this method at the end of a GC cycle. | 6144 * V8 will call this method at the end of a GC cycle. |
6121 * | 6145 * |
(...skipping 1296 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
7418 // Must be 1 or -1. | 7442 // Must be 1 or -1. |
7419 int internal_field_index2, | 7443 int internal_field_index2, |
7420 WeakCallbackInfo<void>::Callback weak_callback); | 7444 WeakCallbackInfo<void>::Callback weak_callback); |
7421 static void MakeWeak(internal::Object*** location_addr); | 7445 static void MakeWeak(internal::Object*** location_addr); |
7422 static void* ClearWeak(internal::Object** location); | 7446 static void* ClearWeak(internal::Object** location); |
7423 static void Eternalize(Isolate* isolate, | 7447 static void Eternalize(Isolate* isolate, |
7424 Value* handle, | 7448 Value* handle, |
7425 int* index); | 7449 int* index); |
7426 static Local<Value> GetEternal(Isolate* isolate, int index); | 7450 static Local<Value> GetEternal(Isolate* isolate, int index); |
7427 | 7451 |
7428 static void RegisterExternallyReferencedObject(internal::Object** object, | |
7429 internal::Isolate* isolate); | |
7430 template <class K, class V, class T> | 7452 template <class K, class V, class T> |
7431 friend class PersistentValueMapBase; | 7453 friend class PersistentValueMapBase; |
7432 | 7454 |
7433 static void FromJustIsNothing(); | 7455 static void FromJustIsNothing(); |
7434 static void ToLocalEmpty(); | 7456 static void ToLocalEmpty(); |
7435 static void InternalFieldOutOfBounds(int index); | 7457 static void InternalFieldOutOfBounds(int index); |
7436 template <class T> friend class Local; | 7458 template <class T> friend class Local; |
7437 template <class T> | 7459 template <class T> |
7438 friend class MaybeLocal; | 7460 friend class MaybeLocal; |
7439 template <class T> | 7461 template <class T> |
(...skipping 1040 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
8480 } | 8502 } |
8481 | 8503 |
8482 template <class T> | 8504 template <class T> |
8483 template <typename P> | 8505 template <typename P> |
8484 P* PersistentBase<T>::ClearWeak() { | 8506 P* PersistentBase<T>::ClearWeak() { |
8485 return reinterpret_cast<P*>( | 8507 return reinterpret_cast<P*>( |
8486 V8::ClearWeak(reinterpret_cast<internal::Object**>(this->val_))); | 8508 V8::ClearWeak(reinterpret_cast<internal::Object**>(this->val_))); |
8487 } | 8509 } |
8488 | 8510 |
8489 template <class T> | 8511 template <class T> |
8490 void PersistentBase<T>::RegisterExternalReference(Isolate* isolate) const { | 8512 void PersistentBase<T>::RegisterExternalReference( |
| 8513 EmbedderReachableReferenceReporter* reporter) const { |
8491 if (IsEmpty()) return; | 8514 if (IsEmpty()) return; |
8492 V8::RegisterExternallyReferencedObject( | 8515 reporter->ReportExternalReference(this->val_); |
8493 reinterpret_cast<internal::Object**>(this->val_), | |
8494 reinterpret_cast<internal::Isolate*>(isolate)); | |
8495 } | 8516 } |
8496 | 8517 |
8497 template <class T> | 8518 template <class T> |
8498 void PersistentBase<T>::MarkIndependent() { | 8519 void PersistentBase<T>::MarkIndependent() { |
8499 typedef internal::Internals I; | 8520 typedef internal::Internals I; |
8500 if (this->IsEmpty()) return; | 8521 if (this->IsEmpty()) return; |
8501 I::UpdateNodeFlag(reinterpret_cast<internal::Object**>(this->val_), | 8522 I::UpdateNodeFlag(reinterpret_cast<internal::Object**>(this->val_), |
8502 true, | 8523 true, |
8503 I::kNodeIsIndependentShift); | 8524 I::kNodeIsIndependentShift); |
8504 } | 8525 } |
(...skipping 1068 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
9573 */ | 9594 */ |
9574 | 9595 |
9575 | 9596 |
9576 } // namespace v8 | 9597 } // namespace v8 |
9577 | 9598 |
9578 | 9599 |
9579 #undef TYPE_CHECK | 9600 #undef TYPE_CHECK |
9580 | 9601 |
9581 | 9602 |
9582 #endif // INCLUDE_V8_H_ | 9603 #endif // INCLUDE_V8_H_ |
OLD | NEW |