PPAPI: Force async callback invocation option.

ppapi/c/pp_completion_callback.h

 /* Copyright (c) 2011 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 #ifndef PPAPI_C_PP_COMPLETION_CALLBACK_H_
 #define PPAPI_C_PP_COMPLETION_CALLBACK_H_
 
 /**
  * @file
  * This file defines the API to create and run a callback.
  */
 
 #include <stdlib.h>
 
 #include "ppapi/c/pp_macros.h"
 #include "ppapi/c/pp_stdint.h"
 
 /**
  * @addtogroup Typedefs
  * @{
  */
 
 /**
- * PP_CompletionCallback_Func defines the signature that you implement to
- * receive callbacks on asynchronous completion.
+ * PP_CompletionCallback_Func defines the function signature that you implement
+ * to receive callbacks on asynchronous completion of an operation.
+ *
+ * |user_data| is a pointer to user-specified data associated with this
+ * function at callback creation. See PP_MakeCompletionCallback() for details.
+ *
+ * |result| is the result of the operation. Non-positive values correspond to
+ * the error codes from pp_errors.h (excluding PP_OK_COMPLETIONPENDING).
+ * Positive values indicate additional information such as bytes read.
  */
 typedef void (*PP_CompletionCallback_Func)(void* user_data, int32_t result);
 /**
  * @}
  */
 
 /**
+ *
+ * @addtogroup Enums
+ * @{
+ */
+
+/**
+ * This enumeration contains flags used to control how non-NULL callbacks are
+ * scheduled by asynchronous methods.
+ */
+typedef enum {
+  /**
+   * By default, any non-NULL callback will always be invoked asynchronously,
+   * on success or error, even if the operation could complete synchronously
+   * 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.
+   */
+  PP_COMPLETIONCALLBACK_FLAG_NONE = 0 << 0,
+  /**
+   * This flag allows any method taking such callback to complete synchronously
+   * and not call the callback if the operation would not block. This is useful
+   * when performance is an issue, and the operation bandwidth should not be
+   * limited to the processing speed of the message loop.
+   *
+   * 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.
+   */
+  PP_COMPLETIONCALLBACK_FLAG_OPTIONAL = 1 << 0
+} PP_CompletionCallback_Flag;
+PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_CompletionCallback_Flag, 4);
+
+
+/**
  * @addtogroup Structs
  * @{
  */
 
-/**
- * Any method that takes a PP_CompletionCallback has the option of completing
- * asynchronously if the operation would block.  Such a method should return
- * PP_OK_COMPLETIONPENDING to indicate that the method will complete
- * asynchronously 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.  PP_BlockUntilComplete() provides a
- * convenient way to specify blocking behavior. Refer to PP_BlockUntilComplete
- * for more information.
+/* Any method that takes a PP_CompletionCallback can complete asynchronously.
+ * Refer to PP_CompletionCallback_Flag for more information.
  *
- * The result parameter passes an int32_t that, if negative or equal to 0,
- * indicate if the call will completely asynchronously (the callback will be
- * called with a status code). A value greater than zero indicates additional
- * information such as bytes read.
+ * If PP_CompletionCallback_Func is NULL, the operation might block if necessary
+ * to complete the work. Refer to PP_BlockUntilComplete for more information.
+ *
+ * See PP_MakeCompletionCallback() for the description of each field.
  */
 struct PP_CompletionCallback {
   PP_CompletionCallback_Func func;
   void* user_data;
+  int32_t flags;

[piman, 2011/06/07 17:32:14]

Because you're changing the size (and semantics) of PP_CompletionCallback, you
need to rev all or the interfaces that uses a PP_CompletionCallback

[polina, 2011/06/09 23:53:51]

Done.

 };
 /**
  * @}
  */
 
 /**
  * @addtogroup Functions
  * @{
  */
