- Clarify the order of setting the interrupt bit and posting a message in

runtime/vm/dart_api_impl.cc

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 #include "include/dart_api.h"
 #include "include/dart_mirrors_api.h"
 #include "include/dart_native_api.h"
 
 #include "platform/assert.h"
 #include "vm/class_finalizer.h"
@@ skipping 1583 matching lines @@
 }
 
 
 DART_EXPORT void Dart_InterruptIsolate(Dart_Isolate isolate) {
   TRACE_API_CALL(CURRENT_FUNC);
   if (isolate == NULL) {
     FATAL1("%s expects argument 'isolate' to be non-null.",  CURRENT_FUNC);
   }
   // TODO(16615): Validate isolate parameter.
   Isolate* iso = reinterpret_cast<Isolate*>(isolate);
+  // Schedule the interrupt. The isolate will notice this bit being set if it
+  // is currently executing in Dart code.
   iso->ScheduleInterrupts(Isolate::kApiInterrupt);
+  // If the isolate is blocked on the message queue, we post a dummy message
+  // to the isolate's main port. The message will be ultimately ignored, but as
+  // part of handling the message the interrupt bit which was set above will be
+  // honored.
   // Can't use Dart_Post() since there isn't a current isolate.
   Dart_CObject api_null = { Dart_CObject_kNull , { 0 } };
   Dart_PostCObject(iso->main_port(), &api_null);
 }
 
 
 DART_EXPORT bool Dart_IsolateMakeRunnable(Dart_Isolate isolate) {
   CHECK_NO_ISOLATE(Isolate::Current());
   if (isolate == NULL) {
     FATAL1("%s expects argument 'isolate' to be non-null.",  CURRENT_FUNC);
@@ skipping 4406 matching lines @@
   ASSERT(stream != NULL);
   TimelineEvent* event = stream->StartEvent();
   if (event != NULL) {
     event->AsyncEnd(label, async_id);
     event->Complete();
   }
   return Api::Success();
 }
 
 }  // namespace dart