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 263
