ppapi/c/pp_completion_callback.h

   1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /* From pp_completion_callback.idl modified Thu May  9 14:59:57 2013. */
   7
   8 #ifndef PPAPI_C_PP_COMPLETION_CALLBACK_H_
   9 #define PPAPI_C_PP_COMPLETION_CALLBACK_H_
  10
  11 #include "ppapi/c/pp_macros.h"
  12 #include "ppapi/c/pp_stdint.h"
  13
  14 /**
  15  * @file
  16  * This file defines the API to create and run a callback.
  17  */
  18
  19
  20 /**
  21  * @addtogroup Typedefs
  22  * @{
  23  */
  24 /**
  25  * This typedef defines the signature that you implement to receive callbacks
  26  * on asynchronous completion of an operation.
  27  *
  28  * @param[in] user_data A pointer to user data passed to a callback function.
  29  * @param[in] result If result is 0 (PP_OK), the operation succeeded.  Negative
  30  * values (other than -1 or PP_OK_COMPLETE) indicate error and are specified
  31  * in pp_errors.h. Positive values for result usually indicate success and have
  32  * some operation-dependent meaning (such as bytes read).
  33  */
  34 typedef void (*PP_CompletionCallback_Func)(void* user_data, int32_t result);
  35 /**
  36  * @}
  37  */
  38
  39 /**
  40  * @addtogroup Enums
  41  * @{
  42  */
  43 /**
  44  * This enumeration contains flags used to control how non-NULL callbacks are
  45  * scheduled by asynchronous methods.
  46  */
  47 typedef enum {
  48   /**
  49    * By default any non-NULL callback will always invoked asynchronously,
  50    * on success or error, even if the operation could complete synchronously
  51    * without blocking.
  52    *
  53    * The method taking such callback will always return PP_OK_COMPLETIONPENDING.
  54    * The callback will be invoked on the same thread on which the method was
  55    * invoked.
  56    *
  57    * NOTE: If the method taking the callback is invoked on a background
  58    * thread that has no valid PPB_MessageLoop resource attached, the system has
  59    * no way to run the callback on the correct thread. In this case, a log
  60    * message will be emitted and the plugin will be made to crash.
  61    */
  62   PP_COMPLETIONCALLBACK_FLAG_NONE = 0 << 0,
  63   /**
  64    * This flag allows any method taking such callback to complete synchronously
  65    * and not call the callback if the operation would not block. This is useful
  66    * when performance is an issue, and the operation bandwidth should not be
  67    * limited to the processing speed of the message loop.
  68    *
  69    * On synchronous method completion, the completion result will be returned
  70    * by the method itself. Otherwise, the method will return
  71    * PP_OK_COMPLETIONPENDING, and the callback will be invoked asynchronously on
  72    * the same thread on which the method was invoked. If there is no valid
  73    * PPB_MessageLoop attached to that thread, and the callback would normally
  74    * run asynchronously, the invoked method will return
  75    * PP_ERROR_NO_MESSAGE_LOOP.
  76    */
  77   PP_COMPLETIONCALLBACK_FLAG_OPTIONAL = 1 << 0
  78 } PP_CompletionCallback_Flag;
  79 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_CompletionCallback_Flag, 4);
  80 /**
  81  * @}
  82  */
  83
  84 /**
  85  * @addtogroup Structs
  86  * @{
  87  */
  88 /**
  89  * <code>PP_CompletionCallback</code> is a common mechanism for supporting
  90  * potentially asynchronous calls in browser interfaces. Any method that takes a
  91  * <code>PP_CompletionCallback</code> can be used in one of three different
  92  * ways:
  93  *   - Required: The callback will always be invoked asynchronously on the
  94  *               thread where the associated PPB method was invoked. The method
  95  *               will always return PP_OK_COMPLETIONPENDING when a required
  96  *               callback, and the callback will be invoked later (barring
  97  *               system or thread shutdown; see PPB_MessageLoop for details).
  98  *               Required callbacks are the default.
  99  *               <br /><br />
 100  *               NOTE: If you use a required callback on a background thread,
 101  *               you must have created and attached a PPB_MessageLoop.
 102  *               Otherwise, the system can not run your callback on that thread,
 103  *               and will instead emit a log message and crash your plugin to
 104  *               make the problem more obvious.
 105  *
 106  *   - Optional: The callback may be invoked asynchronously, or the PPB method
 107  *               may complete synchronously if it can do so without blocking.
 108  *               If the method will complete asynchronously, it will return
 109  *               PP_OK_COMPLETIONPENDING. Otherwise, it will complete
 110  *               synchronously and return an appropriate code (see below for
 111  *               more information on the return code). Optional callbacks are
 112  *               generally more difficult to use correctly than Required
 113  *               callbacks, but can provide better performance for some APIs
 114  *               (especially APIs with buffered reads, such as PPB_URLLoader or
 115  *               PPB_FileIO).
 116  *               <br /><br />
 117  *               NOTE: If you use an optional callback on a background thread,
 118  *               and you have not created and attached a PPB_MessageLoop, then
 119  *               the method you invoke will fail without running and return
 120  *               PP_ERROR_NO_MESSAGE_LOOP.
 121  *
 122  *   - Blocking: In this case, the callback's function pointer is NULL, and the
 123  *               invoked method must complete synchronously. The method will
 124  *               run to completion and return an appropriate code when finished
 125  *               (see below for more information). Blocking completion
 126  *               callbacks are only supported on background threads.
 127  *               <br /><br />
 128  *               <code>PP_BlockUntilComplete()</code> provides a convenient way
 129  *               to specify blocking behavior. Refer to
 130  *               <code>PP_BlockUntilComplete</code> for more information.
 131  *
 132  * When the callback is run asynchronously, the result parameter passed to
 133  * <code>func</code> is an int32_t that, if negative indicates an error code
 134  * whose meaning is specific to the calling method (refer to
 135  * <code>pp_error.h</code> for further information). A positive or 0 value is a
 136  * return result indicating success whose meaning depends on the calling method
 137  * (e.g. number of bytes read).
 138  */
 139 struct PP_CompletionCallback {
 140   /**
 141    * This value is a callback function that will be called, or NULL if this is
 142    * a blocking completion callback.
 143    */
 144   PP_CompletionCallback_Func func;
 145   /**
 146    * This value is a pointer to user data passed to a callback function.
 147    */
 148   void* user_data;
 149   /**
 150    * Flags used to control how non-NULL callbacks are scheduled by
 151    * asynchronous methods.
 152    */
 153   int32_t flags;
 154 };
 155 /**
 156  * @}
 157  */
 158
 159 #include <stdlib.h>
 160
 161 /**
 162  * @addtogroup Functions
 163  * @{
 164  */
 165 /**
 166  * PP_MakeCompletionCallback() is used to create a
 167  * <code>PP_CompletionCallback</code>.
 168  *
 169  * <strong>Example, creating a Required callback:</strong>
 170  *
 171  * @code
 172  * struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
 173  * @endcode
 174  *
 175  * <strong>Example, creating an Optional callback:</strong>
 176  *
 177  * @code
 178  * struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
 179  * cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
 180  * @endcode
 181  *
 182  * @param[in] func A <code>PP_CompletionCallback_Func</code> that will be
 183  * called.
 184  * @param[in] user_data A pointer to user data passed to your callback
 185  * function. This is optional and is typically used to help track state
 186  * when you may have multiple callbacks pending.
 187  *
 188  * @return A <code>PP_CompletionCallback</code> structure.
 189  */
 190 PP_INLINE struct PP_CompletionCallback PP_MakeCompletionCallback(
 191     PP_CompletionCallback_Func func,
 192     void* user_data) {
 193   struct PP_CompletionCallback cc;
 194   cc.func = func;
 195   cc.user_data = user_data;
 196   cc.flags = PP_COMPLETIONCALLBACK_FLAG_NONE;
 197   return cc;
 198 }
 199
 200 /**
 201  * PP_MakeOptionalCompletionCallback() is used to create a PP_CompletionCallback
 202  * with PP_COMPLETIONCALLBACK_FLAG_OPTIONAL set.
 203  *
 204  * @param[in] func A PP_CompletionCallback_Func to be called on completion.
 205  * @param[in] user_data A pointer to user data passed to be passed to the
 206  * callback function. This is optional and is typically used to help track state
 207  * in case of multiple pending callbacks.
 208  *
 209  * @return A PP_CompletionCallback structure.
 210  */
 211 PP_INLINE struct PP_CompletionCallback PP_MakeOptionalCompletionCallback(
 212     PP_CompletionCallback_Func func,
 213     void* user_data) {
 214   struct PP_CompletionCallback cc = PP_MakeCompletionCallback(func, user_data);
 215   cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
 216   return cc;
 217 }
 218 /**
 219  * @}
 220  */
 221
 222 /**
 223  * @addtogroup Functions
 224  * @{
 225  */
 226
 227 /**
 228  * PP_RunCompletionCallback() is used to run a callback. It invokes
 229  * the callback function passing it user data specified on creation and
 230  * completion |result|.
 231  *
 232  * @param[in] cc A pointer to a <code>PP_CompletionCallback</code> that will be
 233  * run.
 234  * @param[in] result The result of the operation. Non-positive values correspond
 235  * to the error codes from pp_errors.h (excluding PP_OK_COMPLETIONPENDING).
 236  * Positive values indicate additional information such as bytes read.
 237  */
 238 PP_INLINE void PP_RunCompletionCallback(struct PP_CompletionCallback* cc,
 239                                         int32_t result) {
 240   cc->func(cc->user_data, result);
 241 }
 242
 243 /**
 244  * @}
 245  */
 246
 247 /**
 248  * @addtogroup Functions
 249  * @{
 250  */
 251
 252  /**
 253  * PP_BlockUntilComplete() is used in place of an actual completion callback
 254  * to request blocking behavior. If specified, the calling thread will block
 255  * until the function completes. Blocking completion callbacks are only allowed
 256  * from background threads.
 257  *
 258  * @return A <code>PP_CompletionCallback</code> structure.
 259  */
 260 PP_INLINE struct PP_CompletionCallback PP_BlockUntilComplete(void) {
 261   return PP_MakeCompletionCallback(NULL, NULL);
 262 }
 263
 264 /**
 265  * PP_RunAndClearCompletionCallback() runs a callback and clears the reference
 266  * to that callback.
 267  *
 268  * This function is used when the null-ness of a completion callback is used as
 269  * a signal for whether a completion callback has been registered. In this
 270  * case, after the execution of the callback, it should be cleared. However,
 271  * this introduces a conflict if the completion callback wants to schedule more
 272  * work that involves the same completion callback again (for example, when
 273  * reading data from an URLLoader, one would typically queue up another read
 274  * callback). As a result, this function clears the pointer
 275  * before the provided callback is executed.
 276  */
 277 PP_INLINE void PP_RunAndClearCompletionCallback(
 278     struct PP_CompletionCallback* cc,
 279     int32_t res) {
 280   struct PP_CompletionCallback temp = *cc;
 281   *cc = PP_BlockUntilComplete();
 282   PP_RunCompletionCallback(&temp, res);
 283 }
 284 /**
 285  * @}
 286  */
 287
 288 #endif  /* PPAPI_C_PP_COMPLETION_CALLBACK_H_ */
 289