PPAPI: Make CompletionCallbacks work right on background threads.

ppapi/api/pp_completion_callback.idl

Index: ppapi/api/pp_completion_callback.idl
diff --git a/ppapi/api/pp_completion_callback.idl b/ppapi/api/pp_completion_callback.idl
index 0dff263fb19db9c8bfebef113bc0c6340baaf3c3..6db9e2eb134121426a2bb9804c1d242b8c8637f7 100644
--- a/ppapi/api/pp_completion_callback.idl
+++ b/ppapi/api/pp_completion_callback.idl
@@ -32,7 +32,13 @@ enum PP_CompletionCallback_Flag {
    * without blocking.
    *
    * The method taking such callback will always return PP_OK_COMPLETIONPENDING.
-   * The callback will be invoked on the main thread of PPAPI execution.
+   * The callback will be invoked on the same thread on which the method was
+   * invoked.
+   *
+   * NOTE: If the method taking the callback is invoked on a background
+   * thread that has no valid PPB_MessageLoop resource attached, the system has
+   * no way to run the callback on the correct thread. In this case, a log
+   * message will be emitted and the plugin will be made to crash.
    */
   PP_COMPLETIONCALLBACK_FLAG_NONE = 0 << 0,
   /**
@@ -44,32 +50,70 @@ enum PP_CompletionCallback_Flag {
    * On synchronous method completion, the completion result will be returned
    * by the method itself. Otherwise, the method will return
    * PP_OK_COMPLETIONPENDING, and the callback will be invoked asynchronously on
-   * the main thread of PPAPI execution.
+   * the same thread on which the method was invoked. If there is no valid
+   * PPB_MessageLoop attached to that thread, and the callback would normally
+   * run asynchronously, the invoked method will return
+   * PP_ERROR_NO_MESSAGE_LOOP.
    */
   PP_COMPLETIONCALLBACK_FLAG_OPTIONAL = 1 << 0
 };
 
 
 /**
- * Any method that takes a <code>PP_CompletionCallback</code> has the option of
- * completing asynchronously if the operation would block.  Such a method
- * should return <code>PP_OK_COMPLETIONPENDING</code> to indicate that the
- * method will complete asynchronously and notify the caller and will always be
- * invoked from the main thread of PPAPI execution.  If the completion callback
- * is NULL, then the operation will block if necessary to complete its work.
- * <code>PP_BlockUntilComplete()</code> provides a convenient way to specify
- * blocking behavior. Refer to <code>PP_BlockUntilComplete</code> for more
- * information.
- *
- * The result parameter passed to <code>func</code> is an int32_t that, if
- * negative indicates an error code whose meaning is specific to the calling
- * method (refer to <code>pp_error.h</code> for further information). A
- * positive or 0 value is a return result indicating success whose meaning
- * depends on the calling method (e.g. number of bytes read).
+ * <code>PP_CompletionCallback</code> is a common mechanism for supporting
+ * potentially asynchronous calls in browser interfaces. Any method that takes a
+ * <code>PP_CompletionCallback</code> can be used in one of three different
+ * ways:
+ *   - Required: The callback will always be invoked asynchronously on the
+ *               thread where the associated PPB method was invoked. The method
+ *               will always return <code>PP_OK_COMPLETIONPENDING when a
+ *               required callback, and the callback will be invoked later
+ *               (barring system or thread shutdown; see PPB_MessageLoop for
+ *               details). Required callbacks are the default.
+ *
+ *               NOTE: If you use a required callback on a background thread,
+ *               you must have created and attached a PPB_MessageLoop.
+ *               Otherwise, the system can not run your callback on that thread,
+ *               and will instead emit a log message and crash your plugin to
+ *               make the problem more obvious.
+ *
+ *   - Optional: The callback may be invoked asynchronously, or the PPB method
+ *               may complete synchronously if it can do so without blocking.
+ *               If the method will complete asynchronously, it will return
+ *               PP_OK_COMPLETIONPENDING. Otherwise, it will complete
+ *               synchronously and return an appropriate code (see below for
+ *               more information on the return code). Optional callbacks are
+ *               generally more difficult to use correctly than Required
+ *               callbacks, but can provide better performance for some APIs
+ *               (especially APIs with buffered reads, such as PPB_URLLoader or
+ *               PPB_FileIO).
+ *
+ *               NOTE: If you use an optional callback on a background thread,
+ *               and you have not created and attached a PPB_MessageLoop, then
+ *               the method you invoke will fail without running and return
+ *               PP_ERROR_NO_MESSAGE_LOOP.
+ *
+ *   - Blocking: In this case, the callback's function pointer is NULL, and the
+ *               invoked method must complete synchronously. The method will
+ *               run to completion and return an appropriate code when finished
+ *               (see below for more information). Blocking completion
+ *               callbacks are only supported on background threads.
+ *
+ *               <code>PP_BlockUntilComplete()</code> provides a convenient way
+ *               to specify blocking behavior. Refer to
+ *                <code>PP_BlockUntilComplete</code> for more information.
+ *
+ * When the callback is run asynchronously, the result parameter passed to
+ * <code>func</code> is an int32_t that, if negative indicates an error code
+ * whose meaning is specific to the calling method (refer to
+ * <code>pp_error.h</code> for further information). A positive or 0 value is a
+ * return result indicating success whose meaning depends on the calling method
+ * (e.g. number of bytes read).
  */
 [passByValue] struct PP_CompletionCallback {
   /**
-   * This value is a callback function that will be called.
+   * This value is a callback function that will be called, or NULL if this is
+   * a blocking completion callback.
    */
   PP_CompletionCallback_Func func;
   /**
@@ -95,7 +139,13 @@ enum PP_CompletionCallback_Flag {
  * PP_MakeCompletionCallback() is used to create a
  * <code>PP_CompletionCallback</code>.
  *
- * <strong>Example:</strong>
+ * <strong>Example, creating a Required callback:</strong>
+ *
+ * <code>
+ * struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
+ * </code>
+ *
+ * <strong>Example, creating an Optional callback:</strong>
  *
  * <code>
  * struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);