Document DeferredHandleScope

R=jochen@chromium.org

Change-Id: I34bc156c3c4911ba8511ba9720fb6cc2e3880d7e
Reviewed-on: https://chromium-review.googlesource.com/468888Reviewed-by: Jochen Eisinger <jochen@chromium.org>
Commit-Queue: Andreas Haas <ahaas@chromium.org>
Cr-Commit-Position: refs/heads/master@{#44407}

src/handles.cc

@@ -167,6 +167,9 @@ DeferredHandleScope::DeferredHandleScope(Isolate* isolate)
   HandleScopeData* data = impl_->isolate()->handle_scope_data();
   Object** new_next = impl_->GetSpareOrNewBlock();
   Object** new_limit = &new_next[kHandleBlockSize];
+  // Check that at least one HandleScope exists, see the class description.
+  DCHECK(!impl_->blocks()->is_empty());
+  // Check that we are not in a SealedHandleScope.
   DCHECK(data->limit == &impl_->blocks()->last()[kHandleBlockSize]);
   impl_->blocks()->Add(new_next);
 

src/handles.h

@@ -354,6 +354,26 @@ class V8_EXPORT_PRIVATE CanonicalHandleScope final {
   friend class HandleScope;
 };
 
+// A DeferredHandleScope is a HandleScope in which handles are not destroyed
+// when the DeferredHandleScope is left. Instead the DeferredHandleScope has to
+// be detached with {Detach}, and the result of {Detach} has to be destroyed
+// explicitly. A DeferredHandleScope should only be used with the following
+// design pattern:
+// 1) Open a HandleScope (not a DeferredHandleScope).
+//    HandleScope scope(isolate_);
+// 2) Create handles.
+//    Handle<Object> h1 = handle(object1, isolate);
+//    Handle<Object> h2 = handle(object2, isolate);
+// 3) Open a DeferredHandleScope.
+//    DeferredHandleScope deferred_scope(isolate);
+// 4) Reopen handles which should be in the DeferredHandleScope, e.g only h1.
+//    h1 = handle(*h1, isolate);
+// 5) Detach the DeferredHandleScope.
+//    DeferredHandles* deferred_handles = deferred_scope.Detach();
+// 6) Destroy the deferred handles.
+//    delete deferred_handles;
+//
+// Note: A DeferredHandleScope must not be opened within a DeferredHandleScope.
 class V8_EXPORT_PRIVATE DeferredHandleScope final {
  public:
   explicit DeferredHandleScope(Isolate* isolate);
@@ -369,7 +389,7 @@ class V8_EXPORT_PRIVATE DeferredHandleScope final {
   HandleScopeImplementer* impl_;
 
 #ifdef DEBUG
-  bool handles_detached_;
+  bool handles_detached_ = false;
   int prev_level_;
 #endif