ppapi/api/pp_completion_callback.idl

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