-
 /**
- * PP_MakeCompletionCallback() is used to create a PP_CompletionCallback.
+ * PP_MakeCompletionCallback() is used to create a PP_CompletionCallback
+ * without flags. If you want to alter the default callback behavior, set the
+ * flags to a bit field combination of PP_CompletionCallback_Flag's.
  *
- * @param[in] func A PP_CompletionCallback_Func that will be called.
- * @param[in] user_data A pointer to user data passed to your callback
- * function. This is optional and is typically used to help track state
- * when you may have multiple callbacks pending.
+ * Example:
+ *   struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
+ *   cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
+ *
+ * @param[in] func A PP_CompletionCallback_Func to be called on completion.
+ * @param[in] user_data A pointer to user data passed to be passed to the
+ * callback function. This is optional and is typically used to help track state
+ * in case of multiple pending callbacks.
+ *
  * @return A PP_CompletionCallback structure.
  */
 PP_INLINE struct PP_CompletionCallback PP_MakeCompletionCallback(
     PP_CompletionCallback_Func func,
     void* user_data) {
   struct PP_CompletionCallback cc;
   cc.func = func;
   cc.user_data = user_data;
+  cc.flags = PP_COMPLETIONCALLBACK_FLAG_NONE;

[piman, 2011/06/07 17:32:14]

I thought we were not going to change the default behavior. Shouldn't this be
PP_COMPLETIONCALLBACK_FLAG_OPTIONAL ?

[polina, 2011/06/09 23:53:51]

You have it backwards. The idea was to have the new default behavior - always
forcing the callbacks. See the bug by darin (linked from the CL description).

There was a discussion about the specifics and naming of the enum fields. I
reflected the resolution of the most recent discussion here.

[piman, 2011/06/10 00:51:20]

But that breaks existing plugins.... Can we do a 2-step process, first we add
the flag, then we make it the default ?

[polina, 2011/06/10 19:33:19]

This should not break any existing plugins that properly handle return codes
from functions taking callbacks. They should have the logic for
PP_OK_COMPLETIONPENDING (which is still applicable as-is) and the logic for
other values (which will now be dead code).

Do you have a specific case in mind that will suffer from this? The only thing I
can think of is tests that assert that PP_OK_COMPLETIONPENDING is not returned.

Btw, if I make this a 2-step process, will I have to rev the interfaces twice?

   return cc;
 }
 /**
  * @}
  */
 
 /**
  * @addtogroup Functions
  * @{
  */
 
 /**
- * PP_RunCompletionCallback() is used to run a callback.
+ * PP_RunCompletionCallback() is used to run a callback. It invokes
+ * the callback function passing it user data specified on creation and
+ * completion |result|.
  *
  * @param[in] cc A pointer to a PP_CompletionCallback that will be run.
- * @param[in] res The result parameter that, if negative or equal to 0,
- * indicate if the call will completely asynchronously (the callback will be
- * called with a status code). A value greater than zero indicates additional
- * information such as bytes read.
+ * @param[in] result The result of the operation. Non-positive values correspond
+ * to the error codes from pp_errors.h (excluding PP_OK_COMPLETIONPENDING).
+ * Positive values indicate additional information such as bytes read.
  */
 PP_INLINE void PP_RunCompletionCallback(struct PP_CompletionCallback* cc,
-                                        int32_t res) {
-  cc->func(cc->user_data, res);
+                                        int32_t result) {
+  cc->func(cc->user_data, result);
 }
 
 /**
  * @}
  */
 
 /**
  * @addtogroup Functions
  * @{
  */
 
  /**
  * PP_BlockUntilComplete() is used in place of an actual completion callback
  * to request blocking behavior. If specified, the calling thread will block
- * until the function completes.  Blocking completion callbacks are only usable
+ * until the function completes. Blocking completion callbacks are only allowed
  * from background threads.
  *
- * @return A PP_CompletionCallback structure.
+ * @return A PP_CompletionCallback structure corresponding to a NULL callback.
  */
 PP_INLINE struct PP_CompletionCallback PP_BlockUntilComplete() {
   return PP_MakeCompletionCallback(NULL, NULL);
 }
 
 /**
  * Runs a callback and clears the reference to it.
  *
  * This is used when the null-ness of a completion callback is used as a signal
  * for whether a completion callback has been registered. In this case, after
@@ skipping 10 matching lines @@
     int32_t res) {
   struct PP_CompletionCallback temp = *cc;
   *cc = PP_BlockUntilComplete();
   PP_RunCompletionCallback(&temp, res);
 }
 /**
  * @}
  */
 
 #endif  /* PPAPI_C_PP_COMPLETION_CALLBACK_H_ */