Add comments for RasterBufferProvider synchronization methods.

Also adds comments explaining the implementation of them in
OneCopyRasterBufferProvider.

R=piman@chromium.org, sunnyps@chromium.org

Bug: 730660
Cq-Include-Trybots: master.tryserver.blink:linux_trusty_blink_rel;master.tryserver.chromium.android:android_optional_gpu_tests_rel
Change-Id: I02a762a4208fcd8d317c35c49f40d36425f27126
Reviewed-on: https://chromium-review.googlesource.com/891442Reviewed-by: Antoine Labour <piman@chromium.org>
Commit-Queue: danakj <danakj@chromium.org>
Cr-Commit-Position: refs/heads/master@{#532594}

cc/raster/one_copy_raster_buffer_provider.cc

@@ -117,6 +117,11 @@ OneCopyRasterBufferProvider::AcquireBufferForRaster(
 void OneCopyRasterBufferProvider::OrderingBarrier() {
   TRACE_EVENT0("cc", "OneCopyRasterBufferProvider::OrderingBarrier");
 
+  // This inserts a SyncToken on the compositor thread for the texture and
+  // mailbox created there, which will we written to on the worker thread.
+  // The SyncToken will be waited on and block the worker context's commands
+  // from running until it is flushed, which does not happen here, as we delay
+  // it to run less of them.
   gpu::gles2::GLES2Interface* gl = compositor_context_provider_->ContextGL();
   gpu::SyncToken sync_token =
       LayerTreeResourceProvider::GenerateSyncTokenHelper(gl);
@@ -126,6 +131,11 @@ void OneCopyRasterBufferProvider::OrderingBarrier() {
 }
 
 void OneCopyRasterBufferProvider::Flush() {
+  // This flush on the compositor context flushes queued work on all contexts,
+  // including the raster worker. Tile raster inserted a SyncToken which is
+  // waited for in order to tell if a tile is ready for draw, but a flush
+  // is needed to ensure the work is sent for those queries to get the right
+  // answer.
   compositor_context_provider_->ContextSupport()->FlushPendingWork();
 }
 
@@ -398,7 +408,8 @@ void OneCopyRasterBufferProvider::CopyOnWorkerThread(
 
   ri->DeleteTextures(1, &texture_id);
 
-  // Generate sync token for cross context synchronization.
+  // Generate sync token on the worker context that will be sent to and waited
+  // for by the display compositor before using the content generated here.
   resource_lock->set_sync_token(
       LayerTreeResourceProvider::GenerateSyncTokenHelper(ri));
 }

cc/raster/raster_buffer_provider.h

@@ -49,11 +49,17 @@ class CC_EXPORT RasterBufferProvider {
       uint64_t resource_content_id,
       uint64_t previous_content_id) = 0;
 
-  // Used for syncing resources to the worker context.
+  // Call this on the compositor thread to allow the RasterBufferProvider to
+  // insert synchronization primatives into the compositor context, which will
+  // be used by the RasterBuffer to synchronize with the worker context. Should
+  // be called once all RasterBuffers are created but before they are scheduled
+  // to run on the worker threads.
   virtual void OrderingBarrier() = 0;
 
-  // In addition to above, also ensures that pending work is sent to the GPU
-  // process.
+  // Flush pending work from writing the content of the RasterBuffer, so that
+  // queries to tell if the backing is ready to draw from will get the right
+  // answer. This should be done before calling IsResourceReadyToDraw() or
+  // SetReadyToDrawCallback().
   virtual void Flush() = 0;
 
   // Returns the format to use for the tiles.