PPAPI: Make CompletionCallbacks work right on background threads.

ppapi/c/pp_completion_callback.h

Index: ppapi/c/pp_completion_callback.h
diff --git a/ppapi/c/pp_completion_callback.h b/ppapi/c/pp_completion_callback.h
index 911302ff1e6c155970e795fb8726f4c0fc213e48..6619ca4f1aefe78c91e5a686a6ec8e3a469c54b8 100644
--- a/ppapi/c/pp_completion_callback.h
+++ b/ppapi/c/pp_completion_callback.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From pp_completion_callback.idl modified Wed Oct  5 14:06:02 2011. */
+/* From pp_completion_callback.idl modified Wed Nov  7 11:20:18 2012. */
 
 #ifndef PPAPI_C_PP_COMPLETION_CALLBACK_H_
 #define PPAPI_C_PP_COMPLETION_CALLBACK_H_
@@ -51,7 +51,13 @@ typedef enum {
    * 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,
   /**
@@ -63,7 +69,10 @@ typedef enum {
    * 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
 } PP_CompletionCallback_Flag;
@@ -77,25 +86,60 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_CompletionCallback_Flag, 4);
  * @{
  */
 /**
- * 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.
+ * <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.
  *
- * 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).
+ * 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).
  */
 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;
   /**
@@ -122,7 +166,13 @@ struct PP_CompletionCallback {
  * 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);