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 main thread of PPAPI execution.
  36    */
  37   PP_COMPLETIONCALLBACK_FLAG_NONE = 0 << 0,
  38   /**
  39    * This flag allows any method taking such callback to complete synchronously
  40    * and not call the callback if the operation would not block. This is useful
  41    * when performance is an issue, and the operation bandwidth should not be
  42    * limited to the processing speed of the message loop.
  43    *
  44    * On synchronous method completion, the completion result will be returned
  45    * by the method itself. Otherwise, the method will return
  46    * PP_OK_COMPLETIONPENDING, and the callback will be invoked asynchronously on
  47    * the main thread of PPAPI execution.
  48    */
  49   PP_COMPLETIONCALLBACK_FLAG_OPTIONAL = 1 << 0
  50 };
  51
  52
  53 /**
  54  * Any method that takes a <code>PP_CompletionCallback</code> has the option of
  55  * completing asynchronously if the operation would block.  Such a method
  56  * should return <code>PP_OK_COMPLETIONPENDING</code> to indicate that the
  57  * method will complete asynchronously and notify the caller and will always be
  58  * invoked from the main thread of PPAPI execution.  If the completion callback
  59  * is NULL, then the operation will block if necessary to complete its work.
  60  * <code>PP_BlockUntilComplete()</code> provides a convenient way to specify
  61  * blocking behavior. Refer to <code>PP_BlockUntilComplete</code> for more
  62  * information.
  63  *
  64  * The result parameter passed to <code>func</code> is an int32_t that, if
  65  * negative indicates an error code whose meaning is specific to the calling
  66  * method (refer to <code>pp_error.h</code> for further information). A
  67  * positive or 0 value is a return result indicating success whose meaning
  68  * depends on the calling method (e.g. number of bytes read).
  69  */
  70 [passByValue] struct PP_CompletionCallback {
  71   /**
  72    * This value is a callback function that will be called.
  73    */
  74   PP_CompletionCallback_Func func;
  75   /**
  76    * This value is a pointer to user data passed to a callback function.
  77    */
  78   mem_t user_data;
  79
  80   /**
  81    * Flags used to control how non-NULL callbacks are scheduled by
  82    * asynchronous methods.
  83    */
  84   int32_t flags;
  85 };
  86
  87 #inline c
  88 #include <stdlib.h>
  89
  90 /**
  91  * @addtogroup Functions
  92  * @{
  93  */
  94 /**
  95  * PP_MakeCompletionCallback() is used to create a
  96  * <code>PP_CompletionCallback</code>.
  97  *
  98  * <strong>Example:</strong>
  99  *
 100  * <code>
 101  * struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
 102  * cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
 103  * </code>
 104  *
 105  * @param[in] func A <code>PP_CompletionCallback_Func</code> that will be
 106  * called.
 107  * @param[in] user_data A pointer to user data passed to your callback
 108  * function. This is optional and is typically used to help track state
 109  * when you may have multiple callbacks pending.
 110  *
 111  * @return A <code>PP_CompletionCallback</code> structure.
 112  */
 113 PP_INLINE struct PP_CompletionCallback PP_MakeCompletionCallback(
 114     PP_CompletionCallback_Func func,
 115     void* user_data) {
 116   struct PP_CompletionCallback cc;
 117   cc.func = func;
 118   cc.user_data = user_data;
 119   cc.flags = PP_COMPLETIONCALLBACK_FLAG_NONE;
 120   return cc;
 121 }
 122
 123 /**
 124  * PP_MakeOptionalCompletionCallback() is used to create a PP_CompletionCallback
 125  * with PP_COMPLETIONCALLBACK_FLAG_OPTIONAL set.
 126  *
 127  * @param[in] func A PP_CompletionCallback_Func to be called on completion.
 128  * @param[in] user_data A pointer to user data passed to be passed to the
 129  * callback function. This is optional and is typically used to help track state
 130  * in case of multiple pending callbacks.
 131  *
 132  * @return A PP_CompletionCallback structure.
 133  */
 134 PP_INLINE struct PP_CompletionCallback PP_MakeOptionalCompletionCallback(
 135     PP_CompletionCallback_Func func,
 136     void* user_data) {
 137   struct PP_CompletionCallback cc = PP_MakeCompletionCallback(func, user_data);
 138   cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
 139   return cc;
 140 }
 141 /**
 142  * @}
 143  */
 144
 145 /**
 146  * @addtogroup Functions
 147  * @{
 148  */
 149
 150 /**
 151  * PP_RunCompletionCallback() is used to run a callback. It invokes
 152  * the callback function passing it user data specified on creation and
 153  * completion |result|.
 154  *
 155  * @param[in] cc A pointer to a <code>PP_CompletionCallback</code> that will be
 156  * run.
 157  * @param[in] result The result of the operation. Non-positive values correspond
 158  * to the error codes from pp_errors.h (excluding PP_OK_COMPLETIONPENDING).
 159  * Positive values indicate additional information such as bytes read.
 160  */
 161 PP_INLINE void PP_RunCompletionCallback(struct PP_CompletionCallback* cc,
 162                                         int32_t result) {
 163   cc->func(cc->user_data, result);
 164 }
 165
 166 /**
 167  * @}
 168  */
 169
 170 /**
 171  * @addtogroup Functions
 172  * @{
 173  */
 174
 175  /**
 176  * PP_BlockUntilComplete() is used in place of an actual completion callback
 177  * to request blocking behavior. If specified, the calling thread will block
 178  * until the function completes. Blocking completion callbacks are only allowed
 179  * from background threads.
 180  *
 181  * @return A <code>PP_CompletionCallback</code> structure.
 182  */
 183 PP_INLINE struct PP_CompletionCallback PP_BlockUntilComplete() {
 184   return PP_MakeCompletionCallback(NULL, NULL);
 185 }
 186
 187 /**
 188  * PP_RunAndClearCompletionCallback() runs a callback and clears the reference
 189  * to that callback.
 190  *
 191  * This function is used when the null-ness of a completion callback is used as
 192  * a signal for whether a completion callback has been registered. In this
 193  * case, after the execution of the callback, it should be cleared. However,
 194  * this introduces a conflict if the completion callback wants to schedule more
 195  * work that involves the same completion callback again (for example, when
 196  * reading data from an URLLoader, one would typically queue up another read
 197  * callback). As a result, this function clears the pointer
 198  * before the provided callback is executed.
 199  */
 200 PP_INLINE void PP_RunAndClearCompletionCallback(
 201     struct PP_CompletionCallback* cc,
 202     int32_t res) {
 203   struct PP_CompletionCallback temp = *cc;
 204   *cc = PP_BlockUntilComplete();
 205   PP_RunCompletionCallback(&temp, res);
 206 }
 207 /**
 208  * @}
 209  */
 210
 211 #endinl
 212